Index: ChangeLog ================================================================== --- ChangeLog +++ ChangeLog @@ -1,5 +1,13 @@ +2013-02-08 Andreas Kupries + + * apps/dtplite: Fixed missing -ibase option in direcotry + * apps/dtplite.man: processing with -merge. Fixed sorting in + generated toc and indices. Plus new feature: -toc for external + toc to place in the output. Bumped to 1.0.4. Updated + documentation. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: apps/dtplite ================================================================== --- apps/dtplite +++ apps/dtplite @@ -1,11 +1,11 @@ #! /bin/sh # -*- tcl -*- \ exec tclsh "$0" ${1+"$@"} # @@ Meta Begin -# Application dtplite 1.0.3 +# Application dtplite 1.0.4 # Meta platform tcl # Meta summary Lightweight DocTools Processor # Meta description This application is a simple processor # Meta description for documents written in the doctools # Meta description markup language. It covers the most @@ -20,38 +20,38 @@ # Meta require textutil::repeat # Meta author Andreas Kupries # Meta license BSD # @@ Meta End -package provide dtplite 1.0.3 +package provide dtplite 1.0.4 # dtp lite - Lightweight DocTools Processor # ======== = ============================== # # Use cases # --------- -# +# # (1) Validation of a single manpage, i.e. checking that it is valid # doctools format. -# +# # (1a) Getting a preliminary version of the formatted output, for # display in a browser, nroff, etc., proofreading the # formatting. -# +# # (2) Generate documentation for a single package, i.e. all the # manpages, plus index and table of contents. -# +# # (3) Generation of unified documentation for several # packages. Especially unified keyword index and table of # contents. This may additionally generate per-package TOCs # as well (Per-package indices don't make sense IMHO). -# +# # Command syntax # -------------- -# +# # Ad 1) dtplite -o output format file -# +# # The option -o specifies where to write the output to. Using # the string "-" as name of the output file causes the tool to # write the generated data to stdout. If $output is a directory # then a file named [[file rootname $file].$format] is written # to the directory. @@ -58,66 +58,80 @@ # Ad 1a) dtplite validate file # # The "validate" format does not generate output at all, only # syntax checking is performed. -# +# # Ad 2) dtplite -o output format directory -# +# # I.e. we distinguish (2) from (1) by the type of the input, # file, or directory. In this situation output has to be a # directory. Use the path "." to place the results into the # current directory. -# +# # We locate _all_ files under directory, i.e. all subdirectories # are scanned as well. We replicate the found directory # structure in the output (See example below). The index and # table of contents are written to the toplevel directory in the # output. The names are hardwired to "toc.$format" and # "index.$format". -# +# # Ad 3) dtplite -merge -o output format directory -# +# # This can be treated as special case of (2). The -merge option # tells it that the output is nested one level deeper, to keep a # global toc and index in the toplevel and to merge the package # toc and index into them. -# +# # This way the global documents are built up incrementally. This # can help us in a future extended installer as well!, extending # a global documentation tree of all installed packages. -# +# # Additional features. -# +# # * As described above the format name is used as the extension # for the generated files. Does it make sense to introduce an # option with which we can overide this, or should we simply # extect that a calling script does a proper renaming of all the # files ? ... The option is better. In HTML output we have # links between the files, and renaming from the outside just # breaks the links. This option is '-ext'. It is ignored if the # output is a single file (fully specified via -o), or stdout. -# +# # -ext extension -# +# # * Most of the formats don't need much/none of customizability. # I.e. text, nroff, wiki, tmml, ... For HTML however some # degree of customizability is required for good output. What # should we given to the user ? -# +# # - Allow setting of a stylesheet. # - Allow integration of custom body header and footer html. # - Allow additional links for the navigation bar. -# +# # Note: The tool generates standard navigation bars to link the # all tocs, indices, and pages together. -# +# # -style file # -header file # -footer file # -nav label url -# +# +# * The application may mis-detect files as doctools input. +# And we cannot always mark them as non-doctools because +# they may be such. Test cases, for example. To exclude +# these we have the option '-exclude' taking a glob pattern. +# Multiple uses of the option accumulate. +# +# -exclude glob +# +# * For tcllib itself we have external tools generating a nicer +# TOC. Use option -toc to specify the doctoc file to use instead +# of generating our own. +# +# -toc path +# # That should be enough to allow the creation of good looking formatted # documentation without getting overly complex in both implementation # and use. package require doctools 1.4.11 ; # 'image' support, -ibase support @@ -300,14 +314,18 @@ variable imap array set imap {} # Database of exclusion patterns. Files matching these are not - # manpages. For example, test files for doctools itself may full + # manpages. For example, test files for doctools itself may fall # under this. variable excl {} + + # Path of a user specified table of contents (doctoc format). + + variable utoc {} } # ### ### ### ######### ######### ######### ## External data and status # @@ -346,21 +364,23 @@ # ?-ext ext? \ # ?-style file? \ # ?-header file? \ # ?-footer file? \ # ?-nav label url?... \ +# ?-exclude glob?... \ +# ?-toc path? \ # format inputpath ## proc ::dtplite::processCmdline {} { global argv variable output ; variable style ; variable stdout variable format ; variable header ; variable single variable input ; variable footer ; variable mode - variable ext ; variable nav ; variable merge - variable module ; variable excl + variable ext ; variable nav ; variable merge + variable module ; variable excl ; variable utoc # Process the options, perform basic validation. while {[llength $argv]} { set opt [lindex $argv 0] @@ -374,10 +394,14 @@ set merge 1 set argv [lrange $argv 1 end] } elseif {[string equal $opt "-ext"]} { if {[llength $argv] < 2} Usage set ext [lindex $argv 1] + set argv [lrange $argv 2 end] + } elseif {[string equal $opt "-toc"]} { + if {[llength $argv] < 2} Usage + set utoc [lindex $argv 1] set argv [lrange $argv 2 end] } elseif {[string equal $opt "-exclude"]} { if {[llength $argv] < 2} Usage lappend excl [lindex $argv 1] set argv [lrange $argv 2 end] @@ -699,10 +723,11 @@ variable input variable out variable module variable meta variable format + variable utoc # Phase 0. Find the documents to convert. # Phase I. Collect meta data, and compute the map from input to # ........ output files. This is also the map for the symbolic # ........ references. We extend an existing map (required for use @@ -712,17 +737,24 @@ # .......... information. MapImages set files [LocateManpages $input] if {![llength $files]} { - ArgError "Module \"$module\" has no files to process." + ArgError "Module \"$module\" has no files to process." } MetadataGet $files StyleMakeLocal - TocWrite toc index [TocGenerate [TocGet $module toc]] + if {$utoc ne {}} { + if {[file exists $utoc]} { + set utoc [Get $utoc] + } + TocWrite toc index $utoc + } else { + TocWrite toc index [TocGenerate [TocGet $module toc]] + } IdxWrite index toc [IdxGenerate $module [IdxGet]] dt configure -module $module XrefGet XrefSetup dt @@ -760,10 +792,11 @@ variable out variable module variable meta variable output variable format + variable utoc # Phase 0. Find the documents to process. # Phase I. Collect meta data, and compute the map from input to # ........ output files. This is also the map for the symbolic # ........ references. We extend an existing map (required for use @@ -775,20 +808,27 @@ # .......... to boths tocs and the index. MapImages set files [LocateManpages $input] if {![llength $files]} { - ArgError "Module \"$module\" has no files to process." + ArgError "Module \"$module\" has no files to process." } MetadataGet $files $module StyleMakeLocal $module set localtoc [TocGet $module $module/toc] TocWrite $module/toc index [TocGenerate $localtoc] [TocMap $localtoc] - TocWrite toc index [TocGenerate [TocMergeSaved $localtoc]] - IdxWrite index toc [IdxGenerate {} [IdxGetSaved index]] + if {$utoc ne {}} { + if {[file exists $utoc]} { + set utoc [Get $utoc] + } + TocWrite toc index $utoc + } else { + TocWrite toc index [TocGenerate [TocMergeSaved $localtoc]] + } + IdxWrite index toc [IdxGenerate {} [IdxGetSaved index]] dt configure -module $module XrefGetSaved XrefSetup dt FooterSetup dt @@ -796,11 +836,11 @@ foreach f [lsort -dict $files] { puts stdout \t$f set o $out($f) - dt configure -file [At $o] + dt configure -file [At $o] -ibase $input/$f NavbuttonPush {Keyword Index} [Output index] $o NavbuttonPush {Table Of Contents} [Output $module/toc] $o NavbuttonPush {Main Table Of Contents} [Output toc] $o HeaderSetup dt @@ -932,11 +972,11 @@ proc ::dtplite::TocGenerate {data} { # Handling single and multiple divisions. # single div => div is full toc # multi div => place divs into the toc in alpha order. # - # Sort toc (each division) by label. + # Sort toc (each division) by label (index 1). # Write as doctoc. array set toc $data TagsBegin @@ -947,11 +987,11 @@ set desc [lindex $data 0] set data [lindex [lindex $data 1] 1] TocAlign mxf mxl $data Tag+ toc_begin [list {Table Of Contents} $desc] - foreach item [lsort -dict -index 2 $data] { + foreach item [lsort -dict -index 1 $data] { foreach {symfile label desc} $item break Tag+ item \ [FmtR mxf $symfile] \ [FmtR mxl $label] \ [list $desc] @@ -961,11 +1001,11 @@ foreach desc [lsort -dict [array names toc]] { foreach {ref div} $toc($desc) break TocAlign mxf mxl $div Tag+ division_start [list $desc [Output $ref]] - foreach item [lsort -dict -index 2 $div] { + foreach item [lsort -dict -index 1 $div] { foreach {symfile label desc} $item break Tag+ item \ [FmtR mxf $symfile] \ [FmtR mxl $label] \ [list $desc] @@ -1098,11 +1138,11 @@ foreach k [lsort -dict [array names keys]] { IdxAlign mxf $keys($k) Tag+ key [list $k] - foreach v [lsort -dict -index 0 $keys($k)] { + foreach v [lsort -dict -index 1 $keys($k)] { foreach {file label} $v break Tag+ manpage [FmtR mxf $file] [list $label] } } Index: apps/dtplite.man ================================================================== --- apps/dtplite.man +++ apps/dtplite.man @@ -222,10 +222,20 @@ 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. +[para] + +When used multiple times only the last definition is relevant. + + +[opt_def -toc path] + +This option specifies a doctoc file to use for the table of contents +instead of generating our own. + [para] When used multiple times only the last definition is relevant. ADDED embedded/man/files/apps/dtplite.n Index: embedded/man/files/apps/dtplite.n ================================================================== --- /dev/null +++ embedded/man/files/apps/dtplite.n @@ -0,0 +1,565 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/dtplite.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "dtplite" n 1.0 tcllib "Documentation toolbox" +.BS +.SH NAME +dtplite \- Lightweight DocTools Markup Processor +.SH SYNOPSIS +\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputfile\fR +.sp +\fBdtplite\fR \fBvalidate\fR \fIinputfile\fR +.sp +\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR +.sp +\fBdtplite\fR \fB-merge\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR +.sp +.BE +.SH DESCRIPTION +.PP +The application described by this document, \fBdtplite\fR, is the +successor to the extremely simple \fBmpexpand\fR. Influenced in its +functionality by the \fBdtp\fR doctools processor it is much more +powerful than \fBmpexpand\fR, yet still as easy to use; definitely +easier than \fBdtp\fR with its myriad of subcommands and options. +.PP +\fBdtplite\fR is based upon the package \fBdoctools\fR, like +the other two processors. +.SS "USE CASES" +\fBdtplite\fR was written with the following three use cases in +mind. +.PP +.IP [1] +Validation of a single document, i.e. checking that it was written in +valid doctools format. This mode can also be used to get a preliminary +version of the formatted output for a single document, for display in +a browser, nroff, etc., allowing proofreading of the formatting. +.IP [2] +Generation of the formatted documentation for a single package, +i.e. all the manpages, plus a table of contents and an index of +keywords. +.IP [3] +An extension of the previous mode of operation, a method for the easy +generation of one documentation tree for several packages, and +especially of a unified table of contents and keyword index. +.PP +.PP +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. +.PP +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 \fBOPTIONS\fR) the last +two have internal processing which make them specific to HTML. +.SS "COMMAND LINE" +.TP +\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputfile\fR +This is the form for use case [1]. The \fIoptions\fR will be +explained later, in section \fBOPTIONS\fR. +.RS +.TP +path \fIoutput\fR (in) +This argument specifies where to write the generated document. It can +be the path to a file or directory, or \fB-\fR. +The last value causes the application to write the generated +documented to \fBstdout\fR. +.sp +If the \fIoutput\fR 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 \fIinputfile\fR, +the \fIformat\fR, and the value given to option \fB-ext\fR (if +present). +.TP +(path|handle) \fIformat\fR (in) +This argument specifies the formatting engine to use when processing +the input, and thus the format of the generated document. See section +\fBFORMATS\fR for the possibilities recognized by the application. +.TP +path \fIinputfile\fR (in) +This argument specifies the path to the file to process. It has to +exist, must be readable, and written in \fIdoctools\fR format. +.RE +.sp +.TP +\fBdtplite\fR \fBvalidate\fR \fIinputfile\fR +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. +.TP +\fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR +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 \fIoutput\fR, which now has to be the path to an existing and +writable directory. +.sp +The input documents are all files in \fIinputdirectory\fR or any of +its subdirectories which were recognized by \fBfileutil::fileType\fR +as containing text in \fIdoctools\fR format. +.TP +\fBdtplite\fR \fB-merge\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputdirectory\fR +This is the form for use case [3]. The only difference to the +form for use case [2] is the additional option \fB-merge\fR. +.sp +Each such call will merge the generated documents coming from +processing the input documents under \fIinputdirectory\fR or any of +its subdirectories to the files under \fIoutput\fR. 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). +.PP +.SS OPTIONS +This section describes all the options available to the user of the +application, with +the exception of the options \fB-o\fR and \fB-merge\fR. These +two were described already, in section \fBCOMMAND LINE\fR. +.PP +.TP +\fB-exclude\fR 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. +.TP +\fB-ext\fR 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 \fIformat\fR as the extension +by default. This option here will override this however, forcing it to +use \fIstring\fR as the file extension. This option is ignored if the +name of the output file is fully specified through option \fB-o\fR. +.sp +When used multiple times only the last definition is relevant. +.TP +\fB-header\fR file +This option can be used if and only if the selected \fIformat\fR +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 +\fB\fR. +If navigation buttons are present (see option \fB-nav\fR below), +then the HTML generated for them is appended to the header data +originating here before the final assignment to the parameter. +.sp +When used multiple times only the last definition is relevant. +.TP +\fB-footer\fR file +Like \fB-header\fR, except that: Any navigation buttons are ignored, +the corresponding required engine parameter is named "footer", and the +data is inserted just before the tag \fB\fR. +.sp +When used multiple times only the last definition is relevant. +.TP +\fB-style\fR file +This option can be used if and only if the selected \fIformat\fR +provides an engine parameter named "meta". When specified it will +generate a piece of HTML code declaring the \fIfile\fR 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 \fB\fR. +.sp +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. +.sp +When used multiple times only the last definition is relevant. +.TP +\fB-toc\fR path +This option specifies a doctoc file to use for the table of contents +instead of generating our own. +.sp +When used multiple times only the last definition is relevant. +.TP +\fB-nav\fR label url +Use this option to specify a navigation button with \fIlabel\fR to +display and the \fIurl\fR to link to. This option can be used if and +only if the selected \fIformat\fR provides an engine parameter named +"header". The HTML generated for this is appended to whatever data we +got from option \fB-header\fR before it is inserted into the +generated documents. +.sp +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. +.PP +.SS FORMATS +At first the \fIformat\fR 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. +.PP +\fINote a limitation\fR: 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. +\fIdoctools_api\fR, but for \fIdoctoc_api\fR and \fIdocidx_api\fR +as well. Otherwise the generation of a table of contents and of a +keyword index will fail. +.PP +List of predefined formats, i.e. as provided by the +package \fBdoctools\fR: +.PP +.TP +\fBnroff\fR +The processor generates *roff output, the standard format for unix +manpages. +.TP +\fBhtml\fR +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. +.TP +\fBtmml\fR +The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML. +.TP +\fBlatex\fR +The processor generates LaTeX output. +.TP +\fBwiki\fR +The processor generates Wiki markup as understood by \fBwikit\fR. +.TP +\fBlist\fR +The processor extracts the information provided by \fBmanpage_begin\fR. +This format is used internally to extract the meta data from which +both table of contents and keyword index are derived from. +.TP +\fBnull\fR +The processor does not generate any output. This is equivalent to +\fBvalidate\fR. +.PP +.SS "DIRECTORY STRUCTURES" +In this section we describe the directory structures generated by the +application under \fIoutput\fR when processing all documents in an +\fIinputdirectory\fR. In other words, this is only relevant to the use +cases [2] and [3]. +.TP +[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. +.CS + + + output/ + toc.html + index.html + files/ + path/to/FOO.html + +.CE +.IP +The last line in the example shows the document +generated for a file FOO located at +.CS + + + inputdirectory/path/to/FOO + +.CE +.TP +[3] +When merging many packages into a unified set of documents the +generated directory structure is a bit deeper: +.CS + + + output + .toc + .idx + .tocdoc + .idxdoc + .xrf + toc.html + index.html + FOO1/ + ... + FOO2/ + toc.html + files/ + path/to/BAR.html + +.CE +.IP +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. +.sp +The files "\fI.toc\fR", "\fI.idx\fR", and "\fI.xrf\fR" 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. +.sp +The files "\fI.tocdoc\fR", and "\fI.idxdoc\fR", 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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +docidx introduction, doctoc introduction, doctools introduction +.SH KEYWORDS +HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries + +.fi ADDED embedded/man/files/apps/nns.n Index: embedded/man/files/apps/nns.n ================================================================== --- /dev/null +++ embedded/man/files/apps/nns.n @@ -0,0 +1,358 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nns.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nns" n 1.1 tcllib "Name service facility" +.BS +.SH NAME +nns \- Name service facility, Commandline Client Application +.SH SYNOPSIS +\fBnns\fR \fBbind\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? \fIname\fR \fIdata\fR +.sp +\fBnns\fR \fBsearch\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? ?\fB-continuous\fR? ?\fIpattern\fR? +.sp +\fBnns\fR \fBident\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? +.sp +\fBnns\fR \fBwho\fR +.sp +.BE +.SH DESCRIPTION +.PP +Please read \fIName service facility, introduction\fR first. +.PP +The application described by this document, \fBnns\fR, is a simple +command line client for the nano name service facility provided by the +Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR. +Beyond that the application's sources also serve as an example of how +to use the client package \fBnameserv\fR. All abilities of a +client are covered, from configuration to registration of names to +searching. +.PP +This name service facility has nothing to do with the Internet's +\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the +reader is looking for a package dealing with that please see either of +the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib +too. +.SS "USE CASES" +\fBnns\fR was written with the following two main use cases in +mind. +.PP +.IP [1] +Registration of a name/data pair in the name service. +.IP [2] +Searching the name service for entries matching a glob pattern. +.PP +.PP +Beyond the above we also want to be able to identify the client, and +get information about the name service. +.SS "COMMAND LINE" +.TP +\fBnns\fR \fBbind\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? \fIname\fR \fIdata\fR +This form registers the \fIname\fR/\fIdata\fR pair in the specified +name service. In this form the command will \fInot\fR 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 \fIname\fR/\fIdata\fR pair when the +connection is restored. +.sp +The options to specify the name service will be explained later, in +section \fBOPTIONS\fR. +.TP +\fBnns\fR \fBsearch\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? ?\fB-continuous\fR? ?\fIpattern\fR? +This form searches the specified name service for entries matching the +glob-\fIpattern\fR and prints them to stdout, with each entry on its +own line. If no pattern is specified it defaults to \fB*\fR, +matching everything. +.sp +The options to specify the name service will be explained later, in +section \fBOPTIONS\fR. +.sp +If the option \fB-continuous\fR 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. +.TP +\fBnns\fR \fBident\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? +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. +.sp +The options to specify the name service will be explained later, in +section \fBOPTIONS\fR. +.TP +\fBnns\fR \fBwho\fR +This form prints name, version, and protocol version of the +application to stdout. +.PP +.SS OPTIONS +This section describes all the options available to the user of the +application +.PP +.TP +\fB-host\fR name|ipaddress +If this option is not specified it defaults to \fBlocalhost\fR. It +specifies the name or ip-address of the host the name service to talk +to is running on. +.TP +\fB-port\fR number +If this option is not specified it defaults to \fB38573\fR. It +specifies the TCP port the name service to talk to is listening on for +requests. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +nameserv(n), nameserv::common(n) +.SH KEYWORDS +application, client, name service +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries + +.fi ADDED embedded/man/files/apps/nnsd.n Index: embedded/man/files/apps/nnsd.n ================================================================== --- /dev/null +++ embedded/man/files/apps/nnsd.n @@ -0,0 +1,316 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nnsd.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nnsd" n 1.0.1 tcllib "Name service facility" +.BS +.SH NAME +nnsd \- Name service facility, Commandline Server Application +.SH SYNOPSIS +\fBnnsd\fR ?\fB-localonly\fR \fIflag\fR? ?\fB-port\fR \fIport\fR? +.sp +.BE +.SH DESCRIPTION +.PP +Please read \fIName service facility, introduction\fR first. +.PP +The application described by this document, \fBnns\fR, is a simple +command line server for the nano name service facility provided by the +Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR. +Beyond that the application's sources also serve as an example of how +to use the server package \fBnameserv::server\fR. +.PP +This name service facility has nothing to do with the Internet's +\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the +reader is looking for a package dealing with that please see either of +the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib +too. +.SS "USE CASES" +\fBnnsd\fR was written with the following main use case in +mind. +.PP +.IP [1] +Run a nano name service on some host. +.PP +.PP +.SS "COMMAND LINE" +.TP +\fBnnsd\fR ?\fB-localonly\fR \fIflag\fR? ?\fB-port\fR \fIport\fR? +The command configures a server per the specified options and starts +it. The command will not exit on its, as it keeps the name service +database wholly in memory. The user has to kill it explicitly, eithre +by sending a a signal, or through the job-control facilities of the +shell in use. +.sp +The options to configure the name service are explained in section +\fBOPTIONS\fR. +.PP +.SS OPTIONS +This section describes all the options available to the user of the +application +.PP +.TP +\fB-localonly\fR bool +If this option is not specified it defaults to \fBtrue\fR, 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 \fBfalse\fR. +.TP +\fB-port\fR number +If this option is not specified it defaults to \fB38573\fR. It +specifies the TCP port the server has to listen on for requests. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +nameserv::common(n), nameserv::server(n) +.SH KEYWORDS +application, name service, server +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries + +.fi ADDED embedded/man/files/apps/nnslog.n Index: embedded/man/files/apps/nnslog.n ================================================================== --- /dev/null +++ embedded/man/files/apps/nnslog.n @@ -0,0 +1,319 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/nnslog.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nnslog" n 1.0 tcllib "Name service facility" +.BS +.SH NAME +nnslog \- Name service facility, Commandline Logging Client Application +.SH SYNOPSIS +\fBnnslog\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? +.sp +.BE +.SH DESCRIPTION +.PP +Please read \fIName service facility, introduction\fR first. +.PP +The application described by this document, \fBnnslog\fR, is a +simple command line client for the nano name service facility provided +by the Tcllib packages \fBnameserv\fR, and \fBnameserv::server\fR. +.PP +It essentially implements "\fBnns\fR 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 \fBstdout\fR. +.PP +This name service facility has nothing to do with the Internet's +\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the +reader is looking for a package dealing with that please see either of +the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib +too. +.SS "USE CASES" +\fBnnslog\fR was written with the following main use case in mind. +.PP +.IP [1] +Monitoring the name service for all changes and logging them in a text +terminal. +.PP +.PP +.SS "COMMAND LINE" +.TP +\fBnnslog\fR ?\fB-host\fR \fIhost\fR? ?\fB-port\fR \fIport\fR? +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. +.sp +The options to specify the name service will be explained later, in +section \fBOPTIONS\fR. +.PP +.SS OPTIONS +This section describes all the options available to the user of the +application +.TP +\fB-host\fR name|ipaddress +If this option is not specified it defaults to \fBlocalhost\fR. It +specifies the name or ip-address of the host the name service to talk +to is running on. +.TP +\fB-port\fR number +If this option is not specified it defaults to \fB38573\fR. It +specifies the TCP port the name service to talk to is listening on for +requests. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +nameserv(n), nameserv::common(n) +.SH KEYWORDS +application, client, name service +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2008 Andreas Kupries + +.fi ADDED embedded/man/files/apps/page.n Index: embedded/man/files/apps/page.n ================================================================== --- /dev/null +++ embedded/man/files/apps/page.n @@ -0,0 +1,648 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/page.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page" n 1.0 tcllib "Development Tools" +.BS +.SH NAME +page \- Parser Generator +.SH SYNOPSIS +\fBpage\fR ?\fIoptions\fR...? ?\fIinput\fR ?\fIoutput\fR?? +.sp +.BE +.SH DESCRIPTION +.PP +The application described by this document, \fBpage\fR, is actually +not just a parser generator, as the name implies, but a generic tool +for the execution of arbitrary transformations on texts. +.PP +Its genericity comes through the use of \fIplugins\fR 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 \fIpackrat parsers\fR) from grammar +specifications (\fIParsing Expression Grammars\fR). +.PP +\fBpage\fR is written on top of the package +\fBpage::pluginmgr\fR, wrapping its functionality into a command +line based application. All the other \fBpage::*\fR packages are +plugin and/or supporting packages for the generation of parsers. The +parsers themselves are based on the packages \fBgrammar::peg\fR, +\fBgrammar::peg::interp\fR, and \fBgrammar::mengine\fR. +.SS "COMMAND LINE" +.TP +\fBpage\fR ?\fIoptions\fR...? ?\fIinput\fR ?\fIoutput\fR?? +This is general form for calling \fBpage\fR. The application will +read the contents of the file \fIinput\fR, process them under the +control of the specified \fIoptions\fR, and then write the result to +the file \fIoutput\fR. +.sp +If \fIinput\fR is the string \fB-\fR the data to process will be +read from \fBstdin\fR instead of a file. Analogously the result will +be written to \fBstdout\fR instead of a file if \fIoutput\fR is the +string \fB-\fR. A missing output or input specification causes the +application to assume \fB-\fR. +.sp +The detailed specifications of the recognized \fIoptions\fR are +provided in section \fBOPTIONS\fR. +.RS +.TP +path \fIinput\fR (in) +This argument specifies the path to the file to be processed by the +application, or \fB-\fR. The last value causes the application to +read the text from \fBstdin\fR. Otherwise it has to exist, and be +readable. If the argument is missing \fB-\fR is assumed. +.TP +path \fIoutput\fR (in) +This argument specifies where to write the generated text. It can be +the path to a file, or \fB-\fR. The last value causes the +application to write the generated documented to \fBstdout\fR. +.sp +If the file \fIoutput\fR 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. +.sp +If the argument is missing \fB-\fR is assumed. +.RE +.PP +.SS OPERATION +... reading ... transforming ... writing - plugins - pipeline ... +.SS OPTIONS +This section describes all the options available to the user of the +application. Options are always processed in order. I.e. of both +\fB--help\fR and \fB--version\fR are specified the option +encountered first has precedence. +.PP +Unknown options specified before any of the options \fB-rd\fR, +\fB-wr\fR, or \fB-tr\fR 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. +.PP +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 +.PP +.CS + +-c peg +.CE +.PP +And now the recognized options and their arguments, if they have any: +.PP +.TP +\fB--help\fR +.TP +\fB-h\fR +.TP +\fB-?\fR +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. +.TP +\fB--version\fR +.TP +\fB-V\fR +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. +.TP +\fB-P\fR +This option signals the application to activate visual feedback while +reading the input. +.TP +\fB-T\fR +This option signals the application to collect statistics while +reading the input and to print them after reading has completed, +before processing started. +.TP +\fB-D\fR +This option signals the application to activate logging in the Safe +base, for the debugging of problems with plugins. +.TP +\fB-r\fR parser +.TP +\fB-rd\fR parser +.TP +\fB--reader\fR parser +These options specify the plugin the application has to use for +reading the \fIinput\fR. If the options are used multiple times the +last one will be used. +.TP +\fB-w\fR generator +.TP +\fB-wr\fR generator +.TP +\fB--writer\fR generator +These options specify the plugin the application has to use for +generating and writing the final \fIoutput\fR. If the options are used +multiple times the last one will be used. +.TP +\fB-t\fR process +.TP +\fB-tr\fR process +.TP +\fB--transform\fR process +These options specify a plugin to run on the input. In contrast to +readers and writers each use will \fInot\fR 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 +\fB-p\fR or \fB-a\fR. The initial default is to append the new +transformations. +.TP +\fB-a\fR +.TP +\fB--append\fR +These options signal the application that all following +transformations should be added at the end of the list of +transformations. +.TP +\fB-p\fR +.TP +\fB--prepend\fR +These options signal the application that all following +transformations should be added at the beginning of the list of +transformations. +.TP +\fB--reset\fR +This option signals the application to clear the list of +transformations. This is necessary to wipe out the default +transformations used. +.TP +\fB-c\fR file +.TP +\fB--configuration\fR 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. +.sp +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. +.PP +.SS PLUGINS +\fBpage\fR 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 \fBpage\fR. The +exact APIs provided to and expected from the plugins can be found in +the documentation for \fBpage::pluginmgr\fR, for those who wish to +write their own plugins. +.PP +Plugins are specified as arguments to the options \fB-r\fR, +\fB-w\fR, \fB-t\fR, \fB-c\fR, and their equivalent longer +forms. See the section \fBOPTIONS\fR for reference. +.PP +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 +\fBPLUGIN LOCATIONS\fR for a listing of all paths and their +sources. +.PP +.TP +\fB-c\fR \fIname\fR +Configurations. The name of the package for the plugin \fIname\fR is +"page::config::\fIname\fR". +.sp +We have one predefined plugin: +.RS +.TP +\fIpeg\fR +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: +.sp +.CS + + + --reset + --append + --reader peg + --transform reach + --transform use + --writer me + +.CE +.sp +.RE +.TP +\fB-r\fR \fIname\fR +Readers. The name of the package for the plugin \fIname\fR is +"page::reader::\fIname\fR". +.sp +We have five predefined plugins: +.RS +.TP +\fIpeg\fR +Interprets the input as a parsing expression grammar (\fIPEG\fR) 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. +.TP +\fIhb\fR +Interprets the input as Tcl code as generated by the writer plugin +\fIhb\fR and generates its tree representation. +.TP +\fIser\fR +Interprets the input as the serialization of a PEG, as generated by +the writer plugin \fIser\fR, using the package +\fBgrammar::peg\fR. +.TP +\fIlemon\fR +Interprets the input as a grammar specification as understood by +Richard Hipp's \fILEMON\fR 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. +.TP +\fItreeser\fR +Interprets the input as the serialization of a +\fBstruct::tree\fR. It is validated as such, +but nothing else. It is \fInot\fR assumed to +be the tree representation of a grammar. +.RE +.TP +\fB-w\fR \fIname\fR +Writers. The name of the package for the plugin \fIname\fR is +"page::writer::\fIname\fR". +.sp +We have eight predefined plugins: +.RS +.TP +\fIidentity\fR +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. +.TP +\fInull\fR +Generates nothing, and ignores the incoming data structure. +.TP +\fItree\fR +Assumes that the incoming data structure is a \fBstruct::tree\fR +and generates an indented textual representation of all nodes, their +parental relationships, and their attribute information. +.TP +\fIpeg\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR 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. +.TP +\fItpc\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR or other other grammar and writes out Tcl code defining a +package which defines a \fBgrammar::peg\fR object containing the +grammar when it is loaded into an interpreter. +.TP +\fIhb\fR +This is like the writer plugin \fItpc\fR, but it writes only the +statements which define stat expression and grammar rules. The code +making the result a package is left out. +.TP +\fIser\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR or other other grammar, transforms it internally into a +\fBgrammar::peg\fR object and writes out its serialization. +.TP +\fIme\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR 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 \fBgrammar::mengine\fR. +.RE +.TP +\fB-t\fR \fIname\fR +Transformers. The name of the package for the plugin \fIname\fR is +"page::transform::\fIname\fR". +.sp +We have two predefined plugins: +.RS +.TP +\fIreach\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR 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. +.TP +\fIuse\fR +Assumes that the incoming data structure is a tree representation of a +\fIPEG\fR or other other grammar. It determines which nonterminal +symbols and rules are able to generate a \fIfinite\fR 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. +.RE +.PP +.SS "PLUGIN LOCATIONS" +The application-specific paths searched by \fBpage\fR either are, +or come from: +.PP +.IP [1] +The directory "\fI~/.page/plugin\fR" +.IP [2] +The environment variable \fIPAGE_PLUGINS\fR +.IP [3] +The registry entry \fIHKEY_LOCAL_MACHINE\\SOFTWARE\\PAGE\\PLUGINS\fR +.IP [4] +The registry entry \fIHKEY_CURRENT_USER\\SOFTWARE\\PAGE\\PLUGINS\fR +.PP +.PP +The type-specific paths searched by \fBpage\fR either are, or come +from: +.PP +.IP [1] +The directory "\fI~/.page/plugin/\fR" +.IP [2] +The environment variable \fIPAGE__PLUGINS\fR +.IP [3] +The registry entry \fIHKEY_LOCAL_MACHINE\\SOFTWARE\\PAGE\\\\PLUGINS\fR +.IP [4] +The registry entry \fIHKEY_CURRENT_USER\\SOFTWARE\\PAGE\\\\PLUGINS\fR +.PP +.PP +Where the placeholder \fI\fR is always one of the values below, +properly capitalized. +.IP [1] +reader +.IP [2] +writer +.IP [3] +transform +.IP [4] +config +.PP +.PP +The registry entries are specific to the Windows(tm) platform, all +other platforms will ignore them. +.PP +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). +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +page::pluginmgr +.SH KEYWORDS +parser generator, text processing +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries + +.fi ADDED embedded/man/files/apps/tcldocstrip.n Index: embedded/man/files/apps/tcldocstrip.n ================================================================== --- /dev/null +++ embedded/man/files/apps/tcldocstrip.n @@ -0,0 +1,406 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/apps/tcldocstrip.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcldocstrip" n 1.0 tcllib "Textprocessing toolbox" +.BS +.SH NAME +tcldocstrip \- Tcl-based Docstrip Processor +.SH SYNOPSIS +\fBtcldocstrip\fR \fIoutput\fR ?options? \fIinput\fR ?\fIguards\fR? +.sp +\fBtcldocstrip\fR ?options? \fIoutput\fR (?options? \fIinput\fR \fIguards\fR)... +.sp +\fBtcldocstrip\fR \fB-guards\fR \fIinput\fR +.sp +.BE +.SH DESCRIPTION +.PP +The application described by this document, \fBtcldocstrip\fR, is a +relative of \fBdocstrip\fR, a simple literate programming tool for +LaTeX. +.PP +\fBtcldocstrip\fR is based upon the package \fBdocstrip\fR. +.SS "USE CASES" +\fBtcldocstrip\fR was written with the following three use cases in +mind. +.PP +.IP [1] +Conversion of a single input file according to the listed guards into +the stripped output. This handles the most simple case of a set of +guards specifying a single document found in a single input file. +.IP [2] +Stitching, or the assembly of an output from several sets of guards, +in a specific order, and possibly from different files. This is the +second common case. One document spread over several inputs, and/or +spread over different guard sets. +.IP [3] +Extraction and listing of all the unique guard expressions and guards +used within a document to help a person which did not author the +document in question in familiarizing itself with it. +.PP +.SS "COMMAND LINE" +.TP +\fBtcldocstrip\fR \fIoutput\fR ?options? \fIinput\fR ?\fIguards\fR? +This is the form for use case [1]. It converts the \fIinput\fR +file according to the specified \fIguards\fR and options. The result +is written to the named \fIoutput\fR file. +Usage of the string \fB-\fR as the name of the output signals that +the result should be written to \fBstdout\fR. The guards are +document-specific and have to be known to the caller. The +\fIoptions\fR will be explained later, in section \fBOPTIONS\fR. +.RS +.TP +path \fIoutput\fR (in) +This argument specifies where to write the generated document. It can +be the path to a file or directory, or \fB-\fR. +The last value causes the application to write the generated +documented to \fBstdout\fR. +.sp +If the \fIoutput\fR does not exist then [file dirname $output] +has to exist and must be a writable directory. +.TP +path \fIinputfile\fR (in) +This argument specifies the path to the file to process. It has to +exist, must be readable, and written in \fIdocstrip\fR format. +.RE +.sp +.TP +\fBtcldocstrip\fR ?options? \fIoutput\fR (?options? \fIinput\fR \fIguards\fR)... +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. +.sp +It extracts data from the various \fIinput\fR files, according to the +specified \fIoptions\fR and \fIguards\fR, and writes the result to the +given \fIoutput\fR, 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 \fB-\fR as output +causes the application to write to stdout. +Using the string \fB.\fR 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. +.TP +\fBtcldocstrip\fR \fB-guards\fR \fIinput\fR +This is the form for use case [3]. +It determines the guards, and unique guard expressions used within the +provided \fIinput\fR document. The found strings are written to +stdout, one string per line. +.PP +.SS OPTIONS +This section describes all the options available to the user of the +application, with the exception of the option \fB-guards\fR. This +option was described already, in section \fBCOMMAND LINE\fR. +.PP +.TP +\fB-metaprefix\fR string +This option is inherited from the command \fBdocstrip::extract\fR +provided by the package \fBdocstrip\fR. +.sp +It specifies the string by which the '%%' prefix of a metacomment line +will be replaced. Defaults to '%%'. For Tcl code this would typically +be '#'. +.TP +\fB-onerror\fR mode +This option is inherited from the command \fBdocstrip::extract\fR +provided by the package \fBdocstrip\fR. +.sp +It controls what will be done when a format error in the \fItext\fR +being processed is detected. The settings are: +.RS +.TP +\fBignore\fR +Just ignore the error; continue as if nothing happened. +.TP +\fBputs\fR +Write an error message to \fBstderr\fR, then continue processing. +.TP +\fBthrow\fR +Throw an error. \fB::errorCode\fR is set to a list whose first element +is \fBDOCSTRIP\fR, second element is the type of error, and third +element is the line number where the error is detected. This is the +default. +.RE +.TP +\fB-trimlines\fR bool +This option is inherited from the command \fBdocstrip::extract\fR +provided by the package \fBdocstrip\fR. +.sp +Controls whether \fIspaces\fR at the end of a line should be trimmed +away before the line is processed. Defaults to \fBtrue\fR. +.TP +\fB-preamble\fR text +.TP +\fB-postamble\fR text +.TP +\fB-nopreamble\fR +.TP +\fB-nopostamble\fR +The -no*amble options deactivate file pre- and postambles altogether, +whereas the -*amble options specify the \fIuser\fR 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. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category \fIdocstrip\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +application and/or documentation. +.SH "SEE ALSO" +docstrip +.SH KEYWORDS +.dtx, LaTeX, conversion, docstrip, documentation, literate programming, markup, source +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries + +.fi ADDED embedded/man/files/modules/aes/aes.n Index: embedded/man/files/modules/aes/aes.n ================================================================== --- /dev/null +++ embedded/man/files/modules/aes/aes.n @@ -0,0 +1,388 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/aes/aes.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005, Pat Thoyts +'\" Copyright (c) 2012, Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "aes" n 1.1 tcllib "Advanced Encryption Standard (AES)" +.BS +.SH NAME +aes \- Implementation of the AES block cipher +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBaes ?1.1?\fR +.sp +\fB::aes::aes\fR ?\fI-mode [ecb|cbc]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-hex\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? [ \fI-in channel\fR | ?\fB--\fR? \fIdata\fR ] +.sp +\fB::aes::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR +.sp +\fB::aes::Encrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::aes::Decrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::aes::Reset\fR \fIKey\fR \fIiv\fR +.sp +\fB::aes::Final\fR \fIKey\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::aes::aes\fR ?\fI-mode [ecb|cbc]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-hex\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? [ \fI-in channel\fR | ?\fB--\fR? \fIdata\fR ] +Perform the \fBaes\fR algorithm on either the data provided +by the argument or on the data read from the \fI-in\fR channel. If +an \fI-out\fR channel is given then the result will be written to +this channel. +.sp +The \fI-key\fR 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. +.sp +The \fI-mode\fR and \fI-dir\fR options are optional and default to cbc +mode and encrypt respectively. The initialization vector \fI-iv\fR +takes a 16 byte binary argument which defaults to all zeros. +See \fBMODES OF OPERATION\fR for more about available modes and +their uses. +.sp +AES is a 128-bit block cipher. This means that the data must be +provided in units that are a multiple of 16 bytes. +.PP +.SH "PROGRAMMING INTERFACE" +Internal state is maintained in an opaque structure that is returned +from the \fBInit\fR 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 \fBReset\fR function with a new +initialization vector value. +.TP +\fB::aes::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR +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 \fBMODES OF OPERATION\fR for details about cipher modes. +.TP +\fB::aes::Encrypt\fR \fIKey\fR \fIdata\fR +Use a prepared key acquired by calling \fBInit\fR 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. +.TP +\fB::aes::Decrypt\fR \fIKey\fR \fIdata\fR +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. +.TP +\fB::aes::Reset\fR \fIKey\fR \fIiv\fR +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. +.TP +\fB::aes::Final\fR \fIKey\fR +This should be called to clean up resources associated with \fIKey\fR. +Once this function has been called the key may not be used again. +.PP +.SH "MODES OF OPERATION" +.TP +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. +.TP +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. +.PP +.SH EXAMPLES +.CS + + +% set nil_block [string repeat \\\\0 16] +% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block +66e94bd4ef8a2c3b884cfa59ca342b2e + +.CE +.CS + + +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 + +.CE +.SH REFERENCES +.IP [1] +"Advanced Encryption Standard", +Federal Information Processing Standards Publication 197, 2001 +(\fIhttp://csrc.nist.gov/publications/fips/fips197/fips-197.pdf\fR) +.PP +.SH AUTHORS +Thorsten Schloermann, Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIaes\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +blowfish(n), des(n), md5(n), sha1(n) +.SH KEYWORDS +aes, block cipher, data integrity, encryption, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2005, Pat Thoyts +Copyright (c) 2012, Andreas Kupries + +.fi ADDED embedded/man/files/modules/amazon-s3/S3.n Index: embedded/man/files/modules/amazon-s3/S3.n ================================================================== --- /dev/null +++ embedded/man/files/modules/amazon-s3/S3.n @@ -0,0 +1,1598 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/amazon-s3/S3.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Copyright 2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms. +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "S3" n 1.0.0 tcllib "Amazon S3 Web Service Utilities" +.BS +.SH NAME +S3 \- Amazon S3 Web Service Interface +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsha1 1.0\fR +.sp +package require \fBmd5 2.0\fR +.sp +package require \fBbase64 2.3\fR +.sp +package require \fBxsxp 1.0\fR +.sp +\fBS3::Configure\fR ?\fB-reset\fR \fIboolean\fR? ?\fB-retries\fR \fIinteger\fR? ?\fB-accesskeyid\fR \fIidstring\fR? ?\fB-secretaccesskey\fR \fIidstring\fR? ?\fB-service-access-point\fR \fIFQDN\fR? ?\fB-use-tls\fR \fIboolean\fR? ?\fB-default-compare\fR \fIalways|never|exists|missing|newer|date|checksum|different\fR? ?\fB-default-separator\fR \fIstring\fR? ?\fB-default-acl\fR \fIprivate|public-read|public-read-write|authenticated-read|keep|calc\fR? ?\fB-default-bucket\fR \fIbucketname\fR? +.sp +\fBS3::SuggestBucket\fR ?\fIname\fR? +.sp +\fBS3::REST\fR \fIdict\fR +.sp +\fBS3::ListAllMyBuckets\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-parse-xml\fR \fIxmlstring\fR? ?\fB-result-type\fR \fIREST|xml|pxml|dict|names|owner\fR? +.sp +\fBS3::PutBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-acl\fR \fI{}|private|public-read|public-read-write|authenticated-read\fR? +.sp +\fBS3::DeleteBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? +.sp +\fBS3::GetBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-parse-xml\fR \fIxmlstring\fR? ?\fB-max-count\fR \fIinteger\fR? ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-delimiter\fR \fIdelimiterstring\fR? ?\fB-result-type\fR \fIREST|xml|pxml|names|dict\fR? +.sp +\fBS3::Put\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-file\fR \fIfilename\fR? ?\fB-content\fR \fIcontentstring\fR? ?\fB-acl\fR \fIprivate|public-read|public-read-write|authenticated-read|calc|keep\fR? ?\fB-content-type\fR \fIcontenttypestring\fR? ?\fB-x-amz-meta-*\fR \fImetadatatext\fR? ?\fB-compare\fR \fIcomparemode\fR? +.sp +\fBS3::Get\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-file\fR \fIfilename\fR? ?\fB-content\fR \fIcontentvarname\fR? ?\fB-timestamp\fR \fIaws|now\fR? ?\fB-headers\fR \fIheadervarname\fR? +.sp +\fBS3::Head\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-dict\fR \fIdictvarname\fR? ?\fB-headers\fR \fIheadersvarname\fR? ?\fB-status\fR \fIstatusvarname\fR? +.sp +\fBS3::GetAcl\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-result-type\fR \fIREST|xml|pxml\fR? +.sp +\fBS3::PutAcl\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-acl\fR \fInew-acl\fR? +.sp +\fBS3::Delete\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-status\fR \fIstatusvar\fR? +.sp +\fBS3::Push\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-directory\fR \fIdirectoryname\fR ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-x-amz-meta-*\fR \fImetastring\fR? ?\fB-acl\fR \fIaclcode\fR? ?\fB-delete\fR \fIboolean\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +.sp +\fBS3::Pull\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-directory\fR \fIdirectoryname\fR ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-delete\fR \fIboolean\fR? ?\fB-timestamp\fR \fIaws|now\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +.sp +\fBS3::Toss\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-prefix\fR \fIprefixstring\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +.sp +.BE +.SH DESCRIPTION +This package provides access to Amazon's Simple Storage Solution web service. +.PP +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 \fIhttp://www.amazonaws.com/\fR 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. +.PP +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. +.PP +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. +.SH "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: +.TP +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. +.TP +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. +.TP +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 ...? +.TP +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 \fB::S3::REST\fR. +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. +.TP +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.) +.TP +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. +.PP +.SH COMMANDS +This package provides several separate levels of complexity. +.IP \(bu +The lowest level simply takes arguments to be sent to the service, +sends them, retrieves the result, and provides it to the caller. +\fINote:\fR This layer allows both synchronous and event-driven +processing. It depends on the MD5 and SHA1 and base64 packages +from Tcllib (available at \fIhttp://tcllib.sourceforge.net/\fR). +Note that \fBS3::Configure\fR is required for \fBS3::REST\fR to +work due to the authentication portion, so we put that in the "lowest level." +.IP \(bu +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 \fBTclXML\fR package as well as the +included \fBxsxp\fR package. These packages are package required when +these more-sophisticated routines are called, so nothing breaks if +they are not correctly installed. +.IP \(bu +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.) +.IP \(bu +Another separate program provides a GUI interface allowing drag-and-drop +and other such functionality. (Not yet implemented.) +.IP \(bu +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. +.PP +.PP +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. +.SH "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. +.TP +\fBS3::Configure\fR ?\fB-reset\fR \fIboolean\fR? ?\fB-retries\fR \fIinteger\fR? ?\fB-accesskeyid\fR \fIidstring\fR? ?\fB-secretaccesskey\fR \fIidstring\fR? ?\fB-service-access-point\fR \fIFQDN\fR? ?\fB-use-tls\fR \fIboolean\fR? ?\fB-default-compare\fR \fIalways|never|exists|missing|newer|date|checksum|different\fR? ?\fB-default-separator\fR \fIstring\fR? ?\fB-default-acl\fR \fIprivate|public-read|public-read-write|authenticated-read|keep|calc\fR? ?\fB-default-bucket\fR \fIbucketname\fR? +There is one command for configuration, and that is \fBS3::Configure\fR. +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. +.sp +The following options are accepted: +.RS +.TP +\fB-reset\fR \fIboolean\fR +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. +.TP +\fB-retries\fR \fIinteger\fR +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 \fBS3::REST\fR +from the higher-level commands, but not to \fBS3::REST\fR itself. +That is, \fBS3::REST\fR will always return httpstatus 500 if that's +what it receives. Functions like \fBS3::Put\fR 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. +.TP +\fB-accesskeyid\fR \fIidstring\fR +.TP +\fB-secretaccesskey\fR \fIidstring\fR +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 \fIhttp://www.amazonaws.com/\fR, +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 \fBS3::REST\fR calls are authenticated. +Blame Amazon for the poor choice of names. +.TP +\fB-service-access-point\fR \fIFQDN\fR +Defaults to "s3.amazonaws.com". This is the fully-qualified domain +name of the server to contact for \fBS3::REST\fR 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. +.TP +\fB-slop-seconds\fR \fIinteger\fR +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. +.TP +\fB-use-tls\fR \fIboolean\fR +Defaults to false. This is not yet implemented. If true, \fBS3::REST\fR will +negotiate a TLS connection to Amazon. If false, unencrypted connections +are used. +.TP +\fB-bucket-prefix\fR \fIstring\fR +Defaults to "TclS3". This string is used by \fBS3::SuggestBucketName\fR +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. +.TP +\fB-default-compare\fR \fIalways|never|exists|missing|newer|date|checksum|different\fR +Defaults to "always." If no -compare is specified on +\fBS3::Put\fR, \fBS3::Get\fR, or \fBS3::Delete\fR, this comparison is used. +See those commands for a description of the meaning. +.TP +\fB-default-separator\fR \fIstring\fR +Defaults to "/". This is currently unused. It might make sense to use +this for \fBS3::Push\fR and \fBS3::Pull\fR, but allowing resources to +have slashes in their names that aren't marking directories would be +problematic. Hence, this currently does nothing. +.TP +\fB-default-acl\fR \fIprivate|public-read|public-read-write|authenticated-read|keep|calc\fR +Defaults to an empty string. If no -acl argument is provided to \fBS3::Put\fR or +\fBS3::Push\fR, 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 \fInot\fR used by \fBS3::REST\fR. +.TP +\fB-default-bucket\fR \fIbucketname\fR +If no bucket is given to \fBS3::GetBucket\fR, \fBS3::PutBucket\fR, +\fBS3::Get\fR, \fBS3::Put\fR, +\fBS3::Head\fR, \fBS3::Acl\fR, +\fBS3::Delete\fR, \fBS3::Push\fR, +\fBS3::Pull\fR, or \fBS3::Toss\fR, 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. +.RE +.sp +.TP +\fBS3::SuggestBucket\fR ?\fIname\fR? +The \fBS3::SuggestBucket\fR command accepts an optional string as +a prefix and returns a valid bucket containing the \fIname\fR argument +and the Access Key ID. This makes the name unique to the owner and +to the application (assuming the application picks a good \fIname\fR argument). +If no name is provided, +the name from \fBS3::Configure\fR \fI-bucket-prefix\fR is used. +If that too is empty (which is not the default), an error is thrown. +.TP +\fBS3::REST\fR \fIdict\fR +The \fBS3::REST\fR 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 \fBresultvar\fR in the input dictionary. This requires +the \fI-accesskeyid\fR and \fI-secretaccesskey\fR to be configured via +\fBS3::Configure\fR before being called. +.sp +The possible input keys are these: +.RS +.TP +\fBverb\fR \fIGET|PUT|DELETE|HEAD\fR +This required item indicates the verb to be used. +.TP +\fBresource\fR \fIstring\fR +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. +.TP +?\fBrtype\fR \fItorrent|acl\fR? +This indicates a torrent or acl resource is being manipulated. +Do not include this in the \fBresource\fR key, or the +"?" separator will get URL-encoded. +.TP +?\fBparameters\fR \fIdict\fR? +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. +.TP +?\fBheaders\fR \fIdict\fR? +This optional dictionary provides headers to be added +to the HTTP request. The keys must be in \fIlower case\fR +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 \fBS3::REST\fR, do not add that header here. +Since content-type gets its own key, also do not add +that header here. +.TP +?\fBinbody\fR \fIcontentstring\fR? +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 \fBinbody\fR is +especially large, you may wind up blocking on the write socket. +.TP +?\fBinfile\fR \fIfilename\fR? +This optional item, if provided, and if \fBinbody\fR 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. +.TP +?\fBS3chan\fR \fIchannel\fR? +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 +\fBS3::Configure\fR, which is normally s3.amazonaws.com. If this +is provided, the channel is not closed at the end of the transaction. +.TP +?\fBoutchan\fR \fIchannel\fR? +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. +.TP +?\fBresultvar\fR \fIvarname\fR? +This optional item, if provided, indicates that \fBS3::REST\fR should +run in non-blocking mode. The \fIvarname\fR should be fully qualified +with respect to namespaces and cannot be local to a proc. If provided, +the result of the \fBS3::REST\fR 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 \fBS3::REST\fR and no calls to the eventloop are invoked from +within this call. +.TP +?\fBthrowsocket\fR \fIthrow|return\fR? +This optional item, if provided, indicates that \fBS3::REST\fR should +throw an error if throwmode is throw and a socket error is encountered. +It indicates that \fBS3::REST\fR should return the error code in the +returned dictionary if a socket error is encountered and this is +set to return. If \fBthrowsocket\fR is set to \fIreturn\fR 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 \fBerror\fR, \fBerrorInfo\fR, and \fBerrorCode\fR. +If a foreground call is made (i.e., \fBresultvar\fR is not provided), +and this option is not provided or is set to \fIthrow\fR, then +\fBerror\fR will be invoked instead. +.RE +.sp +Once the call to \fBS3::REST\fR completes, a new dict is returned, +either in the \fIresultvar\fR 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: +.RS +.TP +\fBerror\fR \fIerrorstring\fR +.TP +\fBerrorInfo\fR \fIerrorstring\fR +.TP +\fBerrorCode\fR \fIerrorstring\fR +If an error is caught, these three keys will be set in the result. +Note that \fBS3::REST\fR does \fInot\fR consider a non-2XX HTTP +return code as an error. The \fBerrorCode\fR value will be +formatted according to the \fBERROR REPORTING\fR description. +If these are present, other keys described here might not be. +.TP +\fBhttpstatus\fR \fIthreedigits\fR +The three-digit code from the HTTP transaction. 2XX for good, +5XX for server error, etc. +.TP +\fBhttpmessage\fR \fItext\fR +The textual result after the status code. "OK" or "Forbidden" +or etc. +.TP +\fBoutbody\fR \fIcontentstring\fR +If \fIoutchan\fR 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 \fBoutbody\fR or written to +\fBoutchan\fR as appropriate. +.TP +\fBoutheaders\fR \fIdict\fR +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. +.RE +.PP +.SH "HIGH LEVEL COMMANDS" +The routines in this section all make use of one or more calls +to \fBS3::REST\fR to do their work, then parse and manage the data +in a convenient way. All these commands throw errors +as described in \fBERROR REPORTING\fR unless otherwise noted. +.PP +In all these commands, all arguments are presented as name/value pairs, +in any order. All the argument names start with a hyphen. +.PP +There are a few options that are common to many +of the commands, and those common options are documented here. +.TP +\fB-blocking\fR \fIboolean\fR +If provided and specified as false, +then any calls to \fBS3:REST\fR 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. +.TP +\fB-parse-xml\fR \fIxmlstring\fR +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. +.TP +\fB-bucket\fR \fIbucketname\fR +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 \fBS3::Configure -default-bucket\fR +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. +.TP +\fB-resource\fR \fIresourcename\fR +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. +.TP +\fB-compare\fR \fIalways|never|exists|missing|newer|date|checksum|different\fR +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 \fBS3::Configure -default-compare\fR is used, which in turn defaults to "always." The meanings of the various values are these: +.RS +.TP +\fIalways\fR +Always copy the data. This is the default. +.TP +\fInever\fR +Never copy the data. This is essentially a no-op, except in \fBS3::Push\fR and \fBS3::Pull\fR where the -delete flag might make a difference. +.TP +\fIexists\fR +Copy the data only if the destination already exists. +.TP +\fImissing\fR +Copy the data only if the destination does not already exist. +.TP +\fInewer\fR +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 \fBS3::Configure -slop-seconds\fR 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]. +.TP +\fIdate\fR +Like \fInewer\fR, except copy if the date is newer \fIor\fR older. +.TP +\fIchecksum\fR +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. +.TP +\fIdifferent\fR +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. +.RE +.sp +Note that "newer" and "date" don't care about the contents, and "checksum" doesn't care about the dates, but "different" checks both. +.TP +\fBS3::ListAllMyBuckets\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-parse-xml\fR \fIxmlstring\fR? ?\fB-result-type\fR \fIREST|xml|pxml|dict|names|owner\fR? +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.) +.RS +.TP +\fB-blocking\fR \fIboolean\fR +See above for standard definition. +.TP +\fB-parse-xml\fR \fIxmlstring\fR +See above for standard definition. +.TP +\fB-result-type\fR \fIREST\fR +The dictionary returned by \fBS3::REST\fR is the return value of \fBS3::ListAllMyBuckets\fR. In this case, a non-2XX httpstatus will not throw an error. You may not combine this with \fI-parse-xml\fR. +.TP +\fB-result-type\fR \fIxml\fR +The raw XML of the body is returned as the result (with no encoding applied). +.TP +\fB-result-type\fR \fIpxml\fR +The XML of the body as parsed by \fBxsxp::parse\fR is returned. +.TP +\fB-result-type\fR \fIdict\fR +A dictionary of interesting portions of the XML is returned. The dictionary contains the following keys: +.RS +.TP +Owner/ID +The Amazon AWS ID (in hex) of the owner of the bucket. +.TP +Owner/DisplayName +The Amazon AWS ID's Display Name. +.TP +Bucket/Name +A list of names, one for each bucket. +.TP +Bucket/CreationDate +A list of dates, one for each bucket, +in the same order as Bucket/Name, in ISO format (as returned by Amazon). +.RE +.sp +.TP +\fB-result-type\fR \fInames\fR +A list of bucket names is returned with all other information stripped out. +This is the default result type for this command. +.TP +\fB-result-type\fR \fIowner\fR +A list containing two elements is returned. The first element is +the owner's ID, and the second is the owner's display name. +.RE +.sp +.TP +\fBS3::PutBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-acl\fR \fI{}|private|public-read|public-read-write|authenticated-read\fR? +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 \fBS3::ListAllMyBuckets\fR. See \fBS3::SuggestBucket\fR for ways to minimize this risk. The x-amz-acl header comes from the \fB-acl\fR option, or from \fBS3::Configure -default-acl\fR if not specified. +.TP +\fBS3::DeleteBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? +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. +.TP +\fBS3::GetBucket\fR ?\fB-bucket\fR \fIbucketname\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-parse-xml\fR \fIxmlstring\fR? ?\fB-max-count\fR \fIinteger\fR? ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-delimiter\fR \fIdelimiterstring\fR? ?\fB-result-type\fR \fIREST|xml|pxml|names|dict\fR? +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. +.RS +.TP +\fB-bucket\fR \fIbucketname\fR +The standard bucket argument. +.TP +\fB-blocking\fR \fIboolean\fR +The standard blocking argument. +.TP +\fB-parse-xml\fR \fIxmlstring\fR +The standard parse-xml argument. +.TP +\fB-max-count\fR \fIinteger\fR +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 \fBS3::REST\fR 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. +.TP +\fB-prefix\fR \fIprefixstring\fR +If present, restricts listing to resources with a particular prefix. One +leading / is stripped if present. +.TP +\fB-delimiter\fR \fIdelimiterstring\fR +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. +.TP +\fB-result-type\fR \fIREST|xml|pxml|names|dict\fR +This indicates the format of the return result of the command. +.RS +.TP +REST +If \fI-max-count\fR is specified, the dictionary returned +from \fBS3::REST\fR is returned. If \fI-max-count\fR is +not specified, a list of all the dictionaries returned from +the one or more calls to \fBS3::REST\fR is returned. +.TP +xml +If \fI-max-count\fR is specified, the body returned +from \fBS3::REST\fR is returned. If \fI-max-count\fR is +not specified, a list of all the bodies returned from +the one or more calls to \fBS3::REST\fR is returned. +.TP +pxml +If \fI-max-count\fR is specified, the body returned +from \fBS3::REST\fR is passed throught \fBxsxp::parse\fR and then returned. +If \fI-max-count\fR is +not specified, a list of all the bodies returned from +the one or more calls to \fBS3::REST\fR are each passed through +\fBxsxp::parse\fR and then returned. +.TP +names +Returns a list of all names found in either the Contents/Key fields or +the CommonPrefixes/Prefix fields. If no \fI-delimiter\fR is specified +and no \fI-max-count\fR is specified, this returns a list of all +resources with the specified \fI-prefix\fR. +.TP +dict +Returns a dictionary. (Returns only one dictionary even if \fI-max-count\fR +wasn't specified.) The keys of the dictionary are as follows: +.RS +.TP +Name +The name of the bucket (from the final call to \fBS3::REST\fR). +.TP +Prefix +From the final call to \fBS3::REST\fR. +.TP +Marker +From the final call to \fBS3::REST\fR. +.TP +MaxKeys +From the final call to \fBS3::REST\fR. +.TP +IsTruncated +From the final call to \fBS3::REST\fR, so +always false if \fI-max-count\fR is not specified. +.TP +NextMarker +Always provided if IsTruncated is true, and +calculated of Amazon does not provide it. May be empty if IsTruncated is false. +.TP +Key +A list of names of resources in the bucket matching the \fI-prefix\fR and \fI-delimiter\fR restrictions. +.TP +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.) +.TP +ETag +A list of entity tags (a.k.a. MD5 checksums) in the same order as Key. +.TP +Size +A list of sizes in bytes of the resources, in the same order as Key. +.TP +Owner/ID +A list of owners of the resources in the bucket, in the same order as Key. +.TP +Owner/DisplayName +A list of owners of the resources in the bucket, in the same order as Key. These are the display names. +.TP +CommonPrefixes/Prefix +A list of prefixes common to multiple entities. This is present only if \fI-delimiter\fR was supplied. +.RE +.RE +.RE +.TP +\fBS3::Put\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-file\fR \fIfilename\fR? ?\fB-content\fR \fIcontentstring\fR? ?\fB-acl\fR \fIprivate|public-read|public-read-write|authenticated-read|calc|keep\fR? ?\fB-content-type\fR \fIcontenttypestring\fR? ?\fB-x-amz-meta-*\fR \fImetadatatext\fR? ?\fB-compare\fR \fIcomparemode\fR? +This command sends data to a resource on Amazon's servers for storage, +using the HTTP PUT command. It returns 0 if the \fB-compare\fR 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 \fBS3:Configure -retries\fR settings before throwing an error; +other errors throw immediately. +.RS +.TP +\fB-bucket\fR +This specifies the bucket into which the resource will be written. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-blocking\fR +The standard blocking flag. +.TP +\fB-file\fR +If this is specified, the \fIfilename\fR 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 \fB-content\fR is +also specified, but at least one of \fB-file\fR or \fB-content\fR must +be specified. (The file is allowed to not exist or not be readable if +\fB-compare\fR \fInever\fR is specified.) +.TP +\fB-content\fR +If this is specified, the \fIcontentstring\fR 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 \fB-file\fR +is also specified, but at least one of \fB-file\fR or \fB-content\fR must +be specified. +.TP +\fB-acl\fR +This defaults to \fBS3::Configure -default-acl\fR if not specified. +It sets the x-amz-acl header on the PUT operation. +If the value provided is \fIcalc\fR, 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 \fIcalc\fR and \fB-content\fR. +If the value provided is \fIkeep\fR, 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. +\fINote:\fR \fIcalc\fR is not currently fully implemented. +.TP +\fB-x-amz-meta-*\fR +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. +.TP +\fB-content-type\fR +This overrides the content-type calculated by \fB-file\fR or +sets the content-type for \fB-content\fR. +.TP +\fB-compare\fR +This is the standard compare mode argument. \fBS3::Put\fR 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. +.RE +.sp +.TP +\fBS3::Get\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-file\fR \fIfilename\fR? ?\fB-content\fR \fIcontentvarname\fR? ?\fB-timestamp\fR \fIaws|now\fR? ?\fB-headers\fR \fIheadervarname\fR? +This command retrieves data from a resource on Amazon's S3 servers, +using the HTTP GET command. It returns 0 if the \fB-compare\fR 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 \fBS3:Configure\fR settings before throwing an error; +other errors throw immediately. Note that this is always authenticated +as the user configured in via \fBS3::Configure -accesskeyid\fR. Use +the Tcllib http for unauthenticated GETs. +.RS +.TP +\fB-bucket\fR +This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-blocking\fR +The standard blocking flag. +.TP +\fB-file\fR +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 \fB-content\fR +is also specified, but at least one of \fB-file\fR or \fB-content\fR must +be specified. +.TP +\fB-timestamp\fR +This is only valid in conjunction with \fB-file\fR. It may be specified +as \fInow\fR or \fIaws\fR. The default is \fInow\fR. If \fInow\fR, the file's +modification date is left up to the system. If \fIaws\fR, the file's +mtime is set to match the Last-Modified header on the resource, synchronizing +the two appropriately for \fB-compare\fR \fIdate\fR or +\fB-compare\fR \fInewer\fR. +.TP +\fB-content\fR +If this is specified, the \fIcontentvarname\fR 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 \fB-compare\fR is ignored unless +it is \fInever\fR, in which case no assignment to \fIcontentvarname\fR is +performed. Specifying this is an error if \fB-file\fR is also specified, +but at least one of \fB-file\fR or \fB-content\fR must be specified. +.TP +\fB-compare\fR +This is the standard compare mode argument. \fBS3::Get\fR 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. +.TP +\fB-headers\fR +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 \fB-compare\fR +or other errors), no assignment to this variable is performed. +.RE +.sp +.TP +\fBS3::Head\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-dict\fR \fIdictvarname\fR? ?\fB-headers\fR \fIheadersvarname\fR? ?\fB-status\fR \fIstatusvarname\fR? +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 +\fB-status\fR result can be consulted for details. +.RS +.TP +\fB-bucket\fR +This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-blocking\fR +The standard blocking flag. +.TP +\fB-dict\fR +If specified, the resulting dictionary from the \fBS3::REST\fR +call is assigned to the indicated (not necessarily global) variable +in the caller's scope. +.TP +\fB-headers\fR +If specified, the dictionary of headers from the result are assigned +to the indicated (not necessarily global) variable in the caller's scope. +.TP +\fB-status\fR +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"). +.RE +.TP +\fBS3::GetAcl\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-result-type\fR \fIREST|xml|pxml\fR? +This command gets the ACL of the indicated resource or throws an +error if it is unavailable. +.RS +.TP +\fB-blocking\fR \fIboolean\fR +See above for standard definition. +.TP +\fB-bucket\fR +This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-parse-xml\fR \fIxml\fR +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. +.TP +\fB-result-type\fR \fIREST\fR +The dictionary returned by \fBS3::REST\fR is the return value of +\fBS3::GetAcl\fR. In this case, a non-2XX httpstatus will not throw an +error. +.TP +\fB-result-type\fR \fIxml\fR +The raw XML of the body is returned as the result (with no encoding applied). +.TP +\fB-result-type\fR \fIpxml\fR +The XML of the body as parsed by \fBxsxp::parse\fR is returned. +.TP +\fB-result-type\fR \fIdict\fR +This fetches the ACL, parses it, and returns a dictionary of two elements. +.sp +The first element has the key "owner" whose value is the canonical ID of the owner of the resource. +.sp +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. +.RE +.TP +\fBS3::PutAcl\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-acl\fR \fInew-acl\fR? +This sets the ACL on the indicated resource. It returns the XML written to the ACL, or throws an error if anything went wrong. +.RS +.TP +\fB-blocking\fR \fIboolean\fR +See above for standard definition. +.TP +\fB-bucket\fR +This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-owner\fR +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 \fBS3::GetAcl\fR, 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. +.TP +\fB-acl\fR +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 \fBS3::Configure -default-acl\fR. +The ACL is written with a PUT to the ?acl resource. +.sp +If the value passed to this option +starts with "<", it is taken to be a body to be PUT to the ACL resource. +.sp +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). +.sp +Otherwise, the value is assumed to be a dictionary formatted as the +"acl" sub-entry within the dict returns by \fBS3::GetAcl -result-type dict\fR. +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. +.sp +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. +.RE +.TP +\fBS3::Delete\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-resource\fR \fIresourcename\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-status\fR \fIstatusvar\fR? +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. +.RS +.TP +\fB-bucket\fR +This specifies the bucket from which the resource will be deleted. +Leading and/or trailing slashes are removed for you, as are spaces. +.TP +\fB-resource\fR +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. +.TP +\fB-blocking\fR +The standard blocking flag. +.TP +\fB-status\fR +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. +.RE +.sp +.TP +\fBS3::Push\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-directory\fR \fIdirectoryname\fR ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-x-amz-meta-*\fR \fImetastring\fR? ?\fB-acl\fR \fIaclcode\fR? ?\fB-delete\fR \fIboolean\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +This synchronises a local directory with a remote bucket +by pushing the differences using \fBS3::Put\fR. 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 \fBS3::Sync\fR +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. +.RS +.TP +\fB-bucket\fR +This names the bucket into which data will be pushed. +.TP +\fB-directory\fR +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, \fBS3::Push\fR will PUT +those files that are readable and return in its results the list +of files that could not be opened. +.TP +\fB-prefix\fR +This names the prefix that will be added to all resources. +That is, it is the remote equivalent of \fB-directory\fR. +If it is not specified, the root of the bucket will be treated +as the remote directory. An example may clarify. +.CS + + +S3::Push -bucket test -directory /tmp/xyz -prefix hello/world + +.CE +.IP +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 \fB-prefix\fR option, /tmp/xyz/pdq.html would be stored +as http://s3.amazonaws.com/test/pdq.html. +.TP +\fB-blocking\fR +This is the standard blocking option. +.TP +\fB-compare\fR +If present, this is passed to each invocation of \fBS3::Put\fR. +Naturally, \fBS3::Configure -default-compare\fR is used +if this is not specified. +.TP +\fB-x-amz-meta-*\fR +If present, this is passed to each invocation of \fBS3::Put\fR. All copied +files will have the same metadata. +.TP +\fB-acl\fR +If present, this is passed to each invocation of \fBS3::Put\fR. +.TP +\fB-delete\fR +This defaults to false. If true, resources in the destination that +are not in the source directory are deleted with \fBS3::Delete\fR. +Since only regular files are considered, the existance of a symlink, +pipe, device, or directory in the local source will \fInot\fR +prevent the deletion of a remote resource with a corresponding name. +.TP +\fB-error\fR +This controls the behavior of \fBS3::Push\fR in the event that +\fBS3::Put\fR 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. \fBS3::Delete\fR is always +finished up, with errors simply recorded in the return result. +.RS +.TP +throw +The error is rethrown with the same errorCode. +.TP +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 \fBS3::Delete\fR are not started. +.TP +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. +.RE +.TP +\fB-progress\fR +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 \fIargs\fR as the +first additional argument and a dictionary representing the normalized +arguments to the \fBS3::Push\fR call as the second additional argument. +Then the prefix is invoked with \fIlocal\fR 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 \fIremote\fR 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 \fIstart\fR as the first +additional argument and the common suffix as the second additional +argument. When \fBS3::Put\fR returns for that file, the prefix will be +invoked with \fIcopy\fR as the first additional argument, the common +suffix as the second additional argument, and a third argument that will +be "copied" (if \fBS3::Put\fR sent the resource), "skipped" (if +\fBS3::Put\fR decided not to based on \fB-compare\fR), or the errorCode +that \fBS3::Put\fR 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 +\fIdelete\fR 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 \fBS3::Delete\fR if it failed. Finally, the prefix +will be invoked with \fIfinished\fR as the first additional argument +and the return value as the second additional argument. +.RE +.IP +The return result from this command is a dictionary. They keys are the +suffixes (i.e., the common portion of the path after the \fB-directory\fR +and \fB-prefix\fR), while the values are either "copied", "skipped" (if +\fB-compare\fR indicated not to copy the file), or the errorCode +thrown by \fBS3::Put\fR, as appropriate. If \fB-delete\fR was true, +there may also be entries for suffixes with the value "deleted" or +"notdeleted", indicating whether the attempted \fBS3::Delete\fR +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 \fB-compare\fR 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 \fB-delete\fR is false), and "filesnotdeleted" +(the number of resources whose deletion was attempted but failed). +.sp +Note that this is currently implemented somewhat inefficiently. +It fetches the bucket listing (including timestamps and eTags), +then calls \fBS3::Put\fR, which uses HEAD to find the timestamps +and eTags again. Correcting this with no API change +is planned for a future upgrade. +.sp +.TP +\fBS3::Pull\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-directory\fR \fIdirectoryname\fR ?\fB-prefix\fR \fIprefixstring\fR? ?\fB-blocking\fR \fIboolean\fR? ?\fB-compare\fR \fIcomparemode\fR? ?\fB-delete\fR \fIboolean\fR? ?\fB-timestamp\fR \fIaws|now\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +This synchronises a remote bucket with a local directory by pulling the +differences using \fBS3::Get\fR 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 \fBS3::Sync\fR 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. +.sp +Note that this is currently implemented somewhat inefficiently. +It fetches the bucket listing (including timestamps and eTags), +then calls \fBS3::Get\fR, which uses HEAD to find the timestamps +and eTags again. Correcting this with no API change +is planned for a future upgrade. +.RS +.TP +\fB-bucket\fR +This names the bucket from which data will be pulled. +.TP +\fB-directory\fR +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, +\fBS3::Pull\fR will GET +those files that are writable and return in its results the list +of files that could not be opened. +.TP +\fB-prefix\fR +The prefix of resources that will be considered for retrieval. +See \fBS3::Push\fR for more details, examples, etc. (Of course, +\fBS3::Pull\fR reads rather than writes, but the prefix is +treated similarly.) +.TP +\fB-blocking\fR +This is the standard blocking option. +.TP +\fB-compare\fR +This is passed to each invocation of \fBS3::Get\fR if provided. +Naturally, \fBS3::Configure -default-compare\fR is +used if this is not provided. +.TP +\fB-timestamp\fR +This is passed to each invocation of \fBS3::Get\fR if provided. +.TP +\fB-delete\fR +If this is specified and true, files that exist in the \fB-directory\fR +that are not in the \fB-prefix\fR will be deleted after all resources +have been copied. In addition, empty directories (other than the +top-level \fB-directory\fR) will be deleted, as +Amazon S3 has no concept of an empty directory. +.TP +\fB-error\fR +See \fBS3::Push\fR for a description of this option. +.TP +\fB-progress\fR +See \fBS3::Push\fR 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. +.RE +.IP +The return value from this command is a dictionary. It +is identical in form and meaning to the description of the +return result of \fBS3::Push\fR. It differs only in that +directories may be included, with a trailing slash in their name, +if they are empty and get deleted. +.TP +\fBS3::Toss\fR ?\fB-bucket\fR \fIbucketname\fR? \fB-prefix\fR \fIprefixstring\fR ?\fB-blocking\fR \fIboolean\fR? ?\fB-error\fR \fIthrow|break|continue\fR? ?\fB-progress\fR \fIscriptprefix\fR? +This deletes some or all resources within a bucket. It would be +considered a "recursive delete" had Amazon implemented actual +directories. +.RS +.TP +\fB-bucket\fR +The bucket from which resources will be deleted. +.TP +\fB\fB-blocking\fR\fR +The standard blocking option. +.TP +\fB\fB-prefix\fR\fR +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. +.TP +\fB\fB-error\fR\fR +If this is "throw", \fBS3::Toss\fR rethrows any errors +it encounters. If this is "break", \fBS3::Toss\fR returns +with a normal return after the first error, recording that +error in the return result. If this is "continue", which is +the default, \fBS3::Toss\fR continues on and lists all +errors in the return result. +.TP +\fB\fB-progress\fR\fR +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 \fIargs\fR and the second +being the processed list of arguments to \fBS3::Toss\fR. Then it +is invoked with \fIremote\fR 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 \fIdelete\fR and the second additional argument being +the suffix deleted and the third additional argument being "deleted" +or "notdeleted" depending on whether \fBS3::Delete\fR 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. +.RE +.IP +The return value is a dictionary. The keys are the suffixes of files +that \fBS3::Toss\fR 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. +.PP +.SH LIMITATIONS +.IP \(bu +The pure-Tcl MD5 checking is slow. If you are processing +files in the megabyte range, consider ensuring binary support is available. +.IP \(bu +The commands \fBS3::Pull\fR and \fBS3::Push\fR fetch a +directory listing which includes timestamps and MD5 hashes, +then invoke \fBS3::Get\fR and \fBS3::Put\fR. If +a complex \fB-compare\fR mode is specified, \fBS3::Get\fR and +\fBS3::Put\fR 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. +.IP \(bu +The commands \fBS3::Pull\fR and \fBS3::Push\fR fetch a +directory listing without using \fB-max-count\fR. 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. +.IP \(bu +\fBS3::Sync\fR 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 \fBS3::Sync\fR. +.IP \(bu +Nor is +\fB-compare\fR \fIcalc\fR 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. +.IP \(bu +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. +.IP \(bu +Internally, \fBS3::Push\fR and \fBS3::Pull\fR and \fBS3::Toss\fR +are all very similar and should be refactored. +.IP \(bu +The idea of using \fB-compare\fR \fInever\fR +\fB-delete\fR \fItrue\fR to delete files that have been +deleted from one place but not the other yet not copying +changed files is untested. +.PP +.SH "USAGE SUGGESTIONS" +To fetch a "directory" out of a bucket, make changes, and store it back: +.CS + + +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 + +.CE +.PP +To delete files locally that were deleted off of S3 but not otherwise +update files: +.CS + + +S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \\ + -compare never -delete true + +.CE +.SH "FUTURE DEVELOPMENTS" +The author intends to work on several additional projects related to +this package, in addition to finishing the unfinished features. +.PP +First, a command-line program allowing browsing of buckets and +transfer of files from shell scripts and command prompts is useful. +.PP +Second, a GUI-based program allowing visual manipulation of +bucket and resource trees not unlike Windows Explorer would +be useful. +.PP +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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIamazon-s3\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +amazon, cloud, s3 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) Copyright 2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms. + +.fi ADDED embedded/man/files/modules/amazon-s3/xsxp.n Index: embedded/man/files/modules/amazon-s3/xsxp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/amazon-s3/xsxp.n @@ -0,0 +1,389 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/amazon-s3/xsxp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Copyright 2006 Darren New. All Rights Reserved. +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "xsxp" n 1.0 tcllib "Amazon S3 Web Service Utilities" +.BS +.SH NAME +xsxp \- eXtremely Simple Xml Parser +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBxml \fR +.sp +\fBxsxp::parse\fR \fIxml\fR +.sp +\fBxsxp::fetch\fR \fIpxml\fR \fIpath\fR ?\fIpart\fR? +.sp +\fBxsxp::fetchall\fR \fIpxml_list\fR \fIpath\fR ?\fIpart\fR? +.sp +\fBxsxp::only\fR \fIpxml\fR \fItagname\fR +.sp +\fBxsxp::prettyprint\fR \fIpxml\fR ?\fIchan\fR? +.sp +.BE +.SH 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. +.PP +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. +.PP +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. +.PP +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. +.SH 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. +.TP +\fBxsxp::parse\fR \fIxml\fR +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: +.RS +.IP \(bu +The first element is the name of the tag. +.IP \(bu +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. +.IP \(bu +The third through end elements are the children of the node, if any. Each child is, recursively, a pxml. +.IP \(bu +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. +.RE +.sp +.TP +\fBxsxp::fetch\fR \fIpxml\fR \fIpath\fR ?\fIpart\fR? +\fIpxml\fR is a parsed XML, as returned from xsxp::parse. +\fIpath\fR 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 \fIpxml\fR. 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.) +.sp +An element of \fIpath\fR 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. +.sp +\fIpart\fR defaults to "%ALL". It can be one of the following case-sensitive terms: +.RS +.TP +%ALL +returns the entire selected element. +.TP +%TAGNAME +returns lindex 0 of the selected element. +.TP +%ATTRIBUTES +returns index 1 of the selected element. +.TP +%CHILDREN +returns lrange 2 through end of the selected element, +resulting in a list of elements being returned. +.TP +%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. +.TP +%PCDATA? +is like %PCDATA, but returns an empty string if +no PCDATA is found. +.RE +.sp +For example, to fetch the first bold text from the fifth paragraph of the body of your HTML file, +.CS + +xsxp::fetch $pxml {html body p#4 b} %PCDATA +.CE +.sp +.TP +\fBxsxp::fetchall\fR \fIpxml_list\fR \fIpath\fR ?\fIpart\fR? +This iterates over each PXML in \fIpxml_list\fR (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. +.sp +For example, \fIpxml_list\fR might be +the %CHILDREN of a particular element, and the \fIpath\fR and \fIpart\fR +might select from each child a sub-element in which we're interested. +.sp +.TP +\fBxsxp::only\fR \fIpxml\fR \fItagname\fR +This iterates over the direct children of \fIpxml\fR and selects only +those with \fItagname\fR as their tag. Returns a list of matching +elements. +.sp +.TP +\fBxsxp::prettyprint\fR \fIpxml\fR ?\fIchan\fR? +This outputs to \fIchan\fR (default stdout) a pretty-printed +version of \fIpxml\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIamazon-s3\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +dom, parser, xml +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) Copyright 2006 Darren New. All Rights Reserved. + +.fi ADDED embedded/man/files/modules/asn/asn.n Index: embedded/man/files/modules/asn/asn.n ================================================================== --- /dev/null +++ embedded/man/files/modules/asn/asn.n @@ -0,0 +1,717 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/asn/asn.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries +'\" Copyright (c) 2004 Jochen Loewer +'\" Copyright (c) 2004-2011 Michael Schlenker +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "asn" n 0.8 tcllib "ASN.1 processing" +.BS +.SH NAME +asn \- ASN.1 BER encoder/decoder +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBasn ?0.8.4?\fR +.sp +\fB::asn::asnSequence\fR \fIevalue\fR... +.sp +\fB::asn::asnSequenceFromList\fR \fIelist\fR +.sp +\fB::asn::asnSet\fR \fIevalue\fR... +.sp +\fB::asn::asnSetFromList\fR \fIelist\fR +.sp +\fB::asn::asnApplicationConstr\fR \fIappNumber\fR \fIevalue\fR... +.sp +\fB::asn::asnApplication\fR \fIappNumber\fR \fIdata\fR +.sp +\fB::asn::asnChoice\fR \fIappNumber\fR \fIevalue\fR... +.sp +\fB::asn::asnChoiceConstr\fR \fIappNumber\fR \fIevalue\fR... +.sp +\fB::asn::asnInteger\fR \fInumber\fR +.sp +\fB::asn::asnEnumeration\fR \fInumber\fR +.sp +\fB::asn::asnBoolean\fR \fIbool\fR +.sp +\fB::asn::asnContext\fR \fIcontext\fR \fIdata\fR +.sp +\fB::asn::asnContextConstr\fR \fIcontext\fR \fIevalue\fR... +.sp +\fB::asn::asnObjectIdentifier\fR \fIidlist\fR +.sp +\fB::asn::asnUTCTime\fR \fIutcstring\fR +.sp +\fB::asn::asnNull\fR +.sp +\fB::asn::asnBitString\fR \fIstring\fR +.sp +\fB::asn::asnOctetString\fR \fIstring\fR +.sp +\fB::asn::asnNumericString\fR \fIstring\fR +.sp +\fB::asn::asnPrintableString\fR \fIstring\fR +.sp +\fB::asn::asnIA5String\fR \fIstring\fR +.sp +\fB::asn::asnBMPString\fR \fIstring\fR +.sp +\fB::asn::asnUTF8String\fR \fIstring\fR +.sp +\fB::asn::asnString\fR \fIstring\fR +.sp +\fB::asn::defaultStringType\fR ?\fItype\fR? +.sp +\fB::asn::asnPeekByte\fR \fIdata_var\fR \fIbyte_var\fR +.sp +\fB::asn::asnGetLength\fR \fIdata_var\fR \fIlength_var\fR +.sp +\fB::asn::asnGetResponse\fR \fIchan\fR \fIdata_var\fR +.sp +\fB::asn::asnGetInteger\fR \fIdata_var\fR \fIint_var\fR +.sp +\fB::asn::asnGetEnumeration\fR \fIdata_var\fR \fIenum_var\fR +.sp +\fB::asn::asnGetOctetString\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetString\fR \fIdata_var\fR \fIstring_var\fR ?\fItype_var\fR? +.sp +\fB::asn::asnGetNumericString\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetPrintableString\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetIA5String\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetBMPString\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetUTF8String\fR \fIdata_var\fR \fIstring_var\fR +.sp +\fB::asn::asnGetUTCTime\fR \fIdata_var\fR \fIutc_var\fR +.sp +\fB::asn::asnGetBitString\fR \fIdata_var\fR \fIbits_var\fR +.sp +\fB::asn::asnGetObjectIdentifier\fR \fIdata_var\fR \fIoid_var\fR +.sp +\fB::asn::asnGetBoolean\fR \fIdata_var\fR \fIbool_var\fR +.sp +\fB::asn::asnGetNull\fR \fIdata_var\fR +.sp +\fB::asn::asnGetSequence\fR \fIdata_var\fR \fIsequence_var\fR +.sp +\fB::asn::asnGetSet\fR \fIdata_var\fR \fIset_var\fR +.sp +\fB::asn::asnGetApplication\fR \fIdata_var\fR \fIappNumber_var\fR ?\fIcontent_var\fR? ?\fIencodingType_var\fR? +.sp +\fB::asn::asnGetContext\fR \fIdata_var\fR \fIcontextNumber_var\fR ?\fIcontent_var\fR? ?\fIencodingType_var\fR? +.sp +\fB::asn::asnPeekTag\fR \fIdata_var\fR \fItag_var\fR \fItagtype_var\fR \fIconstr_var\fR +.sp +\fB::asn::asnTag\fR \fItagnumber\fR ?\fIclass\fR? ?\fItagstyle\fR? +.sp +\fB::asn::asnRetag\fR \fIdata_var\fR \fInewTag\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBasn\fR package provides \fIpartial\fR 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. +.PP +ASN.1 is a standard \fIAbstract Syntax Notation\fR, and BER are its +\fIBasic Encoding Rules\fR. +.PP +See \fIhttp://asn1.elibel.tm.fr/en/standards/index.htm\fR for more +information about the standard. +.PP +Also see \fIhttp://luca.ntop.org/Teaching/Appunti/asn1.html\fR for +\fIA Layman's Guide to a Subset of ASN.1, BER, and DER\fR, 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. +.SH "PUBLIC API" +.SS ENCODER +.TP +\fB::asn::asnSequence\fR \fIevalue\fR... +Takes zero or more encoded values, packs them into an ASN sequence and +returns its encoded binary form. +.TP +\fB::asn::asnSequenceFromList\fR \fIelist\fR +Takes a list of encoded values, packs them into an ASN sequence and +returns its encoded binary form. +.TP +\fB::asn::asnSet\fR \fIevalue\fR... +Takes zero or more encoded values, packs them into an ASN set and +returns its encoded binary form. +.TP +\fB::asn::asnSetFromList\fR \fIelist\fR +Takes a list of encoded values, packs them into an ASN set and +returns its encoded binary form. +.TP +\fB::asn::asnApplicationConstr\fR \fIappNumber\fR \fIevalue\fR... +Takes zero or more encoded values, packs them into an ASN application +construct and returns its encoded binary form. +.TP +\fB::asn::asnApplication\fR \fIappNumber\fR \fIdata\fR +Takes a single encoded value \fIdata\fR, packs it into an ASN +application construct and returns its encoded binary form. +.TP +\fB::asn::asnChoice\fR \fIappNumber\fR \fIevalue\fR... +Takes zero or more encoded values, packs them into an ASN choice +construct and returns its encoded binary form. +.TP +\fB::asn::asnChoiceConstr\fR \fIappNumber\fR \fIevalue\fR... +Takes zero or more encoded values, packs them into an ASN choice +construct and returns its encoded binary form. +.TP +\fB::asn::asnInteger\fR \fInumber\fR +Returns the encoded form of the specified integer +\fInumber\fR. +.TP +\fB::asn::asnEnumeration\fR \fInumber\fR +Returns the encoded form of the specified enumeration id +\fInumber\fR. +.TP +\fB::asn::asnBoolean\fR \fIbool\fR +Returns the encoded form of the specified boolean value +\fIbool\fR. +.TP +\fB::asn::asnContext\fR \fIcontext\fR \fIdata\fR +Takes an encoded value and packs it into a constructed value with +application tag, the \fIcontext\fR number. +.TP +\fB::asn::asnContextConstr\fR \fIcontext\fR \fIevalue\fR... +Takes zero or more encoded values and packs them into a constructed +value with application tag, the \fIcontext\fR number. +.TP +\fB::asn::asnObjectIdentifier\fR \fIidlist\fR +Takes a list of at least 2 integers describing an object identifier +(OID) value, and returns the encoded value. +.TP +\fB::asn::asnUTCTime\fR \fIutcstring\fR +Returns the encoded form of the specified UTC time string. +.TP +\fB::asn::asnNull\fR +Returns the NULL encoding. +.TP +\fB::asn::asnBitString\fR \fIstring\fR +Returns the encoded form of the specified \fIstring\fR. +.TP +\fB::asn::asnOctetString\fR \fIstring\fR +Returns the encoded form of the specified \fIstring\fR. +.TP +\fB::asn::asnNumericString\fR \fIstring\fR +Returns the \fIstring\fR encoded as ASN.1 NumericString. Raises an +error if the \fIstring\fR contains characters other than decimal +numbers and space. +.TP +\fB::asn::asnPrintableString\fR \fIstring\fR +Returns the \fIstring\fR encoding as ASN.1 PrintableString. Raises an +error if the \fIstring\fR 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. +.TP +\fB::asn::asnIA5String\fR \fIstring\fR +Returns the \fIstring\fR encoded as ASN.1 IA5String. Raises an error +if the \fIstring\fR contains any characters outside of the US-ASCII +range. +.TP +\fB::asn::asnBMPString\fR \fIstring\fR +Returns the \fIstring\fR encoded as ASN.1 Basic Multilingual Plane +string (Which is essentialy big-endian UCS2). +.TP +\fB::asn::asnUTF8String\fR \fIstring\fR +Returns the \fIstring\fR 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. +.TP +\fB::asn::asnString\fR \fIstring\fR +Returns an encoded form of \fIstring\fR, 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 \fB::asn::defaultStringType\fR. +.TP +\fB::asn::defaultStringType\fR ?\fItype\fR? +Selects the string type to use for the encoding of non-ASCII +strings. Returns current default when called without argument. If the +argument \fItype\fR is supplied, it should be either \fBUTF8\fR or +\fBBMP\fR to choose UTF8String or BMPString respectively. +.PP +.PP +.SS DECODER +General notes: +.IP [1] +Nearly all decoder commands take two arguments. These arguments are variable +names, except for \fB::asn::asnGetResponse\fR. 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. +.IP [2] +After extraction the data variable is always modified first, before by +writing the extracted value to its variable. This means that if both +arguments refer to the same variable, it will always contain the +extracted value after the call, and not the remainder of the input. +.PP +.PP +.TP +\fB::asn::asnPeekByte\fR \fIdata_var\fR \fIbyte_var\fR +Retrieve the first byte of the data, without modifing \fIdata_var\fR. +This can be used to check for implicit tags. +.TP +\fB::asn::asnGetLength\fR \fIdata_var\fR \fIlength_var\fR +Decode the length information for a block of BER data. The tag has already +to be removed from the data. +.TP +\fB::asn::asnGetResponse\fR \fIchan\fR \fIdata_var\fR +Reads an encoded ASN \fIsequence\fR from the channel \fIchan\fR and +stores it into the variable named by \fIdata_var\fR. +.TP +\fB::asn::asnGetInteger\fR \fIdata_var\fR \fIint_var\fR +Assumes that an encoded integer value is at the front of the data +stored in the variable named \fIdata_var\fR, extracts and stores it +into the variable named by \fIint_var\fR. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands. +.TP +\fB::asn::asnGetEnumeration\fR \fIdata_var\fR \fIenum_var\fR +Assumes that an enumeration id is at the front of the data stored in +the variable named \fIdata_var\fR, and stores it into the variable +named by \fIenum_var\fR. Additionally removes all bytes associated +with the value from the data for further processing by the following +decoder commands. +.TP +\fB::asn::asnGetOctetString\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a string is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIstring_var\fR. Additionally removes all bytes associated with +the value from the data for further processing by the following +decoder commands. +.TP +\fB::asn::asnGetString\fR \fIdata_var\fR \fIstring_var\fR ?\fItype_var\fR? +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 \fB::asn::asnGetPrintableString\fR, \fB::asnGetIA5String\fR, etc. +below for the type-specific conversion commands. +.sp +If the optional third argument \fItype_var\fR is supplied, then the +type of the incoming string is stored in the variable named by it. +.sp +The function throws the error +"Invalid command name asnGetSome\fBUnsupportedString\fR" if the +unsupported string type \fBUnsupported\fR is encountered. You can +create the appropriate function +"asn::asnGetSome\fBUnsupportedString\fR" in your application if +neccessary. +.TP +\fB::asn::asnGetNumericString\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a numeric string value is at the front of the data stored +in the variable named \fIdata_var\fR, and stores it into the variable +named by \fIstring_var\fR. Additionally removes all bytes associated +with the value from the data for further processing by the following +decoder commands. +.TP +\fB::asn::asnGetPrintableString\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a printable string value is at the front of the data +stored in the variable named \fIdata_var\fR, and stores it into the +variable named by \fIstring_var\fR. Additionally removes all bytes +associated with the value from the data for further processing by the +following decoder commands. +.TP +\fB::asn::asnGetIA5String\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a IA5 (ASCII) string value is at the front of the data +stored in the variable named \fIdata_var\fR, and stores it into the +variable named by \fIstring_var\fR. Additionally removes all bytes +associated with the value from the data for further processing by the +following decoder commands. +.TP +\fB::asn::asnGetBMPString\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a BMP (two-byte unicode) string value is at the front of +the data stored in the variable named \fIdata_var\fR, and stores it +into the variable named by \fIstring_var\fR, 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. +.TP +\fB::asn::asnGetUTF8String\fR \fIdata_var\fR \fIstring_var\fR +Assumes that a UTF8 string value is at the front of the data stored in +the variable named \fIdata_var\fR, and stores it into the variable +named by \fIstring_var\fR, 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. +.TP +\fB::asn::asnGetUTCTime\fR \fIdata_var\fR \fIutc_var\fR +Assumes that a UTC time value is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIutc_var\fR. 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. +.TP +\fB::asn::asnGetBitString\fR \fIdata_var\fR \fIbits_var\fR +Assumes that a bit string value is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIbits_var\fR 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. +.TP +\fB::asn::asnGetObjectIdentifier\fR \fIdata_var\fR \fIoid_var\fR +Assumes that a object identifier (OID) value is at the front of the data +stored in the variable named \fIdata_var\fR, and stores it into the variable +named by \fIoid_var\fR as a list of integers. +Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands. +.TP +\fB::asn::asnGetBoolean\fR \fIdata_var\fR \fIbool_var\fR +Assumes that a boolean value is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIbool_var\fR. Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands. +.TP +\fB::asn::asnGetNull\fR \fIdata_var\fR +Assumes that a NULL value is at the front of the data stored in the +variable named \fIdata_var\fR and removes the bytes used to encode it +from the data. +.TP +\fB::asn::asnGetSequence\fR \fIdata_var\fR \fIsequence_var\fR +Assumes that an ASN sequence is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIsequence_var\fR. Additionally removes all bytes associated with +the value from the data for further processing by the following +decoder commands. +.sp +The data in \fIsequence_var\fR is encoded binary and has to be +further decoded according to the definition of the sequence, using the +decoder commands here. +.TP +\fB::asn::asnGetSet\fR \fIdata_var\fR \fIset_var\fR +Assumes that an ASN set is at the front of the data stored in the +variable named \fIdata_var\fR, and stores it into the variable named +by \fIset_var\fR. Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands. +.sp +The data in \fIset_var\fR is encoded binary and has to be further +decoded according to the definition of the set, using the decoder +commands here. +.TP +\fB::asn::asnGetApplication\fR \fIdata_var\fR \fIappNumber_var\fR ?\fIcontent_var\fR? ?\fIencodingType_var\fR? +Assumes that an ASN application construct is at the front of the data +stored in the variable named \fIdata_var\fR, and stores its id into +the variable named by \fIappNumber_var\fR. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands. +If a \fIcontent_var\fR 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 \fIencodingType_var\fR is specified, then that var is set to 1 if +the encoding is constructed and 0 if it is primitive. +.sp +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. +.TP +\fB::asn::asnGetContext\fR \fIdata_var\fR \fIcontextNumber_var\fR ?\fIcontent_var\fR? ?\fIencodingType_var\fR? +Assumes that an ASN context tag construct is at the front of the data +stored in the variable named \fIdata_var\fR, and stores its id into +the variable named by \fIcontextNumber_var\fR. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands. +If a \fIcontent_var\fR 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 \fIencodingType_var\fR is specified, then that var is set to 1 if +the encoding is constructed and 0 if it is primitive. +.sp +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. +.PP +.PP +.SS "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 \fB::asn::asnRetag\fR 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: +.TP +\fB::asn::asnPeekTag\fR \fIdata_var\fR \fItag_var\fR \fItagtype_var\fR \fIconstr_var\fR +The \fB::asn::asnPeekTag\fR command can be used to take a peek at the data and decode the tag value, without +removing it from the data. The \fItag_var\fR gets set to the tag number, while the \fItagtype_var\fR gets set +to the class of the tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The \fIconstr_var\fR 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. +.TP +\fB::asn::asnTag\fR \fItagnumber\fR ?\fIclass\fR? ?\fItagstyle\fR? +The \fB::asn::asnTag\fR can be used to create a tag value. The \fItagnumber\fR gives the number of the tag, while +the \fIclass\fR 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 \fItagstyle\fR 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 \fB::asn::asnPeekTag\fR. +.TP +\fB::asn::asnRetag\fR \fIdata_var\fR \fInewTag\fR +Replaces the tag in front of the data in \fIdata_var\fR with \fInewTag\fR. The new Tag can be created using the \fB::asn::asnTag\fR command. +.PP +.SH EXAMPLES +Examples for the usage of this package can be found in the +implementation of package \fBldap\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIasn\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +asn, ber, cer, der, internet, protocol, x.208, x.209 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries +Copyright (c) 2004 Jochen Loewer +Copyright (c) 2004-2011 Michael Schlenker + +.fi ADDED embedded/man/files/modules/base32/base32.n Index: embedded/man/files/modules/base32/base32.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base32/base32.n @@ -0,0 +1,325 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base32/base32.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Public domain +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "base32" n 0.1 tcllib "Base32 encoding" +.BS +.SH NAME +base32 \- base32 standard encoding +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBbase32::core ?0.1?\fR +.sp +package require \fBbase32 ?0.1?\fR +.sp +\fB::base32::encode\fR \fIstring\fR +.sp +\fB::base32::decode\fR \fIestring\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides commands for encoding and decoding of strings +into and out of the standard base32 encoding as specified in RFC 3548. +.SH API +.TP +\fB::base32::encode\fR \fIstring\fR +This command encodes the given \fIstring\fR in base32 and returns the +encoded string as its result. The result may be padded with the +character \fB=\fR to signal a partial encoding at the end of the +input string. +.TP +\fB::base32::decode\fR \fIestring\fR +This commands takes the \fIestring\fR 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. +.sp +Note that while the encoder will generate only uppercase characters +this decoder accepts input in lowercase as well. +.sp +The command will always throw an error whenever encountering +conditions which signal some type of bogus input, namely if +.RS +.IP [1] +the input contains characters which are not valid output of a base32 encoder, +.IP [2] +the length of the input is not a multiple of eight, +.IP [3] +padding appears not at the end of input, but in the middle, +.IP [4] +the padding has not of length six, four, three, or one characters, +.RE +.PP +.SH "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). +.CS + + + 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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase32\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +base32, rfc3548 +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) Public domain + +.fi ADDED embedded/man/files/modules/base32/base32core.n Index: embedded/man/files/modules/base32/base32core.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base32/base32core.n @@ -0,0 +1,313 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base32/base32core.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Public domain +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "base32::core" n 0.1 tcllib "Base32 encoding" +.BS +.SH NAME +base32::core \- Expanding basic base32 maps +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBbase32::core ?0.1?\fR +.sp +\fB::base32::core::define\fR \fImap\fR \fIforwvar\fR \fIbackwvar\fR \fIivar\fR +.sp +\fB::base32::core::valid\fR \fIstring\fR \fIpattern\fR \fImvar\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +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. +.SH API +.TP +\fB::base32::core::define\fR \fImap\fR \fIforwvar\fR \fIbackwvar\fR \fIivar\fR +This command computes full forward and backward (inverse) mappings +from the basic \fImap\fR and stores them in the variables named by +\fIforwvar\fR and \fIbackwvar\fR 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 \fIivar\fR. +.TP +\fB::base32::core::valid\fR \fIstring\fR \fIpattern\fR \fImvar\fR +This command checks if the input \fIstring\fR is a valid base32 +encoded string, based on the \fIpattern\fR of invalid characters as +generated by \fB::base32::core::define\fR, and some other general +rules. +.sp +The result of the command is a boolean flag. Its value is \fBTrue\fR +for a valid \fIstring\fR, and \fBFalse\fR otherwise. In the latter +case an error message describing the problem with the input is stored +into the variable named by \fImvar\fR. The variable is not touched if +the input was found to be valid. +.sp +The rules checked by the command, beyond rejection of bad characters, +are: +.RS +.IP [1] +The length of the input is not a multiple of eight, +.IP [2] +The padding appears not at the end of input, but in the middle, +.IP [3] +The padding has not of length six, four, three, or one characters, +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase32\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +base32 +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) Public domain + +.fi ADDED embedded/man/files/modules/base32/base32hex.n Index: embedded/man/files/modules/base32/base32hex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base32/base32hex.n @@ -0,0 +1,327 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base32/base32hex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Public domain +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "base32::hex" n 0.1 tcllib "Base32 encoding" +.BS +.SH NAME +base32::hex \- base32 extended hex encoding +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBbase32::core ?0.1?\fR +.sp +package require \fBbase32::hex ?0.1?\fR +.sp +\fB::base32::hex::encode\fR \fIstring\fR +.sp +\fB::base32::hex::decode\fR \fIestring\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH API +.TP +\fB::base32::hex::encode\fR \fIstring\fR +This command encodes the given \fIstring\fR in extended hex base32 and +returns the encoded string as its result. The result may be padded +with the character \fB=\fR to signal a partial encoding at the end +of the input string. +.TP +\fB::base32::hex::decode\fR \fIestring\fR +This commands takes the \fIestring\fR 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. +.sp +Note that while the encoder will generate only uppercase characters +this decoder accepts input in lowercase as well. +.sp +The command will always throw an error whenever encountering +conditions which signal some type of bogus input, namely if +.RS +.IP [1] +the input contains characters which are not valid output +of a extended hex base32 encoder, +.IP [2] +the length of the input is not a multiple of eight, +.IP [3] +padding appears not at the end of input, but in the middle, +.IP [4] +the padding has not of length six, four, three, or one characters, +.RE +.PP +.SH "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. +.CS + + + 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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase32\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +base32, hex, rfc3548 +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) Public domain + +.fi ADDED embedded/man/files/modules/base64/ascii85.n Index: embedded/man/files/modules/base64/ascii85.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base64/ascii85.n @@ -0,0 +1,326 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base64/ascii85.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010, Emiliano Gavilán +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ascii85" n 1.0 tcllib "Text encoding & decoding binary data" +.BS +.SH NAME +ascii85 \- ascii85-encode/decode binary data +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBascii85 ?1.0?\fR +.sp +\fB::ascii85::encode\fR ?\fB-maxlen\fR \fImaxlen\fR? ?\fB-wrapchar\fR \fIwrapchar\fR? \fIstring\fR +.sp +\fB::ascii85::decode\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides procedures to encode binary data into ascii85 and back. +.TP +\fB::ascii85::encode\fR ?\fB-maxlen\fR \fImaxlen\fR? ?\fB-wrapchar\fR \fIwrapchar\fR? \fIstring\fR +Ascii85 encodes the given binary \fIstring\fR and returns the encoded +result. Inserts the character \fIwrapchar\fR every \fImaxlen\fR +characters of output. \fIwrapchar\fR defaults to newline. \fImaxlen\fR +defaults to \fB76\fR. +.sp +\fINote well\fR: If your string is not simple ascii you should fix +the string encoding before doing ascii85 encoding. See the examples. +.sp +The command will throw an error for negative values of \fImaxlen\fR, +or if \fImaxlen\fR is not an integer number. +.TP +\fB::ascii85::decode\fR \fIstring\fR +Ascii85 decodes the given \fIstring\fR and returns the binary data. +The decoder ignores whitespace in the string, as well as tabs and +newlines. +.PP +.SH EXAMPLES +.CS + + +% ascii85::encode "Hello, world" +87cURD_*#TDfTZ) + +.CE +.CS + + +% 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^] + +.CE +.CS + + +# 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]] + +.CE +.SH REFERENCES +.IP [1] +\fIhttp://en.wikipedia.org/wiki/Ascii85\fR +.IP [2] +Postscript Language Reference Manual, 3rd Edition, page 131. +\fIhttp://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase64\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ascii85, encoding +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2010, Emiliano Gavilán + +.fi ADDED embedded/man/files/modules/base64/base64.n Index: embedded/man/files/modules/base64/base64.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base64/base64.n @@ -0,0 +1,323 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base64/base64.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2000, Eric Melski +'\" Copyright (c) 2001, Miguel Sofer +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "base64" n 2.4.2 tcllib "Text encoding & decoding binary data" +.BS +.SH NAME +base64 \- base64-encode/decode binary data +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBbase64 ?2.4.2?\fR +.sp +\fB::base64::encode\fR ?\fB-maxlen\fR \fImaxlen\fR? ?\fB-wrapchar\fR \fIwrapchar\fR? \fIstring\fR +.sp +\fB::base64::decode\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides procedures to encode binary data into base64 and back. +.TP +\fB::base64::encode\fR ?\fB-maxlen\fR \fImaxlen\fR? ?\fB-wrapchar\fR \fIwrapchar\fR? \fIstring\fR +Base64 encodes the given binary \fIstring\fR and returns the encoded +result. Inserts the character \fIwrapchar\fR every \fImaxlen\fR +characters of output. \fIwrapchar\fR defaults to newline. \fImaxlen\fR +defaults to \fB76\fR. +.sp +\fINote\fR that if \fImaxlen\fR is set to \fB0\fR, the +output will not be wrapped at all. +.sp +\fINote well\fR: If your string is not simple ascii you should fix +the string encoding before doing base64 encoding. See the examples. +.sp +The command will throw an error for negative values of \fImaxlen\fR, +or if \fImaxlen\fR is not an integer number. +.TP +\fB::base64::decode\fR \fIstring\fR +Base64 decodes the given \fIstring\fR and returns the binary data. +The decoder ignores whitespace in the string. +.PP +.SH EXAMPLES +.CS + + +% base64::encode "Hello, world" +SGVsbG8sIHdvcmxk + +.CE +.CS + + +% base64::encode [string repeat xyz 20] +eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6 +eHl6eHl6eHl6 +% base64::encode -wrapchar "" [string repeat xyz 20] +eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6 + +.CE +.CS + + +# 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]] + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase64\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +base64, encoding +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2000, Eric Melski +Copyright (c) 2001, Miguel Sofer + +.fi ADDED embedded/man/files/modules/base64/uuencode.n Index: embedded/man/files/modules/base64/uuencode.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base64/uuencode.n @@ -0,0 +1,351 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base64/uuencode.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uuencode" n 1.1.4 tcllib "Text encoding & decoding binary data" +.BS +.SH NAME +uuencode \- UU-encode/decode binary data +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBuuencode ?1.1.4?\fR +.sp +\fB::uuencode::encode\fR \fIstring\fR +.sp +\fB::uuencode::decode\fR \fIstring\fR +.sp +\fB::uuencode::uuencode\fR ?\fB-name\fR \fIstring\fR? ?\fB-mode\fR \fIoctal\fR? (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +.sp +\fB::uuencode::uudecode\fR (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a Tcl-only implementation of the +\fBuuencode(1)\fR and \fBuudecode(1)\fR commands. This encoding +packs binary data into printable ASCII characters. +.TP +\fB::uuencode::encode\fR \fIstring\fR +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. +.TP +\fB::uuencode::decode\fR \fIstring\fR +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). +.TP +\fB::uuencode::uuencode\fR ?\fB-name\fR \fIstring\fR? ?\fB-mode\fR \fIoctal\fR? (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +.TP +\fB::uuencode::uudecode\fR (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +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. +.PP +.SH OPTIONS +.TP +-filename name +Cause the uuencode or uudecode commands to read their data from the +named file rather that taking a string parameter. +.TP +-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". +.TP +-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 \fBchmod(1)\fR. +.PP +.SH EXAMPLES +.PP +.CS + + +% set d [uuencode::encode "Hello World!"] +2&5L;&\\\\@5V]R;&0A + +.CE +.PP +.CS + + +% uuencode::uudecode $d +Hello World! + +.CE +.PP +.CS + + +% set d [uuencode::uuencode -name hello.txt "Hello World"] +begin 644 hello.txt ++2&5L;&\\@5V]R;&0` +` +end + +.CE +.PP +.CS + + +% uuencode::uudecode $d +{hello.txt 644 {Hello World}} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase64\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +encoding, uuencode +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/base64/yencode.n Index: embedded/man/files/modules/base64/yencode.n ================================================================== --- /dev/null +++ embedded/man/files/modules/base64/yencode.n @@ -0,0 +1,334 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/base64/yencode.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "yencode" n 1.1.2 tcllib "Text encoding & decoding binary data" +.BS +.SH NAME +yencode \- Y-encode/decode binary data +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fByencode ?1.1.2?\fR +.sp +\fB::yencode::encode\fR \fIstring\fR +.sp +\fB::yencode::decode\fR \fIstring\fR +.sp +\fB::yencode::yencode\fR ?\fB-name\fR \fIstring\fR? ?\fB-line\fR \fIinteger\fR? ?\fB-crc32\fR \fIboolean\fR? (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +.sp +\fB::yencode::ydecode\fR (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +.sp +.BE +.SH DESCRIPTION +.PP +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 \fINNTP\fR posting protocols. See +\fIhttp://www.yenc.org/\fR for details concerning the algorithm. +.TP +\fB::yencode::encode\fR \fIstring\fR +returns the yEnc encoded data. +.TP +\fB::yencode::decode\fR \fIstring\fR +Decodes the given yEnc encoded data. +.TP +\fB::yencode::yencode\fR ?\fB-name\fR \fIstring\fR? ?\fB-line\fR \fIinteger\fR? ?\fB-crc32\fR \fIboolean\fR? (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +Encode a file or block of data. +.TP +\fB::yencode::ydecode\fR (\fB-file\fR \fIfilename\fR | ?\fB--\fR? \fIstring\fR) +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. +.PP +.SH OPTIONS +.TP +-filename name +Cause the yencode or ydecode commands to read their data from the +named file rather that taking a string parameter. +.TP +-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". +.TP +-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. +.TP +-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 +\fItrue\fR to \fIfalse\fR. +.PP +.PP +.CS + + +% 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 + +.CE +.SH REFERENCES +.IP [1] +\fIhttp://www.yenc.org/yenc-draft.1.3.txt\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbase64\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +encoding, yEnc, ydecode, yencode +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/bee/bee.n Index: embedded/man/files/modules/bee/bee.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bee/bee.n @@ -0,0 +1,544 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bee/bee.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bee" n 0.1 tcllib "BitTorrent" +.BS +.SH NAME +bee \- BitTorrent Serialization Format Encoder/Decoder +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBbee ?0.1?\fR +.sp +\fB::bee::encodeString\fR \fIstring\fR +.sp +\fB::bee::encodeNumber\fR \fIinteger\fR +.sp +\fB::bee::encodeListArgs\fR \fIvalue\fR... +.sp +\fB::bee::encodeList\fR \fIlist\fR +.sp +\fB::bee::encodeDictArgs\fR \fIkey\fR \fIvalue\fR... +.sp +\fB::bee::encodeDict\fR \fIdict\fR +.sp +\fB::bee::decode\fR \fIstring\fR ?\fIendvar\fR? ?\fIstart\fR? +.sp +\fB::bee::decodeIndices\fR \fIstring\fR ?\fIendvar\fR? ?\fIstart\fR? +.sp +\fB::bee::decodeChannel\fR \fIchan\fR \fB-command\fR \fIcmdprefix\fR ?\fB-exact\fR? ?\fB-prefix\fR \fIdata\fR? +.sp +\fBcmdprefix\fR \fBeof\fR \fItoken\fR +.sp +\fBcmdprefix\fR \fBerror\fR \fItoken\fR \fImessage\fR +.sp +\fBcmdprefix\fR \fBvalue\fR \fItoken\fR \fIvalue\fR +.sp +\fB::bee::decodeCancel\fR \fItoken\fR +.sp +\fB::bee::decodePush\fR \fItoken\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBbee\fR package provides de- and encoder commands for data +in bencoding (speak 'bee'), the serialization format for data and +messages used by the BitTorrent application. +.PP +.SH "PUBLIC API" +.SS 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. +.PP +.TP +\fB::bee::encodeString\fR \fIstring\fR +Returns the bee-encoding of the \fIstring\fR. +.TP +\fB::bee::encodeNumber\fR \fIinteger\fR +Returns the bee-encoding of the \fIinteger\fR number. +.TP +\fB::bee::encodeListArgs\fR \fIvalue\fR... +Takes zero or more bee-encoded values and returns the bee-encoding of +their list. +.TP +\fB::bee::encodeList\fR \fIlist\fR +Takes a list of bee-encoded values and returns the bee-encoding of the +list. +.TP +\fB::bee::encodeDictArgs\fR \fIkey\fR \fIvalue\fR... +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. +.TP +\fB::bee::encodeDict\fR \fIdict\fR +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. +.PP +.PP +.SS 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. +.PP +.TP +\fB::bee::decode\fR \fIstring\fR ?\fIendvar\fR? ?\fIstart\fR? +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. +.sp +If the optional \fIendvar\fR is set then it is the name of a variable +to store the index of the first character \fIafter\fR the decoded +value into. In other words, if the string contains more than one value +then \fIendvar\fR can be used to obtain the position of the bee-value +after the bee-value currently decoded. together with \fIstart\fR, see +below, it is possible to iterate over the string to extract all +contained values. +.sp +The optional \fIstart\fR index defaults to \fB0\fR, i.e. the +beginning of the string. It is the index of the first character of the +bee-encoded value to extract. +.TP +\fB::bee::decodeIndices\fR \fIstring\fR ?\fIendvar\fR? ?\fIstart\fR? +Takes the same arguments as \fB::bee::decode\fR and returns the same +information in \fIendvar\fR. The result however is different. Instead +of the tcl value contained in the \fIstring\fR 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. +.sp +Formally the results for the various types of bee-values are: +.RS +.TP +string +A list containing three elements: +.RS +.IP \(bu +The constant string \fBstring\fR, denoting the type of the value. +.IP \(bu +An integer number greater than or equal to zero. This is the index of +the first character of the bee-value in the input \fIstring\fR. +.IP \(bu +An integer number greater than or equal to zero. This is the index of +the last character of the bee-value in the input \fIstring\fR. +.RE +.sp +\fINote\fR 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. +.TP +integer +The result is like for strings, except that the type element contains +the constant string \fBinteger\fR. +.TP +list +The result is like before, with two exceptions: One, the type element +contains the constant string \fBlist\fR. 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. +.TP +dictionary +The result is like for strings, except that the type element contains +the constant string \fBdict\fR. 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. +.RE +.sp +.TP +\fB::bee::decodeChannel\fR \fIchan\fR \fB-command\fR \fIcmdprefix\fR ?\fB-exact\fR? ?\fB-prefix\fR \fIdata\fR? +The command creates a decoder for a series of bee-values arriving on +the channel \fIchan\fR and returns its handle. This handle can be used +to remove the decoder again. +Setting up another bee decoder on \fIchan\fR while a bee decoder is +still active will fail with an error message. +.sp +.RS +.TP +\fB-command\fR +The command prefix \fIcmdprefix\fR specified by the \fIrequired\fR +option \fB-command\fR 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 +.sp +.RS +.TP +\fBcmdprefix\fR \fBeof\fR \fItoken\fR +The decoder has reached eof on the channel \fIchan\fR. 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 \fItoken\fR is +not valid anymore as well. +.TP +\fBcmdprefix\fR \fBerror\fR \fItoken\fR \fImessage\fR +The decoder encountered an error, which is not eof. For example a +malformed bee-value. The \fImessage\fR 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. +.TP +\fBcmdprefix\fR \fBvalue\fR \fItoken\fR \fIvalue\fR +The decoder received and successfully decoded a bee-value. +The format of the equivalent tcl \fIvalue\fR is the same as returned +by \fB::bee::decode\fR. The channel is still open and the decoder +token is valid. This means that the callback is able to remove the +decoder. +.RE +.sp +.TP +\fB-exact\fR +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. +.sp +The \fB-exact\fR 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. +.sp +.TP +\fB-prefix\fR +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. +.RE +.sp +.TP +\fB::bee::decodeCancel\fR \fItoken\fR +This command cancels the decoder set up by \fB::bee::decodeChannel\fR +and represented by the handle \fItoken\fR. +.TP +\fB::bee::decodePush\fR \fItoken\fR \fIstring\fR +This command appends the \fIstring\fR to the internal decoder +buffer. It is the runtime equivalent of the option \fB-prefix\fR of +\fB::bee::decodeChannel\fR. Use it to push data back into the decoder +when the \fBvalue\fR callback used data from the channel to +determine if it should decode another bee-value or not. +.PP +.PP +.SH "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. +.PP +.TP +String \fIS\fR +A string \fIS\fR of length \fIL\fR is encoded by the string +"\fIL\fR\fB:\fR\fIS\fR", where the length is written out in textual +form. +.TP +Integer \fIN\fR +An integer number \fIN\fR is encoded by the string +"\fBi\fR\fIN\fR\fBe\fR". +.TP +List \fIv1\fR ... \fIvn\fR +A list of the values \fIv1\fR to \fIvn\fR is encoded by the string +"\fBl\fR\fIBV1\fR...\fIBVn\fR\fBe\fR" +where "BV\fBi\fR" is the bee-encoding of the value "v\fBi\fR". +.TP +Dict \fIk1\fR -> \fIv1\fR ... +A dictionary mapping the string key \fIk\fR\fBi\fR to the value +\fIv\fR\fBi\fR, for \fBi\fR in \fB1\fR ... \fBn\fR +is encoded by the string +"\fBd\fR\fIBK\fR\fBi\fR\fIBV\fR\fBi\fR...\fBe\fR" +for i in \fB1\fR ... \fBn\fR, where "BK\fBi\fR" is the bee-encoding +of the key string "k\fBi\fR". and "BV\fBi\fR" is the bee-encoding of +the value "v\fBi\fR". +.sp +\fINote\fR: 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". +.PP +.PP +Note that the type of each encoded item can be determined immediately +from the first character of its representation: +.PP +.TP +i +Integer. +.TP +l +List. +.TP +d +Dictionary. +.TP +[0-9] +String. +.PP +.PP +By wrapping an integer number into \fBi\fR...\fBe\fR the format +makes sure that they are different from strings, which all begin with +a digit. +.SH EXAMPLES +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbee\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +BitTorrent, bee, bittorrent, serialization, torrent +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench.n Index: embedded/man/files/modules/bench/bench.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench.n @@ -0,0 +1,486 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench" n 0.4 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench \- bench - Processing benchmark suites +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBbench ?0.4?\fR +.sp +\fB::bench::locate\fR \fIpattern\fR \fIpaths\fR +.sp +\fB::bench::run\fR ?\fIoption value\fR...? \fIinterp_list\fR \fIfile\fR... +.sp +\fB::bench::versions\fR \fIinterp_list\fR +.sp +\fB::bench::del\fR \fIbench_result\fR \fIcolumn\fR +.sp +\fB::bench::edit\fR \fIbench_result\fR \fIcolumn\fR \fInewvalue\fR +.sp +\fB::bench::merge\fR \fIbench_result\fR... +.sp +\fB::bench::norm\fR \fIbench_result\fR \fIcolumn\fR +.sp +\fB::bench::out::raw\fR \fIbench_result\fR +.sp +.BE +.SH 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. +.PP +A reader interested in the bench language itself should start with the +\fIbench language introduction\fR and proceed from there to the +formal \fIbench language specification\fR. +.PP +.SH "PUBLIC API" +.SS "BENCHMARK EXECUTION" +.TP +\fB::bench::locate\fR \fIpattern\fR \fIpaths\fR +This command locates Tcl interpreters and returns a list containing +their paths. It searches them in the list of \fIpaths\fR specified by +the caller, using the glob \fIpattern\fR. +.sp +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. +.TP +\fB::bench::run\fR ?\fIoption value\fR...? \fIinterp_list\fR \fIfile\fR... +This command executes the benchmarks declared in the set of files, +once per Tcl interpreter specified via the \fIinterp_list\fR, and per +the configuration specified by the options, and then returns the +accumulated timing results. The format of this result is described in +section \fBResult format\fR. +.sp +It is assumed that the contents of the files are written in the bench +language. +.sp +The available options are +.RS +.TP +\fB-errors\fR \fIflag\fR +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. +.TP +\fB-threads\fR \fIn\fR +The argument is a non-negative integer value declaring the number of +threads to use while executing the benchmarks. The default value is +\fB0\fR, to not use threads. +.TP +\fB-match\fR \fIpattern\fR +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. +.TP +\fB-rmatch\fR \fIpattern\fR +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. +.TP +\fB-iters\fR \fIn\fR +The argument is positive integer number, the maximal number of +iterations for any benchmark. The default is \fB1000\fR. Individual +benchmarks can override this. +.TP +\fB-pkgdir\fR \fIpath\fR +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. +.sp +If no paths were specified the system will behave as before. +If one or more paths are specified, say \fBN\fR, each of the specified +interpreters will be invoked \fBN\fR times, with one of the specified +paths. The chosen path is put into the interpreters' \fBauto_path\fR, +thus allowing it to find specific versions of a package. +.sp +In this way the use of \fB-pkgdir\fR allows the user to benchmark +several different versions of a package, against one or more interpreters. +.sp +\fINote:\fR The empty string is allowed as a path and causes the system to +run the specified interpreters with an unmodified \fBauto_path\fR. In case +the package in question is available there as well. +.RE +.sp +.TP +\fB::bench::versions\fR \fIinterp_list\fR +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. +.sp +The command uses builtin command \fBinfo patchlevel\fR to determine +the version of each interpreter. +.PP +.SS "RESULT MANIPULATION" +.TP +\fB::bench::del\fR \fIbench_result\fR \fIcolumn\fR +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. +.sp +The benchmark results are in the format described in section +\fBResult format\fR. +.sp +The column is identified by an integer number. +.TP +\fB::bench::edit\fR \fIbench_result\fR \fIcolumn\fR \fInewvalue\fR +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. +.sp +The benchmark results are in the format described in section +\fBResult format\fR. +.sp +The column is identified by an integer number. +.TP +\fB::bench::merge\fR \fIbench_result\fR... +This commands takes one or more benchmark results, merges them into +one big result, and returns that as its result. +.sp +All benchmark results are in the format described in section +\fBResult format\fR. +.TP +\fB::bench::norm\fR \fIbench_result\fR \fIcolumn\fR +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. +.sp +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 \fB1\fR, as these benchmarks are +neither faster nor slower than the baseline. +.sp +A factor less than \fB1\fR indicates a benchmark which was faster +than the baseline, whereas a factor greater than \fB1\fR indicates a +slower execution. +.sp +The benchmark results are in the format described in section +\fBResult format\fR. +.sp +The column is identified by an integer number. +.TP +\fB::bench::out::raw\fR \fIbench_result\fR +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. +.sp +For other formatting styles see the packages \fBbench::out::text\fR +and \fBbench::out::csv\fR which provide commands to format +benchmark results for human consumption, or as CSV data importable by +spread sheets, respectively. +.sp +Complementary, to read benchmark results from files, sockets etc. look +for the package \fBbench::in\fR and the commands provided by it. +.PP +.SS "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. +.PP +The possible keys are all valid Tcl lists of two or three elements and +have one of the following forms: +.TP +{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. +.sp +The associated value is the version of the Tcl interpreter. +.TP +{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. +.sp +The associated value is irrelevant, and set to the empty string. +.TP +{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. +.sp +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 +.RS +.TP +ERR +Benchmark could not be executed, failed with a Tcl error. +.TP +BAD_RES +The benchmark could be executed, however the result from its body did +not match the declared expectations. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +bench_intro, bench_lang_intro, bench_lang_spec, bench_read, bench_wcsv, bench_wtext +.SH KEYWORDS +benchmark, merging, normalization, performance, testing +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_intro.n Index: embedded/man/files/modules/bench/bench_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_intro.n @@ -0,0 +1,296 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench_intro" n 1.0 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench_intro \- bench introduction +.SH DESCRIPTION +.PP +The \fIbench\fR (short for \fIbenchmark tools\fR), 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 +.IP [1] +A tcl based language for the declaration of test cases. A test case is +represented by a tcl command declaring the various parts needed to +execute it, like setup, cleanup, the commands to test, etc. +.IP [2] +A package providing the ability to execute test cases written in that +language. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the benchmarking process. +.PP +.IP [1] +A \fIwriter\fR of benchmarks has to understand the bench language +itself. A beginner to bench should read the more informally written +\fIbench language introduction\fR first. Having digested this the +formal \fIbench language specification\fR should become +understandable. A writer experienced with bench may only need this +last document from time to time, to refresh her memory. +.IP [2] +A \fIuser\fR of benchmark suites written in the \fIbench\fR language +has to know which tools are available for use. +At the bottom level sits the package \fBbench\fR, providing the +basic facilities to read and execute files containing benchmarks +written in the bench language, and to manipulate benchmark results. +.PP +.SH "HISTORICAL NOTES" +This module and package have been derived from Jeff Hobbs' +\fBtclbench\fR application for the benchmarking of the Tcl core and +its ancestor "\fIrunbench.tcl\fR". +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +bench, bench_lang_faq, bench_lang_intro, bench_lang_spec +.SH KEYWORDS +bench language, benchmark, performance, testing +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_lang_intro.n Index: embedded/man/files/modules/bench/bench_lang_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_lang_intro.n @@ -0,0 +1,374 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_lang_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench_lang_intro" n 1.0 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench_lang_intro \- bench language introduction +.SH DESCRIPTION +.PP +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 +\fIbench language specification\fR. +.SS FUNDAMENTALS +In the broadest terms possible the \fIbench language\fR 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. +.PP +.SS BASICS +One of the most simplest benchmarks which can be written in bench is +.CS + + +bench -desc LABEL -body { + set a b +} + +.CE +This code declares a benchmark named \fBLABEL\fR which measures the +time it takes to assign a value to a variable. The Tcl code doing this +assignment is the \fB-body\fR of the benchmark. +.SS "PRE- AND POSTPROCESSING" +Our next example demonstrates how to declare \fIinitialization\fR and +\fIcleanup\fR code, i.e. code computing information for the use of +the \fB-body\fR, and for releasing such resources after the +measurement is done. +They are the \fB-pre\fR- and the \fB-post\fR-body, respectively. +.PP +In our example, directly drawn from the benchmark suite of Tcllib's +\fBaes\fR 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. +.CS + + +bench -desc "AES-${len} ECB encryption core" \fB-pre\fR { + set key [aes::Init ecb $k $i] +} -body { + aes::Encrypt $key $p +} \fB-post\fR { + aes::Final $key +} + +.CE +.SS "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 \fB-body\fR. +.PP +Instead of running the \fB-body\fR just once the system actually +executes the \fB-body\fR 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. +.PP +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. +.PP +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. \fIHowever\fR 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. +.PP +The advanced initialization and cleanup codes, \fB-ipre\fR- and the +\fB-ipost\fR-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. +.PP +Our example, directly drawn from the benchmark suite of Tcllib's +\fBstruct::set\fR 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. +.CS + + +bench -desc "set include, missing x$times $n" \fB-ipre\fR { + set A $sx($times,$n) + set B $A +} -body { + struct::set include A x +} \fB-ipost\fR { + unset A B +} + +.CE +.SH "FURTHER READING" +Now that this document has been digested the reader, assumed to be a +\fIwriter\fR of benchmarks, he should be fortified enough to be able +to understand the formal \fIbench language specfication\fR. It will +also serve as the detailed specification and cheat sheet for all +available commands and their syntax. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +bench_intro, bench_lang_spec +.SH KEYWORDS +bench language, benchmark, examples, performance, testing +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_lang_spec.n Index: embedded/man/files/modules/bench/bench_lang_spec.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_lang_spec.n @@ -0,0 +1,364 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_lang_spec.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench_lang_spec" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +bench_lang_spec \- bench language specification +.SH SYNOPSIS +\fBbench_rm\fR \fIpath\fR... +.sp +\fBbench_tmpfile\fR +.sp +\fBbench\fR \fIoptions\fR... +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fIbench language introduction\fR first. +.SH COMMANDS +.TP +\fBbench_rm\fR \fIpath\fR... +This command silently removes the files specified as its arguments and +then returns the empty string as its result. +The command is \fItrusted\fR, there is no checking if the specified +files are outside of whatever restricted area the benchmarks are run +in. +.TP +\fBbench_tmpfile\fR +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 \fInot\fR create aynthing. +.sp +The base location of the temporary files is platform dependent: +.RS +.TP +Unix, and indeterminate platform +"\fI/tmp\fR" +.TP +Windows +\fB$TEMP\fR +.TP +Anything else +The current working directory. +.RE +.sp +.TP +\fBbench\fR \fIoptions\fR... +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: +.RS +.TP +\fB-body\fR script +The argument of this option declares the body of the benchmark, the +Tcl script whose performance we wish to measure. This option, and +\fB-desc\fR, are the two required parts of each benchmark. +.TP +\fB-desc\fR 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. +.sp +\fIBeware!\fR This requirement is not checked when benchmarks are +executed, and the system will silently produce bogus data. This +option, and \fB-body\fR, are the two required parts of each +benchmark. +.TP +\fB-ipost\fR script +The argument of this option declares a script which is run immediately +\fIafter\fR each iteration of the body. Its responsibility is to +release resources created by the body, or \fB-ipre\fR-bodym which +we do not wish to live into the next iteration. +.TP +\fB-ipre\fR script +The argument of this option declares a script which is run immediately +\fIbefore\fR 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. +.TP +\fB-iterations\fR num +The argument of this option declares the maximum number of times to +run the \fB-body\fR of the benchmark. During execution this and the +global maximum number of iterations are compared and the smaller of +the two values is used. +.sp +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. +.TP +\fB-post\fR script +The argument of this option declares a script which is run +\fIafter\fR all iterations of the body have been run. Its +responsibility is to release resources created by the body, +or \fB-pre\fR-body. +.TP +\fB-pre\fR script +The argument of this option declares a script which is run +\fIbefore\fR 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. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +bench_intro, bench_lang_intro +.SH KEYWORDS +bench language, benchmark, performance, specification, testing +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_read.n Index: embedded/man/files/modules/bench/bench_read.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_read.n @@ -0,0 +1,304 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_read.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench::in" n 0.1 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench::in \- bench::in - Reading benchmark results +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcsv \fR +.sp +package require \fBbench::in ?0.1?\fR +.sp +\fB::bench::in::read\fR \fIfile\fR +.sp +.BE +.SH DESCRIPTION +This package provides a command for reading benchmark results from +files, sockets, etc. +.PP +A reader interested in the creation, processing or writing of such +results should go and read +\fIbench - Processing benchmark suites\fR instead. +.PP +If the bench language itself is the actual interest please start with +the \fIbench language introduction\fR and then proceed from there +to the formal \fIbench language specification\fR. +.PP +.SH "PUBLIC API" +.TP +\fB::bench::in::read\fR \fIfile\fR +This command reads a benchmark result from the specified \fIfile\fR +and returns it as its result. The command understands the three +formats created by the commands +.RS +.TP +\fBbench::out::raw\fR +Provided by package \fBbench\fR. +.TP +\fBbench::out::csv\fR +Provided by package \fBbench::out::csv\fR. +.TP +\fBbench::out::text\fR +Provided by package \fBbench::out::text\fR. +.RE +.sp +and automatically detects which format is used by the input file. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +bench, bench::out::csv, bench::out::text, bench_intro +.SH KEYWORDS +benchmark, csv, formatting, human readable, parsing, performance, reading, testing, text +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_wcsv.n Index: embedded/man/files/modules/bench/bench_wcsv.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_wcsv.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_wcsv.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench::out::csv" n 0.1.2 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench::out::csv \- bench::out::csv - Formatting benchmark results as CSV +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBbench::out::csv ?0.1.2?\fR +.sp +\fB::bench::out::csv\fR \fIbench_result\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands for fomatting of benchmark results into +a CSV table importable by spread sheets. +.PP +A reader interested in the generation or processing of such results should +go and read \fIbench - Processing benchmark suites\fR instead. +.PP +If the bench language itself is the actual interest please start with +the \fIbench language introduction\fR and then proceed from there +to the formal \fIbench language specification\fR. +.PP +.SH "PUBLIC API" +.TP +\fB::bench::out::csv\fR \fIbench_result\fR +This command formats the specified benchmark result for output to a +file, socket, etc. This specific command generates CSV data importable +by spread sheets. +.sp +For other formatting styles see the packages \fBbench\fR and +\fBbench::out::text\fR which provide commands to format benchmark +results in raw form, or for human consumption, respectively. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +bench, bench::out::text +.SH KEYWORDS +benchmark, csv, formatting, performance, testing +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bench/bench_wtext.n Index: embedded/man/files/modules/bench/bench_wtext.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bench/bench_wtext.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bench/bench_wtext.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bench::out::text" n 0.1.2 tcllib "Benchmarking/Performance tools" +.BS +.SH NAME +bench::out::text \- bench::out::text - Formatting benchmark results as human readable text +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBbench::out::text ?0.1.2?\fR +.sp +\fB::bench::out::text\fR \fIbench_result\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands for fomatting of benchmark results into +human readable text. +.PP +A reader interested in the generation or processing of such results should +go and read \fIbench - Processing benchmark suites\fR instead. +.PP +If the bench language itself is the actual interest please start with +the \fIbench language introduction\fR and then proceed from there +to the formal \fIbench language specification\fR. +.PP +.SH "PUBLIC API" +.TP +\fB::bench::out::text\fR \fIbench_result\fR +This command formats the specified benchmark result for output to a +file, socket, etc. This specific command generates human readable +text. +.sp +For other formatting styles see the packages \fBbench\fR and +\fBbench::out::csv\fR which provide commands to format benchmark +results in raw form, or as importable CSV data, respectively. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbench\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +bench, bench::out::csv +.SH KEYWORDS +benchmark, formatting, human readable, performance, testing, text +.SH CATEGORY +Benchmark tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/bibtex/bibtex.n Index: embedded/man/files/modules/bibtex/bibtex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/bibtex/bibtex.n @@ -0,0 +1,397 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/bibtex/bibtex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 for documentation, Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "bibtex" n 0.5 tcllib "bibtex" +.BS +.SH NAME +bibtex \- Parse bibtex files +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBbibtex ?0.5?\fR +.sp +\fB::bibtex::parse\fR ?\fIoptions\fR? ?\fItext\fR? +.sp +\fB::bibtex::parse\fR \fItext\fR +.sp +\fB::bibtex::parse\fR ?\fB-command\fR \fIcmd\fR? \fB-channel\fR \fIchan\fR +.sp +\fB::bibtex::parse\fR ?\fB-recordcommand\fR \fIrecordcmd\fR? ?\fB-preamblecommand\fR \fIpreamblecmd\fR? ?\fB-stringcommand\fR \fIstringcmd\fR? ?\fB-commentcommand\fR \fIcommentcmd\fR? ?\fB-progresscommand\fR \fIprogresscmd\fR? (\fItext\fR | \fB-channel\fR \fIchan\fR) +.sp +\fB::bibtex::wait\fR \fItoken\fR +.sp +\fB::bibtex::destroy\fR \fItoken\fR +.sp +\fB::bibtex::addStrings\fR \fItoken\fR \fIstringdict\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides commands for the parsing of bibliographies in +BibTeX format. +.TP +\fB::bibtex::parse\fR ?\fIoptions\fR? ?\fItext\fR? +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. +.TP +\fB::bibtex::parse\fR \fItext\fR +In this form the command will assume that the specified \fItext\fR 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. +.TP +\fB::bibtex::parse\fR ?\fB-command\fR \fIcmd\fR? \fB-channel\fR \fIchan\fR +In this form the command will reads the bibliography from the +specified Tcl channel \fIchan\fR and then returns the same data +structure as described above. +.sp +If however the option \fB-command\fR 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 \fIcmd\fR will be invoked with the result of the parse. The +exact definition for the callback is +.sp +.RS +.TP +\fBcmd\fR \fItoken\fR \fIparseresult\fR +The parse result will have the structure explained above, for the +simpler forms of the parser. +.RE +.sp +\fINote\fR that the parser will \fInot\fR close the channel after it +has exhausted it. This is still the responsibility of the user of the +parser. +.TP +\fB::bibtex::parse\fR ?\fB-recordcommand\fR \fIrecordcmd\fR? ?\fB-preamblecommand\fR \fIpreamblecmd\fR? ?\fB-stringcommand\fR \fIstringcmd\fR? ?\fB-commentcommand\fR \fIcommentcmd\fR? ?\fB-progresscommand\fR \fIprogresscmd\fR? (\fItext\fR | \fB-channel\fR \fIchan\fR) +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. +.sp +The processing will be incremental and happen in the background if, +and only if a Tcl channel \fIchan\fR is specified. For a \fItext\fR +the processing will happen immediately and all callbacks will be +invoked before the command itself returns. +.sp +The callbacks, i.e. \fI*cmd\fR, 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. +.RS +.TP +\fBrecordcmd\fR \fItoken\fR \fItype\fR \fIkey\fR \fIrecorddict\fR +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. +.TP +\fBpreamblecmd\fR \fItoken\fR \fIpreambletext\fR +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. +.TP +\fBstringcmd\fR \fItoken\fR \fIstringdict\fR +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. +.TP +\fBcommentcmd\fR \fItoken\fR \fIcommenttext\fR +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. +.TP +\fBprogresscmd\fR \fItoken\fR \fIpercent\fR +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 \fB0\fR and \fB100\fR. +In the case of incremental processing the perecentage will always be +\fB-1\fR as the total number of entries is not known beforehand. +.RE +.sp +.TP +\fB::bibtex::wait\fR \fItoken\fR +This command waits for the parser represented by the \fItoken\fR to +complete and then returns. The returned result is the empty string. +.TP +\fB::bibtex::destroy\fR \fItoken\fR +This command cleans up all internal state associated with the parser +represented by the handle \fItoken\fR, effectively destroying it. This +command can be called from within the parser callbacks to terminate +processing. +.TP +\fB::bibtex::addStrings\fR \fItoken\fR \fIstringdict\fR +This command adds the macro definitions stored in the +dictionary \fIstringdict\fR to the parser represented +by the handle \fItoken\fR. +.sp +The dictionary keys are the macro names and the values their +replacement strings. This command has the correct signature for use as +a \fB-stringcommand\fR callback in an invokation of the command +\fB::bibtex::parse\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIbibtex\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +bibliography, bibtex, parsing, text processing +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2005 for documentation, Andreas Kupries + +.fi ADDED embedded/man/files/modules/blowfish/blowfish.n Index: embedded/man/files/modules/blowfish/blowfish.n ================================================================== --- /dev/null +++ embedded/man/files/modules/blowfish/blowfish.n @@ -0,0 +1,386 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/blowfish/blowfish.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "blowfish" n 1.0.3 tcllib "Blowfish Block Cipher" +.BS +.SH NAME +blowfish \- Implementation of the Blowfish block cipher +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBblowfish ?1.0.4?\fR +.sp +\fB::blowfish::blowfish\fR ?\fI-mode [ecb|cbc]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? ?\fI-pad padchar\fR? [ \fI-in channel\fR | ?\fI--\fR? \fIdata\fR ] +.sp +\fB::blowfish::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR +.sp +\fB::blowfish::Encrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::blowfish::Decrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::blowfish::Reset\fR \fIKey\fR \fIiv\fR +.sp +\fB::blowfish::Final\fR \fIKey\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::blowfish::blowfish\fR ?\fI-mode [ecb|cbc]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? ?\fI-pad padchar\fR? [ \fI-in channel\fR | ?\fI--\fR? \fIdata\fR ] +Perform the \fBblowfish\fR algorithm on either the data provided +by the argument or on the data read from the \fI-in\fR channel. If +an \fI-out\fR channel is given then the result will be written to +this channel. +.sp +The \fI-key\fR option must be given. This parameter takes a binary +string of variable length and is used to generate the \fBblowfish\fR +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 \fBReset\fR. +.sp +The \fI-mode\fR and \fI-dir\fR options are optional and default to cbc +mode and encrypt respectively. The initialization vector \fI-iv\fR +takes an 8 byte binary argument which defaults to 8 zeros. +See \fBMODES OF OPERATION\fR for more about available modes and +their uses. +.sp +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 \fBblowfish\fR +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 \fI-pad\fR option can be used to +change the padding character or to disable padding if the empty string +is provided as the argument. +.PP +.SH "PROGRAMMING INTERFACE" +.TP +\fB::blowfish::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR +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 \fBMODES OF OPERATION\fR for details about cipher modes. +.TP +\fB::blowfish::Encrypt\fR \fIKey\fR \fIdata\fR +Use a prepared key acquired by calling \fBInit\fR 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. +.TP +\fB::blowfish::Decrypt\fR \fIKey\fR \fIdata\fR +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. +.TP +\fB::blowfish::Reset\fR \fIKey\fR \fIiv\fR +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. +.TP +\fB::blowfish::Final\fR \fIKey\fR +This should be called to clean up resources associated with \fIKey\fR. +Once this function has been called the key may not be used again. +.PP +.SH "MODES OF OPERATION" +.TP +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. +.TP +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. +.PP +.SH EXAMPLES +.CS + + +% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!" +d0d8f27e7a374b9e2dbd9938dd04195a + +.CE +.CS + + + 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 + +.CE +.SH REFERENCES +.IP [1] +Schneier, B. "Applied Cryptography, 2nd edition", 1996, +ISBN 0-471-11709-9, pub. John Wiley & Sons. +.PP +.SH AUTHORS +Frank Pilhofer, Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIblowfish\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +3des, des, rc4 +.SH KEYWORDS +block cipher, blowfish, cryptography, encryption, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2003, Pat Thoyts + +.fi ADDED embedded/man/files/modules/cache/async.n Index: embedded/man/files/modules/cache/async.n ================================================================== --- /dev/null +++ embedded/man/files/modules/cache/async.n @@ -0,0 +1,375 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/cache/async.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "cache::async" n 0.3 tcllib "In-memory caches" +.BS +.SH NAME +cache::async \- Asynchronous in-memory cache +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBcache::async ?0.3?\fR +.sp +\fB::cache::async\fR \fIobjectName\fR \fIcommandprefix\fR ?\fIoptions\fR...? +.sp +\fIobjectName\fR \fBget\fR \fIkey\fR \fIdonecmdprefix\fR +.sp +\fIobjectName\fR \fBset\fR \fIkey\fR \fIvalue\fR +.sp +\fIobjectName\fR \fBunset\fR \fIkey\fR +.sp +\fIobjectName\fR \fBexists\fR \fIkey\fR +.sp +\fIobjectName\fR \fBclear\fR ?\fIkey\fR? +.sp +.BE +.SH 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. +.SH API +The package exports a class, \fBcache::async\fR, as specified +below. +.TP +\fB::cache::async\fR \fIobjectName\fR \fIcommandprefix\fR ?\fIoptions\fR...? +The command creates a new \fIcache\fR object with an associated +global Tcl command whose name is \fIobjectName\fR. This command may +be used to invoke various operations on the object. +.sp +The \fIcommandprefix\fR 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 +\fBget\fR, 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. +.sp +The only supported option is +.RS +.TP +\fB-full-async-results\fR +This option defines the behaviour of the cache for when requested keys +are known to the cache at the time of \fBget\fR request. By default +such requeste are responded to asynchronously as well. Setting this +option to \fBfalse\fR forces the cache to respond to them +synchronuously, although still through the specified callback. +.RE +.PP +The object commands created by the class commands above have +the form: +.TP +\fIobjectName\fR \fBget\fR \fIkey\fR \fIdonecmdprefix\fR +This method requests the data for the \fIkey\fR 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. +.sp +Whenever the information is/becomes available the \fIdonecmdprefix\fR +will be run to transfer the result to the caller. This command prefix +is invoked with either 2 or 3 arguments, i.e. +.RS +.IP [1] +The string \fBset\fR, the \fIkey\fR, and the value. +.IP [2] +The string \fBunset\fR, and the \fIkey\fR. +.RE +.IP +These two possibilities are used to either signal the value for the +\fIkey\fR, or that the \fIkey\fR has no value defined for it. The +latter is distinct from the cache not knowing about the \fIkey\fR. +.sp +For a cache object configured to be fully asynchronous (default) the +\fIdonecmdprefix\fR is always run in an idle-handler, decoupling it +from the request. Otherwise the callback will be invoked synchronously +when the \fIkey\fR is known to the cache at the time of the +invokation. +.sp +Another important part of the cache's behaviour, as it is asynchronous +it is possible that multiple \fBget\fR requests are issued for the +same \fIkey\fR 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. +.TP +\fIobjectName\fR \fBset\fR \fIkey\fR \fIvalue\fR +.TP +\fIobjectName\fR \fBunset\fR \fIkey\fR +These two methods are provided to allow users of the cache to make +keys known to the cache, as either having a \fIvalue\fR, or as +undefined. +.sp +It is expected that the data provider (see \fIcommandprefix\fR of the +constructor) uses them in response to data requests for unknown keys. +.sp +Note how this matches the cache's own API towards its caller, calling +the \fIdonecmd\fR of \fBget\fR-requests issued to itself with +either "set key value" or "unset key", versus issuing +\fBget\fR-requests to its own provider with itself in the place of +the \fIdonecmd\fR, expecting to be called with either "set key value" +or "unset key". +.sp +This also means that these methods invoke the \fIdonecmd\fR of all +\fBget\fR-requests waiting for information about the modified +\fIkey\fR. +.TP +\fIobjectName\fR \fBexists\fR \fIkey\fR +This method queries the cache for knowledge about the \fIkey\fR and +returns a boolean value. The result is \fBtrue\fR if the key is +known, and \fBfalse\fR otherwise. +.TP +\fIobjectName\fR \fBclear\fR ?\fIkey\fR? +This method resets the state of either the specified \fIkey\fR or of +all keys known to the cache, making it unkown. This forces future +\fBget\fR-requests to reload the information from the provider. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcache\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +asynchronous, cache, callback, synchronous +.SH COPYRIGHT +.nf +Copyright (c) 2008 Andreas Kupries + +.fi ADDED embedded/man/files/modules/clock/iso8601.n Index: embedded/man/files/modules/clock/iso8601.n ================================================================== --- /dev/null +++ embedded/man/files/modules/clock/iso8601.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/clock/iso8601.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "clock_iso8601" n 0.1 tcllib "Date/Time Utilities" +.BS +.SH NAME +clock_iso8601 \- Parsing ISO 8601 dates/times +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBclock::iso8601 ?0.1?\fR +.sp +\fB::clock::iso8601 parse_date\fR \fIdate\fR \fIoptions...\fR +.sp +\fB::clock::iso8601 parse_time\fR \fItime\fR \fIoptions...\fR +.sp +.BE +.SH DESCRIPTION +This package provides functionality to parse dates and times in +ISO 8601 format. +.PP +.TP +\fB::clock::iso8601 parse_date\fR \fIdate\fR \fIoptions...\fR +This command parses an ISO8601 date string in an unknown variant and +returns the given date/time in seconds since epoch. +.sp +The acceptable options are +\fB-base\fR, +\fB-gmt\fR, +\fB-locale\fR, and +\fB-timezone\fR +of the builtin command \fBclock scan\fR. +.TP +\fB::clock::iso8601 parse_time\fR \fItime\fR \fIoptions...\fR +This command parses a full ISO8601 timestamp string (date and time) in +an unknown variant and returns the given time in seconds since epoch. +.sp +The acceptable options are +\fB-base\fR, +\fB-gmt\fR, +\fB-locale\fR, and +\fB-timezone\fR +of the builtin command \fBclock scan\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIclock::iso8601\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/clock/rfc2822.n Index: embedded/man/files/modules/clock/rfc2822.n ================================================================== --- /dev/null +++ embedded/man/files/modules/clock/rfc2822.n @@ -0,0 +1,270 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/clock/rfc2822.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "clock_rfc2822" n 0.1 tcllib "Date/Time Utilities" +.BS +.SH NAME +clock_rfc2822 \- Parsing ISO 8601 dates/times +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBclock::rfc2822 ?0.1?\fR +.sp +\fB::clock::rfc2822 parse_date\fR \fIdate\fR +.sp +.BE +.SH DESCRIPTION +This package provides functionality to parse dates in +RFC 2822 format. +.PP +.TP +\fB::clock::rfc2822 parse_date\fR \fIdate\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIclock::rfc2822\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/cmdline/cmdline.n Index: embedded/man/files/modules/cmdline/cmdline.n ================================================================== --- /dev/null +++ embedded/man/files/modules/cmdline/cmdline.n @@ -0,0 +1,400 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/cmdline/cmdline.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "cmdline" n 1.3.3 tcllib "Command line and option processing" +.BS +.SH NAME +cmdline \- Procedures to process command lines and options. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcmdline ?1.3.3?\fR +.sp +\fB::cmdline::getopt\fR \fIargvVar\fR \fIoptstring\fR \fIoptVar\fR \fIvalVar\fR +.sp +\fB::cmdline::getKnownOpt\fR \fIargvVar\fR \fIoptstring\fR \fIoptVar\fR \fIvalVar\fR +.sp +\fB::cmdline::getoptions\fR \fIarglistVar\fR \fIoptlist\fR ?\fIusage\fR? +.sp +\fB::cmdline::getKnownOptions\fR \fIarglistVar\fR \fIoptlist\fR ?\fIusage\fR? +.sp +\fB::cmdline::usage\fR \fIoptlist\fR ?\fIusage\fR? +.sp +\fB::cmdline::getfiles\fR \fIpatterns\fR \fIquiet\fR +.sp +\fB::cmdline::getArgv0\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands to parse command lines and options. +.SH "::ARGV HANDLING" +One of the most common variables this package will be used with is +\fB::argv\fR, which holds the command line of the current +application. This variable has a companion \fB::argc\fR which is +initialized to the number of elements in \fB::argv\fR at the beginning +of the application. +.PP +The commands in this package will \fInot\fR modify the \fB::argc\fR +companion when called with \fB::argv\fR. Keeping the value consistent, +if such is desired or required, is the responsibility of the caller. +.SH API +.TP +\fB::cmdline::getopt\fR \fIargvVar\fR \fIoptstring\fR \fIoptVar\fR \fIvalVar\fR +This command works in a fashion like the standard C based \fBgetopt\fR +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. +.sp +\fIargvVar\fR contains the name of the list of arguments to +process. If options are found the list is modified and the processed +arguments are removed from the start of the list. +.sp +\fIoptstring\fR 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. Otherwise +the option is a boolean that is set to 1 if present. +.sp +\fIoptVar\fR refers to the variable the command will store the found +option into (without the leading '-' and without the .arg extension). +.sp +\fIvalVar\fR 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. +.TP +\fB::cmdline::getKnownOpt\fR \fIargvVar\fR \fIoptstring\fR \fIoptVar\fR \fIvalVar\fR +Like \fB::cmdline::getopt\fR, but ignores any unknown options in the +input. +.TP +\fB::cmdline::getoptions\fR \fIarglistVar\fR \fIoptlist\fR ?\fIusage\fR? +Processes the set of command line options found in the list variable +named by \fIarglistVar\fR 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 +\fIusage\fR-argument contains a string to include in front of the +generated message. If not present it defaults to "options:". +.sp +\fIoptlist\fR contains a list of lists where each element specifies an +option in the form: \fIflag\fR \fIdefault\fR \fIcomment\fR. +.sp +If \fIflag\fR ends in ".arg" then the value is taken from the command +line. Otherwise it is a boolean and appears in the result if present +on the command line. If \fIflag\fR ends in ".secret", it will not be +displayed in the usage. +.sp +The options \fB-?\fR, \fB-help\fR, and \fB--\fR are +implicitly understood. The first two abort option processing 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. +.sp +The result of the command is a dictionary mapping all options to their +values, be they user-specified or defaults. +.TP +\fB::cmdline::getKnownOptions\fR \fIarglistVar\fR \fIoptlist\fR ?\fIusage\fR? +Like \fB::cmdline::getoptions\fR, but ignores any unknown options in the +input. +.TP +\fB::cmdline::usage\fR \fIoptlist\fR ?\fIusage\fR? +Generates and returns an error message that lists the allowed +flags. \fIoptlist\fR is defined as for +\fB::cmdline::getoptions\fR. The optional \fIusage\fR-argument +contains a string to include in front of the generated message. If not +present it defaults to "options:". +.TP +\fB::cmdline::getfiles\fR \fIpatterns\fR \fIquiet\fR +Given a list of file \fIpatterns\fR 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 \fIquiet\fR to +true). +.sp +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. +.TP +\fB::cmdline::getArgv0\fR +This command returns the "sanitized" version of \fIargv0\fR. 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. +.PP +.SH EXAMPLES +.CS + + + 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:" + array set params [::cmdline::getoptions argv $options $usage] + + 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} { + ... + } + +.CE +.PP +This example, taken (and slightly modified) from the package +\fBfileutil\fR, 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcmdline\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +argument processing, argv, argv0, cmdline processing, command line processing +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/comm/comm.n Index: embedded/man/files/modules/comm/comm.n ================================================================== --- /dev/null +++ embedded/man/files/modules/comm/comm.n @@ -0,0 +1,1309 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/comm/comm.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 1995-1998 The Open Group. All Rights Reserved. +'\" Copyright (c) 2003-2004 ActiveState Corporation. +'\" Copyright (c) 2006-2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "comm" n 4.6.2 tcllib "Remote communication" +.BS +.SH NAME +comm \- A remote communication facility for Tcl (8.3 and later) +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBcomm ?4.6.2?\fR +.sp +\fB::comm::comm send\fR ?-async? ?-command \fIcallback\fR? \fIid\fR \fIcmd\fR ?\fIarg arg ...\fR? +.sp +\fB::comm::comm self\fR +.sp +\fB::comm::comm interps\fR +.sp +\fB::comm::comm connect\fR ?\fIid\fR? +.sp +\fB::comm::comm new\fR \fIchan\fR ?\fIname value ...\fR? +.sp +\fB::comm::comm channels\fR +.sp +\fB::comm::comm config\fR +.sp +\fB::comm::comm config\fR \fIname\fR +.sp +\fB::comm::comm config\fR ?\fIname\fR \fIvalue\fR \fI...\fR? +.sp +\fB::comm::comm shutdown\fR \fIid\fR +.sp +\fB::comm::comm abort\fR +.sp +\fB::comm::comm destroy\fR +.sp +\fB::comm::comm hook\fR \fIevent\fR ?\fB+\fR? ?\fIscript\fR? +.sp +\fB::comm::comm remoteid\fR +.sp +\fB::comm::comm_send\fR +.sp +\fB::comm::comm return_async\fR +.sp +\fB$future\fR \fBreturn\fR ?\fB-code\fR \fIcode\fR? ?\fIvalue\fR? +.sp +\fB$future\fR \fBconfigure\fR ?\fB-command\fR ?\fIcmdprefix\fR?? +.sp +\fB$future\fR \fBcget\fR \fB-command\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBcomm\fR command provides an inter-interpreter remote +execution facility much like Tk's \fBsend(n)\fR, except that it uses +sockets rather than the X server for the communication path. As a +result, \fBcomm\fR works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path. +.PP +These commands work just like \fBsend\fR and \fBwinfo interps\fR : +.PP +.CS + + + ::comm::comm send ?-async? id cmd ?arg arg ...? + ::comm::comm interps + +.CE +.PP +This is all that is really needed to know in order to use +\fBcomm\fR +.SS COMMANDS +The package initializes \fB::comm::comm\fR as the default \fIchan\fR. +.PP +\fBcomm\fR names communication endpoints with an \fIid\fR unique +to each machine. Before sending commands, the \fIid\fR of another +interpreter is needed. Unlike Tk's send, \fBcomm\fR doesn't +implicitly know the \fIid\fR's of all the interpreters on the system. +The following four methods make up the basic \fBcomm\fR interface. +.TP +\fB::comm::comm send\fR ?-async? ?-command \fIcallback\fR? \fIid\fR \fIcmd\fR ?\fIarg arg ...\fR? +This invokes the given command in the interpreter named by \fIid\fR. The +command waits for the result and remote errors are returned unless the +\fB-async\fR or \fB-command\fR option is given. If \fB-async\fR +is given, send returns immediately and there is no further notification of +result. If \fB-command\fR is used, \fIcallback\fR specifies a command +to invoke when the result is received. These options are mutually +exclusive. The callback will receive arguments in the form +\fI-option value\fR, suitable for \fBarray set\fR. +The options are: \fI-id\fR, the comm id of the interpreter that received +the command; \fI-serial\fR, a unique serial for each command sent to a +particular comm interpreter; \fI-chan\fR, the comm channel name; +\fI-code\fR, the result code of the command; \fI-errorcode\fR, the +errorcode, if any, of the command; \fI-errorinfo\fR, the errorinfo, if +any, of the command; and \fI-result\fR, 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 +\fB-command\fR is used, the command returns the unique serial for the +command. +.TP +\fB::comm::comm self\fR +Returns the \fIid\fR for this channel. +.TP +\fB::comm::comm interps\fR +Returns a list of all the remote \fIid\fR's to which this channel is +connected. \fBcomm\fR learns a new remote \fIid\fR when a command +is first issued it, or when a remote \fIid\fR first issues a command +to this comm channel. \fB::comm::comm ids\fR is an alias for this +method. +.TP +\fB::comm::comm connect\fR ?\fIid\fR? +Whereas \fB::comm::comm send\fR will automatically connect to the +given \fIid\fR, this forces a connection to a remote \fIid\fR without +sending a command. After this, the remote \fIid\fR will appear in +\fB::comm::comm interps\fR. +.PP +.SS "EVAL SEMANTICS" +.PP +The evaluation semantics of \fB::comm::comm send\fR are intended to +match Tk's \fBsend\fR \fIexactly\fR. This means that \fBcomm\fR +evaluates arguments on the remote side. +.PP +If you find that \fB::comm::comm send\fR 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 \fBsend\fR command also produces the +same error. +.PP +.CS + + + % ::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" + +.CE +.PP +The \fBeval\fR hook (described below) can be used to change from +\fBsend\fR's double eval semantics to single eval semantics. +.SS "MULTIPLE CHANNELS" +.PP +More than one \fBcomm\fR channel (or \fIlistener\fR) can be created +in each Tcl interpreter. This allows flexibility to create full and +restricted channels. For instance, \fIhook\fR scripts are specific +to the channel they are defined against. +.TP +\fB::comm::comm new\fR \fIchan\fR ?\fIname value ...\fR? +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 \fB::comm::comm\fR. Any remaining arguments are +passed to the \fBconfig\fR method. The fully qualified channel +name is returned. +.TP +\fB::comm::comm channels\fR +This lists all the channels allocated in this Tcl interpreter. +.PP +.PP +The default configuration parameters for a new channel are: +.PP +.CS + + + "-port 0 -local 1 -listen 0 -silent 0" + +.CE +.PP +The default channel \fB::comm::comm\fR is created with: +.PP +.CS + + + "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0" + +.CE +.SS "CHANNEL CONFIGURATION" +.PP +The \fBconfig\fR method acts similar to \fBfconfigure\fR in that it +sets or queries configuration variables associated with a channel. +.TP +\fB::comm::comm config\fR +.TP +\fB::comm::comm config\fR \fIname\fR +.TP +\fB::comm::comm config\fR ?\fIname\fR \fIvalue\fR \fI...\fR? +When given no arguments, \fBconfig\fR returns a list of all variables +and their value With one argument, \fBconfig\fR returns the value of +just that argument. With an even number of arguments, the given +variables are set to the given values. +.PP +.PP +These configuration variables can be changed (descriptions of them are +elsewhere in this manual page): +.TP +\fB-listen\fR ?\fI0|1\fR? +.TP +\fB-local\fR ?\fI0|1\fR? +.TP +\fB-port\fR ?\fIport\fR? +.TP +\fB-silent\fR ?\fI0|1\fR? +.TP +\fB-socketcmd\fR ?\fIcommandname\fR? +.TP +\fB-interp\fR ?\fIinterpreter\fR? +.TP +\fB-events\fR ?\fIeventlist\fR? +.PP +.PP +These configuration variables are read only: +.TP +\fB-chan\fR \fIchan\fR +.TP +\fB-serial\fR \fIn\fR +.TP +\fB-socket\fR sock\fIIn\fR +.PP +.PP +When \fBconfig\fR changes the parameters of an existing channel (with +the exception of \fB-interp\fR and \fB-events\fR), it closes and +reopens the listening socket. +An automatically assigned channel \fIid\fR will change when this +happens. +Recycling the socket is done by invoking \fB::comm::comm abort\fR, +which causes all active sends to terminate. +.SS "ID/PORT ASSIGNMENTS" +.PP +\fBcomm\fR uses a TCP port for endpoint \fIid\fR. The +\fBinterps\fR (or \fBids\fR) method merely lists all the TCP ports +to which the channel is connected. By default, each channel's +\fIid\fR 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 +\fB-port\fR 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 \fB-port {}\fR. Note that a channel won't be +created and initialized unless the specific port can be allocated. +.PP +As a special case, if the channel is configured with +\fB-listen 0\fR, then it will not create a listening socket and +will use an id of \fB0\fR 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 +\fB-silent 0\fR, then the listening side will ignore connection +attempts where the protocol negotiation phase failed, instead of +throwing an error. +.SS "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. +.PP +This insecure setup can be changed by the user via the two options +\fB-interp\fR, and \fB-events\fR. +.PP +When \fB-interp\fR 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 +\fIwithout\fR 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. +.PP +\fIAlso of note\fR is that replies and callbacks (a special form of +reply) are \fInot\fR considered as received scripts. They are +trusted, part of the internal machinery of comm, and therefore always +executed in the current interpreter. +.PP +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 \fB-events\fR 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. +.SS "REMOTE INTERPRETERS" +.PP +By default, each channel is restricted to accepting connections from +the local system. This can be overridden by using the +\fB-local 0\fR configuration option For such channels, the +\fIid\fR parameter takes the form \fI{ id host }\fR. +.PP +\fIWARNING\fR: The \fIhost\fR must always be specified in the same +form (e.g., as either a fully qualified domain name, plain hostname or +an IP address). +.SS "CLOSING CONNECTIONS" +.PP +These methods give control over closing connections: +.TP +\fB::comm::comm shutdown\fR \fIid\fR +This closes the connection to \fIid\fR, aborting all outstanding +commands in progress. Note that nothing prevents the connection from +being immediately reopened by another incoming or outgoing command. +.TP +\fB::comm::comm abort\fR +This invokes shutdown on all open connections in this comm channel. +.TP +\fB::comm::comm destroy\fR +This aborts all connections and then destroys the this comm channel +itself, including closing the listening socket. Special code allows +the default \fB::comm::comm\fR channel to be closed such that the +\fB::comm::comm\fR 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: +.sp +.CS + + + "::comm::comm destroy; ::comm::comm new ::comm::comm" + +.CE +.PP +.PP +When a remote connection is lost (because the remote exited or called +\fBshutdown\fR), \fBcomm\fR can invoke an application callback. +This can be used to cleanup or restart an ancillary process, for +instance. See the \fIlost\fR callback below. +.SS CALLBACKS +.PP +This is a mechanism for setting hooks for particular events: +.TP +\fB::comm::comm hook\fR \fIevent\fR ?\fB+\fR? ?\fIscript\fR? +This uses a syntax similar to Tk's \fBbind\fR command. Prefixing +\fIscript\fR with a \fB+\fR causes the new script to be appended. +Without this, a new \fIscript\fR 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. +.sp +When an \fIevent\fR occurs, the \fIscript\fR associated with it is +evaluated with the listed variables in scope and available. The +return code (\fInot\fR the return value) of the script is commonly +used decide how to further process after the hook. +.sp +Common variables include: +.RS +.TP +\fBchan\fR +the name of the comm channel (and command) +.TP +\fBid\fR +the id of the remote in question +.TP +\fBfid\fR +the file id for the socket of the connection +.RE +.PP +.PP +These are the defined \fIevents\fR: +.TP +\fBconnecting\fR +Variables: +\fBchan\fR, \fBid\fR +.sp +This hook is invoked before making a connection to the remote named in +\fIid\fR. An error return (via \fBerror\fR) will abort the connection +attempt with the error. Example: +.sp +.CS + + + % ::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 + % + +.CE +.TP +\fBconnected\fR +Variables: +\fBchan\fR, \fBfid\fR, \fBid\fR, \fBhost\fR, and \fBport\fR. +.sp +This hook is invoked immediately after making a remote connection to +\fIid\fR, allowing arbitrary authentication over the socket named by +\fIfid\fR. An error return (via \fBerror\fR ) will close the +connection with the error. \fIhost\fR and \fIport\fR are merely +extracted from the \fIid\fR; changing any of these will have no effect +on the connection, however. It is also possible to substitute and +replace \fIfid\fR. +.TP +\fBincoming\fR +Variables: +\fBchan\fR, \fBfid\fR, \fBaddr\fR, and \fBremport\fR. +.sp +Hook invoked when receiving an incoming connection, allowing arbitrary +authentication over socket named by \fIfid\fR. An error return (via +\fBerror\fR) will close the connection with the error. Note that the +peer is named by \fIremport\fR and \fIaddr\fR but that the remote +\fIid\fR is still unknown. Example: +.sp +.CS + + + ::comm::comm hook incoming { + if {[string match 127.0.0.1 $addr]} { + error "I don't talk to myself" + } + } + +.CE +.TP +\fBeval\fR +Variables: +\fBchan\fR, \fBid\fR, \fBcmd\fR, and \fBbuffer\fR. +.sp +This hook is invoked after collecting a complete script from a remote +but \fIbefore\fR evaluating it. This allows complete control over +the processing of incoming commands. \fIcmd\fR contains either +\fBsend\fR or \fBasync\fR. \fIbuffer\fR holds the script to +evaluate. At the time the hook is called, \fI$chan remoteid\fR is +identical in value to \fIid\fR. +.sp +By changing \fIbuffer\fR, 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 \fBreturn\fR \fIresult\fR (or, from +within a procedure, \fBreturn -code return\fR \fIresult\fR). An +error return (via \fBerror\fR) will return an error result, as is if +the script caused the error. Any other return will evaluate the +script in \fIbuffer\fR as normal. For compatibility with 3.2, +\fBbreak\fR and \fBreturn -code break\fR \fIresult\fR is supported, +acting similarly to \fBreturn {}\fR and \fBreturn -code return\fR +\fIresult\fR. +.sp +Examples: +.RS +.IP [1] +augmenting a command +.sp +.CS + + + % ::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 + +.CE +.IP [2] +short circuiting a command +.sp +.CS + + + % ::comm::comm hook eval {puts "would have executed $buffer"; return 0} + % ::comm::comm send [::comm::comm self] pid + would have executed pid + 0 + +.CE +.IP [3] +Replacing double eval semantics +.sp +.CS + + + % ::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 + +.CE +.IP [4] +Using a slave interpreter +.sp +.CS + + + % 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 + +.CE +.IP [5] +Using a slave interpreter (double eval) +.sp +.CS + + + % ::comm::comm hook eval {return [eval foo eval $buffer]} + +.CE +.IP [6] +Subverting the script to execute +.sp +.CS + + + % ::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 + +.CE +.RE +.TP +\fBreply\fR +Variables: +\fBchan\fR, \fBid\fR, \fBbuffer\fR, \fBret\fR, and \fBreturn()\fR. +.sp +This hook is invoked after collecting a complete reply script from a +remote but \fIbefore\fR evaluating it. This allows complete +control over the processing of replies to sent commands. The reply +\fIbuffer\fR is in one of the following forms +.RS +.IP \(bu +return result +.IP \(bu +return -code code result +.IP \(bu +return -code code -errorinfo info -errorcode ecode msg +.RE +.sp +For safety reasons, this is decomposed. The return result is in +\fIret\fR, and the return switches are in the return array: +.RS +.IP \(bu +\fIreturn(-code)\fR +.IP \(bu +\fIreturn(-errorinfo)\fR +.IP \(bu +\fIreturn(-errorcode)\fR +.RE +.sp +Any of these may be the empty string. Modifying these four variables +can change the return value, whereas modifying \fIbuffer\fR has no +effect. +.TP +\fBcallback\fR +Variables: +\fBchan\fR, \fBid\fR, \fBbuffer\fR, \fBret\fR, and \fBreturn()\fR. +.sp +Similar to \fIreply\fR, but used for callbacks. +.TP +\fBlost\fR +Variables: +\fBchan\fR, \fBid\fR, and \fBreason\fR. +.sp +This hook is invoked when the connection to \fBid\fR is lost. Return +value (or thrown error) is ignored. \fIreason\fR is an explanatory +string indicating why the connection was lost. Example: +.sp +.CS + + + ::comm::comm hook lost { + global myvar + if {$myvar(id) == $id} { + myfunc + return + } + } + +.CE +.PP +.SS UNSUPPORTED +.PP +These interfaces may change or go away in subsequence releases. +.TP +\fB::comm::comm remoteid\fR +Returns the \fIid\fR 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. +.TP +\fB::comm::comm_send\fR +Invoking this procedure will substitute the Tk \fBsend\fR and +\fBwinfo interps\fR commands with these equivalents that use +\fB::comm::comm\fR. +.sp +.CS + + + 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] + } + +.CE +.PP +.SS SECURITY +Starting with version 4.6 of the package an option \fB-socketcmd\fR +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 \fB::socket\fR (the default) can be used. +.PP +The envisioned main use is the specification of the \fBtls::socket\fR +command, see package \fBtls\fR, to secure the communication. +.PP +.CS + + + # 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 + ... + +.CE +.PP +The sections \fBExecution Environment\fR and \fBCallbacks\fR +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. +.SS "BLOCKING SEMANTICS" +.PP +There is one outstanding difference between \fBcomm\fR and +\fBsend\fR. When blocking in a synchronous remote command, \fBsend\fR +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, \fBcomm\fR uses the +\fBvwait\fR command as a semaphore to indicate the return message has +arrived. The difference is that a synchronous \fBsend\fR will block +the application and prevent all events (including window related ones) +from being processed, while a synchronous \fB::comm::comm send\fR +will block the application but still allow other events to get +processed. In particular, \fBafter idle\fR handlers will fire +immediately when comm blocks. +.PP +What can be done about this? First, note that this behavior will come +from any code using \fBvwait\fR to block and wait for an event to +occur. At the cost of multiple channel support, \fBcomm\fR 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 \fBcomm\fR) One way would be to +create a modified version of the \fBvwait\fR command that allow the +event flags passed to Tcl_DoOneEvent to be specified. For \fBcomm\fR, +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 \fBcomm\fR doesn't require Tk). One of these +approaches will be available in a future \fBcomm\fR release as an +optional component. +.SS "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. +.PP +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. +.PP +Before version 4.5 of comm the only solution was to rewrite the server +command to use the Tcl builtin command \fBvwait\fR, or one of its +relatives like \fBtkwait\fR, 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. +.PP +The proper solution is to have the invoked command indicate to +\fBcomm\fR 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. +.PP +The necessary support for this solution has been added to comm since +version 4.5, in the form of the new method \fBreturn_async\fR. +.TP +\fB::comm::comm return_async\fR +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. +.sp +The result of \fBreturn_async\fR is an object. This object, called a +\fIfuture\fR 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. +.sp +An example: +.CS + + +# 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 +} + +.CE +.sp +The API of a future object is: +.RS +.TP +\fB$future\fR \fBreturn\fR ?\fB-code\fR \fIcode\fR? ?\fIvalue\fR? +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). +.sp +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. +.TP +\fB$future\fR \fBconfigure\fR ?\fB-command\fR ?\fIcmdprefix\fR?? +.TP +\fB$future\fR \fBcget\fR \fB-command\fR +These methods allow the user to retrieve and set a command to be +called if the connection the future belongs to has been lost. +.RE +.PP +.SS COMPATIBILITY +.PP +\fBcomm\fR exports itself as a package. The package version number +is in the form \fImajor . minor\fR, 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 \fBcomm\fR this command is usually used: +.PP +.CS + + + package require comm 3 + +.CE +.PP +Note that requiring no version (or a specific version) can also be done. +.PP +The revision history of \fBcomm\fR includes these releases: +.TP +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. +.TP +4.6.1 +Changed the implementation of \fBcomm::commCollect\fR 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. +.TP +4.6 +Added the option \fB-socketcmd\fR enabling users to override how a +socket is opened. The envisioned main use is the specification of the +\fBtls::socket\fR command, see package \fBtls\fR, to secure the +communication. +.TP +4.5.7 +Changed handling of ports already in use to provide a proper error +message. +.TP +4.5.6 +Bugfix in the replacement for \fBvwait\fR, made robust against of +variable names containing spaces. +.TP +4.5.5 +Bugfix in the handling of hooks, typo in variable name. +.TP +4.5.4 +Bugfix in the handling of the result received by the \fBsend\fR +method. Replaced an \fIafter idle unset result\fR with an immediate +\fBunset\fR, with the information saved to a local variable. +.sp +The \fBafter idle\fR 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 \fBvwait\fR of \fBcomm\fR's +\fBsend\fR a few lines above the \fBafter idle\fR, and the child +used the same serial number for its next request. In that case the +parent's \fBafter idle unset\fR will delete the very array element +the child is waiting for, unlocking the \fBvwait\fR, causing it to +access a now missing array element, instead of the expected result. +.TP +4.5.3 +Bugfixes in the wrappers for the builtin \fBupdate\fR and \fBvwait\fR +commands. +.TP +4.5.2 +Bugfix in the wrapper for the builtin \fBupdate\fR command. +.TP +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 \fBcommSendReply\fR, +introduced by version 4.5. Affected debugging. +.TP +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 +\fIfuture\fR objects used by this feature from this version on comm +requires at least Tcl 8.3 to run. Please read the section +\fBAsynchronous Result Generation\fR for more details. +.TP +4.4.1 +Bugfix in the execution of hooks. +.TP +4.4 +Bugfixes in the handling of -interp for regular and hook +scripts. Bugfixes in channel cleanup. +.TP +4.3.1 +Introduced -interp and -events to enable easy use of a slave interp +for execution of received scripts, and of event scripts. +.TP +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. +.TP +4.2 +Bugfixes, and most important, switched to utf-8 as default encoding +for full i18n without any problems. +.TP +4.1 +Rewrite of internal code to remove old pseudo-object model. Addition +of send -command asynchronous callback option. +.TP +4.0 +Per request by John LoVerso. Improved handling of error for async +invoked commands. +.TP +3.7 +Moved into tcllib and placed in a proper namespace. +.TP +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. +.TP +3.5 +Internal change to how reply messages from a \fBsend\fR are handled. +Reply messages are now decoded into the \fIvalue\fR to pass to +\fBreturn\fR; 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 +\fBreply\fR message. +.TP +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 \fBpending\fR rather than the message about +the lost connection. \fBcomm ids\fR is now an alias for +\fBcomm interps\fR (previously, it an alias for \fBcomm chans\fR). +Since the method invocation change of 3.0, break and other exceptional +conditions were not being returned correctly from \fBcomm send\fR. +This has been fixed by removing the extra level of indirection into +the internal procedure \fBcommSend\fR. Also added propagation of +the \fIerrorCode\fR variable. This means that these commands return +exactly as they would with \fBsend\fR: +.sp +.CS + + + comm send id break + catch {comm send id break} + comm send id expr 1 / 0 + +.CE +.sp +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 \fBcomm config\fR (as this manual page +still listed the defunct \fBcomm init\fR!) +.TP +3.3 +Some minor bugs were corrected and the documentation was cleaned up. +Added some examples for hooks. The return semantics of the \fBeval\fR +hook were changed. +.TP +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. +.TP +3.1 +All the documented hooks were implemented. \fBcommLostHook\fR was +removed. A bug in \fBcomm new\fR was fixed. +.TP +3.0 +This is a new version of \fBcomm\fR with several major changes. +There is a new way of creating the methods available under the +\fBcomm\fR command. The \fBcomm init\fR method has been retired +and is replaced by \fBcomm configure\fR which allows access to many +of the well-defined internal variables. This also generalizes the +options available to \fBcomm new\fR. 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. +.TP +2.3 +\fBcomm ids\fR was renamed to \fBcomm channels\fR. General +support for \fBcomm hook\fR was fully implemented, but only the +\fIlost\fR hook exists, and it was changed to follow the general +hook API. \fBcommLostHook\fR was unsupported (replaced by +\fBcomm hook lost\fR) and \fBcommLost\fR was removed. +.TP +2.2 +The \fIdied\fR hook was renamed \fIlost\fR, to be accessed by +\fBcommLostHook\fR and an early implementation of +\fBcomm lost hook\fR. As such, \fBcommDied\fR is now +\fBcommLost\fR. +.TP +2.1 +Unsupported method \fBcomm remoteid\fR was added. +.TP +2.0 +\fBcomm\fR has been rewritten from scratch (but is fully compatible +with Comm 1.0, without the requirement to use obTcl). +.PP +.SH AUTHOR +John LoVerso, John@LoVerso.Southborough.MA.US +.PP +\fIhttp://www.opengroup.org/~loverso/tcl-tk/#comm\fR +.SH LICENSE +Please see the file \fIcomm.LICENSE\fR that accompanied this source, +or +\fIhttp://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html\fR. +.PP +This license for \fBcomm\fR, new as of version 3.2, allows it to be +used for free, without any licensing fee or royalty. +.SH BUGS +.IP \(bu +If there is a failure initializing a channel created with +\fB::comm::comm new\fR, then the channel should be destroyed. +Currently, it is left in an inconsistent state. +.IP \(bu +There should be a way to force a channel to quiesce when changing the +configuration. +.PP +.PP +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. +.IP \(bu +Allow easier use of a slave interp for actual command execution +(especially when operating in "not local" mode). +.IP \(bu +Add host list (xhost-like) or "magic cookie" (xauth-like) +authentication to initial handshake. +.PP +.PP +The following are outstanding todo items. +.IP \(bu +Add an interp discovery and name->port mapping. This is likely to be +in a separate, optional nameserver. (See also the related work, +below.) +.IP \(bu +Fix the \fI{id host}\fR form so as not to be dependent upon +canonical hostnames. This requires fixes to Tcl to resolve hostnames! +.PP +.PP +This man page is bigger than the source file. +.SH "ON USING OLD VERSIONS OF TCL" +.PP +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: +.PP +.CS + + + "comm send $other exit" + +.CE +.PP +Always make sure the channel is quiescent before closing/exiting or +use at least Tcl7.6 under Windows. +.PP +Tcl7.6 on the Mac contains several bugs. It is recommended you use +at least Tcl7.6p2. +.PP +Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended +you use Tcl8.0p1 (or Tcl7.6p2). +.SH "RELATED WORK" +.PP +Tcl-DP provides an RPC-based remote execution interface, but is a +compiled Tcl extension. See +\fIhttp://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html\fR. +.PP +Michael Doyle has code that implements the Tcl-DP +RPC interface using standard Tcl sockets, much like \fBcomm\fR. +.PP +Andreas Kupries uses +\fBcomm\fR and has built a simple nameserver as part of his Pool +library. See \fIhttp://www.purl.org/net/akupries/soft/pool/index.htm\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcomm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +send(n) +.SH KEYWORDS +comm, communication, ipc, message, remote communication, remote execution, rpc, secure, send, socket, ssl, tls +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 1995-1998 The Open Group. All Rights Reserved. +Copyright (c) 2003-2004 ActiveState Corporation. +Copyright (c) 2006-2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/comm/comm_wire.n Index: embedded/man/files/modules/comm/comm_wire.n ================================================================== --- /dev/null +++ embedded/man/files/modules/comm/comm_wire.n @@ -0,0 +1,409 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/comm/comm_wire.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Docs. Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "comm_wire" n 3 tcllib "Remote communication" +.BS +.SH NAME +comm_wire \- The comm wire protocol +.SH SYNOPSIS +package require \fBcomm \fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBcomm\fR command provides an inter-interpreter remote +execution facility much like Tk's \fBsend(n)\fR, except that it uses +sockets rather than the X server for the communication path. As a +result, \fBcomm\fR works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path. +.PP +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 \fBcomm\fR, 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. +.SH "WIRE PROTOCOL VERSION 3" +.SS "BASIC LAYER" +The basic encoding for \fIall\fR 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. +.SS "BASIC MESSAGE LAYER" +On top of the \fBBasic Layer\fR we have a +\fImessage oriented\fR exchange of data. +The totality of all characters written to the channel is a Tcl list, +with each element a separate \fImessage\fR, 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. +.PP +EOL is signaled through the linefeed character, i.e \fBLF\fR, or, +hex \fB0x0a\fR. This is following the unix convention for +line-endings. +.PP +As a list each message is composed of \fIwords\fR. Their meaning +depends on when the message was sent in the overall exchange. This is +described in the upcoming sections. +.SS "NEGOTIATION MESSAGES - INITIAL HANDSHAKE" +The command protocol is defined like this: +.IP \(bu +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 \fB0\fR 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. +.IP \(bu +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 \fBvers\fR as its first element, and the version of the +wire protocol the server has selected from the offered versions as the +second. +.PP +.SS "SCRIPT/COMMAND MESSAGES" +All messages coming after the \fBinitial handshake\fR +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. +.TP +\fBsend\fR +.TP +\fBasync\fR +.TP +\fBcommand\fR +The payload is the Tcl script to execute on the server. It is actually +a list containing the script fragments. These fragment are +\fBconcat\fRenated 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. +.sp +Examples: +.sp +.CS + + + (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 + +.CE +.sp +Note that (a), generated by (a'), is the usual form, if only single +commands are sent by the client. +For example constructed using \fBlist\fR, if the command contains +variable arguments. Like +.sp +.CS + + + send [list array get $the_variable] + +.CE +.sp +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. +.RS +.TP +\fBsend\fR +A reply is expected. The sender is waiting for the result. +.TP +\fBasync\fR +No reply is expected, the sender has no interest in the result and is +not waiting for any. +.TP +\fBcommand\fR +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. +.RE +.TP +\fBreply\fR +Like the previous three command, however the tcl script in the payload +is highly restricted. +It has to be a syntactically valid Tcl \fBreturn\fR command. This +contains result code, value, error code, and error info. +.sp +Examples: +.sp +.CS + + + {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}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcomm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +comm +.SH KEYWORDS +comm, communication, ipc, message, remote communication, remote execution, rpc, socket +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2005 Docs. Andreas Kupries + +.fi ADDED embedded/man/files/modules/control/control.n Index: embedded/man/files/modules/control/control.n ================================================================== --- /dev/null +++ embedded/man/files/modules/control/control.n @@ -0,0 +1,386 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/control/control.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "control" n 0.1.3 tcllib "Tcl Control Flow Commands" +.BS +.SH NAME +control \- Procedures for control flow structures. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcontrol ?0.1.3?\fR +.sp +\fBcontrol::control\fR \fIcommand\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fBcontrol::assert\fR \fIexpr\fR ?\fIarg arg ...\fR? +.sp +\fBcontrol::do\fR \fIbody\fR ?\fIoption test\fR? +.sp +\fBcontrol::no-op\fR ?\fIarg arg ...\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBcontrol\fR 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 \fIkeywords\fR, or a part of the +language itself. In Tcl, control flow structures are just commands +like everything else. +.SH COMMANDS +.TP +\fBcontrol::control\fR \fIcommand\fR \fIoption\fR ?\fIarg arg ...\fR? +The \fBcontrol\fR command is used as a configuration command for +customizing the other public commands of the control package. The +\fIcommand\fR argument names the command to be customized. The set of +valid \fIoption\fR and subsequent arguments are determined by the +command being customized, and are documented with the command. +.TP +\fBcontrol::assert\fR \fIexpr\fR ?\fIarg arg ...\fR? +When disabled, the \fBassert\fR command behaves exactly like the +\fBno-op\fR command. +.sp +When enabled, the \fBassert\fR command evaluates \fIexpr\fR as an +expression (in the same way that \fBexpr\fR evaluates its argument). +If evaluation reveals that \fIexpr\fR is not a valid boolean +expression (according to [\fBstring is boolean -strict\fR]), +an error is raised. If \fIexpr\fR evaluates to a true boolean value +(as recognized by \fBif\fR), then \fBassert\fR returns an empty +string. Otherwise, the remaining arguments to \fBassert\fR 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 \fBjoin\fR 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. +.sp +The \fBassert\fR command can be customized by the \fBcontrol\fR +command in two ways: +.sp +[\fBcontrol::control assert enabled\fR ?\fIboolean\fR?] +queries or sets whether \fBcontrol::assert\fR is enabled. When called +without a \fIboolean\fR argument, a boolean value is returned +indicating whether the \fBcontrol::assert\fR command is enabled. When +called with a valid boolean value as the \fIboolean\fR argument, the +\fBcontrol::assert\fR command is enabled or disabled to match the +argument, and an empty string is returned. +.sp +[\fBcontrol::control assert callback\fR ?\fIcommand\fR?] +queries or sets the callback command that will be called by an enabled +\fBassert\fR on assertion failure. When called without a +\fIcommand\fR argument, the current callback command is returned. +When called with a \fIcommand\fR argument, that argument becomes the +new assertion failure callback command. Note that an assertion +failure callback command is always defined, even when \fBassert\fR +is disabled. The default callback command is +[\fBreturn -code error\fR]. +.sp +Note that \fBcontrol::assert\fR has been written so that in +combination with [\fBnamespace import\fR], it is possible to +use enabled \fBassert\fR commands in some namespaces and disabled +\fBassert\fR commands in other namespaces at the same time. This +capability is useful so that debugging efforts can be independently +controlled module by module. +.sp +.CS + + +% 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} + +.CE +.TP +\fBcontrol::do\fR \fIbody\fR ?\fIoption test\fR? +The \fBdo\fR command evaluates the script \fIbody\fR repeatedly +\fIuntil\fR the expression \fItest\fR becomes true or as long as +(\fIwhile\fR) \fItest\fR is true, depending on the value of +\fIoption\fR being \fBuntil\fR or \fBwhile\fR. If +\fIoption\fR and \fItest\fR are omitted the body is evaluated exactly +once. After normal completion, \fBdo\fR returns an empty string. +Exceptional return codes (\fBbreak\fR, \fBcontinue\fR, \fBerror\fR, +etc.) during the evaluation of \fIbody\fR are handled in the same way +the \fBwhile\fR command handles them, except as noted in +\fBLIMITATIONS\fR, below. +.TP +\fBcontrol::no-op\fR ?\fIarg arg ...\fR? +The \fBno-op\fR command takes any number of arguments and does +nothing. It returns an empty string. +.PP +.SH LIMITATIONS +Several of the commands provided by the \fBcontrol\fR package accept +arguments that are scripts to be evaluated. Due to fundamental +limitations of Tcl's \fBcatch\fR and \fBreturn\fR commands, it is not +possible for these commands to properly evaluate the command +[\fBreturn -code $code\fR] within one of those script +arguments for any value of \fI$code\fR other than \fIok\fR. In this +way, the commands of the \fBcontrol\fR package are limited as compared +to Tcl's built-in control flow commands (such as \fBif\fR, +\fBwhile\fR, etc.) and those control flow commands that can be +provided by packages coded in C. An example of this difference: +.PP +.CS + + +% 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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcontrol\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +break, continue, expr, if, join, namespace, return, string, while +.SH KEYWORDS +assert, control, do, flow, no-op, structure +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/coroutine/coro_auto.n Index: embedded/man/files/modules/coroutine/coro_auto.n ================================================================== --- /dev/null +++ embedded/man/files/modules/coroutine/coro_auto.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/coroutine/coro_auto.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010-2011 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "coroutine::auto" n 1 tcllib "Coroutine utilities" +.BS +.SH NAME +coroutine::auto \- Automatic event and IO coroutine awareness +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBcoroutine::auto 1.1\fR +.sp +package require \fBcoroutine 1.1\fR +.sp +.BE +.SH DESCRIPTION +The \fBcoroutine::auto\fR package provides no commands or other +directly visible functionality. +Built on top of the package \fBcoroutine\fR, 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. +.PP +The commands so affected by this package are +.TP +\fBafter\fR +.TP +\fBexit\fR +.TP +\fBgets\fR +.TP +\fBglobal\fR +.TP +\fBread\fR +.TP +\fBupdate\fR +.TP +\fBvwait\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcoroutine\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait +.SH CATEGORY +Coroutine +.SH COPYRIGHT +.nf +Copyright (c) 2010-2011 Andreas Kupries + +.fi ADDED embedded/man/files/modules/coroutine/coroutine.n Index: embedded/man/files/modules/coroutine/coroutine.n ================================================================== --- /dev/null +++ embedded/man/files/modules/coroutine/coroutine.n @@ -0,0 +1,350 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/coroutine/coroutine.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010-2011 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "coroutine" n 1 tcllib "Coroutine utilities" +.BS +.SH NAME +coroutine \- Coroutine based event and IO handling +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBcoroutine 1.1\fR +.sp +\fBcoroutine::util after\fR \fIdelay\fR +.sp +\fBcoroutine::util await\fR \fIvarname\fR... +.sp +\fBcoroutine::util create\fR \fIarg\fR... +.sp +\fBcoroutine::util exit\fR ?\fIstatus\fR? +.sp +\fBcoroutine::util gets\fR \fIchan\fR ?\fIvarname\fR? +.sp +\fBcoroutine::util global\fR \fIvarname\fR... +.sp +\fBcoroutine::util read\fR \fB-nonewline\fR \fIchan\fR ?\fIn\fR? +.sp +\fBcoroutine::util update\fR ?\fBidletasks\fR? +.sp +\fBcoroutine::util vwait\fR \fIvarname\fR +.sp +.BE +.SH DESCRIPTION +The \fBcoroutine\fR package provides coroutine-aware +implementations of various event- and channel related commands. It can +be in multiple modes: +.IP [1] +Call the commands through their ensemble, in code which is +explicitly written for use within coroutines. +.IP [2] +Import the commands into a namespace, either directly, or +through \fBnamespace path\fR. This allows the use from within code +which is not coroutine-aware per se and restricted to specific +namespaces. +.PP +A more agressive form of making code coroutine-oblivious than point 2 +above is available through the package \fBcoroutine::auto\fR, +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. +.SH 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. +.TP +\fBcoroutine::util after\fR \fIdelay\fR +This command delays the coroutine invoking it by \fIdelay\fR +milliseconds. +.TP +\fBcoroutine::util await\fR \fIvarname\fR... +This command is an extension form of the \fBcoroutine::util vwait\fR +command (see below) which waits on a write to one of many named +namespace variables. +.TP +\fBcoroutine::util create\fR \fIarg\fR... +This command creates a new coroutine with an automatically assigned +name and causes it to run the code specified by the arguments. +.TP +\fBcoroutine::util exit\fR ?\fIstatus\fR? +This command exits the current coroutine, causing it to return +\fIstatus\fR. If no status was specified the default \fI0\fR is +returned. +.TP +\fBcoroutine::util gets\fR \fIchan\fR ?\fIvarname\fR? +This command reads a line from the channel \fIchan\fR and returns it +either as its result, or, if a \fIvarname\fR was specified, writes it +to the named variable and returns the number of characters read. +.TP +\fBcoroutine::util global\fR \fIvarname\fR... +This command imports the named global variables of the coroutine into +the current scope. From the technical point of view these variables +reside in level \fB#1\fR of the Tcl stack. I.e. these are not the +regular global variable in to the global namespace, and each coroutine +can have their own set, independent of all others. +.TP +\fBcoroutine::util read\fR \fB-nonewline\fR \fIchan\fR ?\fIn\fR? +This command reads \fIn\fR characters from the channel \fIchan\fR and +returns them as its result. If \fIn\fR is not specified the command +will read the channel until EOF is reached. +.TP +\fBcoroutine::util update\fR ?\fBidletasks\fR? +This command causes the coroutine invoking it to run pending events or +idle handlers before proceeding. +.TP +\fBcoroutine::util vwait\fR \fIvarname\fR +This command causes the coroutine calling it to wait for a write to +the named namespace variable \fIvarname\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcoroutine\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait +.SH CATEGORY +Coroutine +.SH COPYRIGHT +.nf +Copyright (c) 2010-2011 Andreas Kupries + +.fi ADDED embedded/man/files/modules/counter/counter.n Index: embedded/man/files/modules/counter/counter.n ================================================================== --- /dev/null +++ embedded/man/files/modules/counter/counter.n @@ -0,0 +1,460 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/counter/counter.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "counter" n 2.0.4 tcllib "Counters and Histograms" +.BS +.SH NAME +counter \- Procedures for counters and histograms +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBcounter ?2.0.4?\fR +.sp +\fB::counter::init\fR \fItag args\fR +.sp +\fB::counter::count\fR \fItag\fR ?\fIdelta\fR? ?\fIinstance\fR? +.sp +\fB::counter::start\fR \fItag instance\fR +.sp +\fB::counter::stop\fR \fItag instance\fR +.sp +\fB::counter::get\fR \fItag args\fR +.sp +\fB::counter::exists\fR \fItag\fR +.sp +\fB::counter::names\fR +.sp +\fB::counter::histHtmlDisplay\fR \fItag args\fR +.sp +\fB::counter::reset\fR \fItag args\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBcounter\fR package provides a counter facility and can +compute statistics and histograms over the collected data. +.TP +\fB::counter::init\fR \fItag args\fR +This defines a counter with the name \fItag\fR. The \fIargs\fR +determines the characteristics of the counter. The \fIargs\fR are +.RS +.TP +\fB-group\fR \fIname\fR +Keep a grouped counter where the name of the histogram bucket is +passed into \fB::counter::count\fR. +.TP +\fB-hist\fR \fIbucketsize\fR +Accumulate the counter into histogram buckets of size +\fIbucketsize\fR. For example, if the samples are millisecond time +values and \fIbucketsize\fR 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. +.TP +\fB-hist2x\fR \fIbucketsize\fR +Accumulate the statistic into histogram buckets. The size of the +first bucket is \fIbucketsize\fR, each other bucket holds values 2 +times the size of the previous bucket. For example, if +\fIbucketsize\fR 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. +.TP +\fB-hist10x\fR \fIbucketsize\fR +Accumulate the statistic into histogram buckets. The size of the +first bucket is \fIbucketsize\fR, each other bucket holds values 10 +times the size of the previous bucket. For example, if +\fIbucketsize\fR 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. +.TP +\fB-lastn\fR \fIN\fR +Save the last \fIN\fR values of the counter to maintain a "running +average" over the last \fIN\fR values. +.TP +\fB-timehist\fR \fIsecsPerMinute\fR +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 \fIsecsPerMinute\fR, 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 +\fIsecsPerMinute\fR value seen by the package is used for all +subsequent time-based histograms. +.RE +.TP +\fB::counter::count\fR \fItag\fR ?\fIdelta\fR? ?\fIinstance\fR? +Increment the counter identified by \fItag\fR. The default increment +is 1, although you can increment by any value, integer or real, by +specifying \fIdelta\fR. You must declare each counter with +\fB::counter::init\fR to define the characteristics of counter before +you start to use it. If the counter type is \fB-group\fR, then the +counter identified by \fIinstance\fR is incremented. +.TP +\fB::counter::start\fR \fItag instance\fR +Record the starting time of an interval. The \fItag\fR is the name of +the counter defined as a \fB-hist\fR value-based histogram. The +\fIinstance\fR is used to distinguish this interval from any other +intervals that might be overlapping this one. +.TP +\fB::counter::stop\fR \fItag instance\fR +Record the ending time of an interval. The delta time since the +corresponding \fB::counter::start\fR call for \fIinstance\fR is +recorded in the histogram identified by \fItag\fR. +.TP +\fB::counter::get\fR \fItag args\fR +Return statistics about a counter identified by \fItag\fR. The +\fIargs\fR determine what value to return: +.RS +.TP +\fB-total\fR +Return the total value of the counter. This is the default if +\fIargs\fR is not specified. +.TP +\fB-totalVar\fR +Return the name of the total variable. Useful for specifying with +-textvariable in a Tk widget. +.TP +\fB-N\fR +Return the number of samples accumulated into the counter. +.TP +\fB-avg\fR +Return the average of samples accumulated into the counter. +.TP +\fB-avgn\fR +Return the average over the last \fIN\fR samples taken. The \fIN\fR +value is set in the \fB::counter::init\fR call. +.TP +\fB-hist\fR \fIbucket\fR +If \fIbucket\fR 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. +.TP +\fB-histVar\fR +Return the name of the histogram array variable. +.TP +\fB-histHour\fR +Return the complete hourly histogram in array get format sorted by +bucket. +.TP +\fB-histHourVar\fR +Return the name of the hourly histogram array variable. +.TP +\fB-histDay\fR +Return the complete daily histogram in array get format sorted by +bucket. +.TP +\fB-histDayVar\fR +Return the name of the daily histogram array variable. +.TP +\fB-resetDate\fR +Return the clock seconds value recorded when the +counter was last reset. +.TP +\fB-all\fR +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. +.RE +.TP +\fB::counter::exists\fR \fItag\fR +Returns 1 if the counter is defined. +.TP +\fB::counter::names\fR +Returns a list of all counters defined. +.TP +\fB::counter::histHtmlDisplay\fR \fItag args\fR +Generate HTML to display a histogram for a counter. The \fIargs\fR +control the format of the display. They are: +.RS +.TP +\fB-title\fR \fIstring\fR +Label to display above bar chart +.TP +\fB-unit\fR \fIunit\fR +Specify \fBminutes\fR, \fBhours\fR, or \fBdays\fR for the +time-base histograms. For value-based histograms, the \fIunit\fR is +used in the title. +.TP +\fB-images\fR \fIurl\fR +URL of /images directory. +.TP +\fB-gif\fR \fIfilename\fR +Image for normal histogram bars. The \fIfilename\fR is relative to +the \fB-images\fR directory. +.TP +\fB-ongif\fR \fIfilename\fR +Image for the active histogram bar. The \fIfilename\fR is relative to +the \fB-images\fR directory. +.TP +\fB-max\fR \fIN\fR +Maximum number of value-based buckets to display. +.TP +\fB-height\fR \fIN\fR +Pixel height of the highest bar. +.TP +\fB-width\fR \fIN\fR +Pixel width of each bar. +.TP +\fB-skip\fR \fIN\fR +Buckets to skip when labeling value-based histograms. +.TP +\fB-format\fR \fIstring\fR +Format used to display labels of buckets. +.TP +\fB-text\fR \fIboolean\fR +If 1, a text version of the histogram is dumped, otherwise a graphical +one is generated. +.RE +.TP +\fB::counter::reset\fR \fItag args\fR +Resets the counter with the name \fItag\fR to an initial state. The +\fIargs\fR determine the new characteristics of the counter. They have +the same meaning as described for \fB::counter::init\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcounter\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +counting, histogram, statistics, tallying +.SH CATEGORY +Data structures ADDED embedded/man/files/modules/crc/cksum.n Index: embedded/man/files/modules/crc/cksum.n ================================================================== --- /dev/null +++ embedded/man/files/modules/crc/cksum.n @@ -0,0 +1,367 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/crc/cksum.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "cksum" n 1.1.3 tcllib "Cyclic Redundancy Checks" +.BS +.SH NAME +cksum \- Calculate a cksum(1) compatible checksum +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcksum ?1.1.3?\fR +.sp +\fB::crc::cksum\fR ?\fI-format format\fR? ?\fI-chunksize size\fR? [ \fI-channel chan\fR | \fI-filename file\fR | \fIstring\fR ] +.sp +\fB::crc::CksumInit\fR +.sp +\fB::crc::CksumUpdate\fR \fItoken\fR \fIdata\fR +.sp +\fB::crc::CksumFinal\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::crc::cksum\fR ?\fI-format format\fR? ?\fI-chunksize size\fR? [ \fI-channel chan\fR | \fI-filename file\fR | \fIstring\fR ] +The command takes string data or a channel or file name and returns a +checksum value calculated using the \fBcksum(1)\fR algorithm. The +result is formatted using the \fIformat\fR(n) specifier provided or as +an unsigned integer (%u) by default. +.PP +.SH OPTIONS +.TP +-channel \fIname\fR +Return a checksum for the data read from a channel. The command will +read data from the channel until the \fBeof\fR is true. If you need +to be able to process events during this calculation see the +\fBPROGRAMMING INTERFACE\fR section +.TP +-filename \fIname\fR +This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the \fI-channel\fR option had +been used. The file is closed on completion. +.TP +-format \fIstring\fR +Return the checksum using an alternative format template. +.PP +.SH "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 \fBfileevent\fR handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption. +.TP +\fB::crc::CksumInit\fR +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. +.TP +\fB::crc::CksumUpdate\fR \fItoken\fR \fIdata\fR +Add data to the checksum identified by token. Calling +\fICksumUpdate $token "abcd"\fR is equivalent to calling +\fICksumUpdate $token "ab"\fR followed by +\fICksumUpdate $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::crc::CksumFinal\fR \fItoken\fR +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. +.PP +.SH EXAMPLES +.PP +.CS + + +% crc::cksum "Hello, World!" +2609532967 + +.CE +.PP +.CS + + +% crc::cksum -format 0x%X "Hello, World!" +0x9B8A5027 + +.CE +.PP +.CS + + +% crc::cksum -file cksum.tcl +1828321145 + +.CE +.PP +.CS + + +% set tok [crc::CksumInit] +% crc::CksumUpdate $tok "Hello, " +% crc::CksumUpdate $tok "World!" +% crc::CksumFinal $tok +2609532967 + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcrc\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +crc32(n), sum(n) +.SH KEYWORDS +checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/crc/crc16.n Index: embedded/man/files/modules/crc/crc16.n ================================================================== --- /dev/null +++ embedded/man/files/modules/crc/crc16.n @@ -0,0 +1,385 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/crc/crc16.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "crc16" n 1.1.2 tcllib "Cyclic Redundancy Checks" +.BS +.SH NAME +crc16 \- Perform a 16bit Cyclic Redundancy Check +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcrc16 ?1.1.2?\fR +.sp +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.sp +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +.sp +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.sp +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +.sp +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.sp +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.TP +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +.TP +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.TP +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +.TP +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR +.TP +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR +The command takes either string data or a file name and returns a checksum +value calculated using the CRC algorithm. The command used sets up the +CRC polynomial, initial value and bit ordering for the desired +standard checksum calculation. The result is formatted +using the \fIformat\fR(n) specifier provided or as an unsigned integer +(%u) by default. +.sp +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. +.sp +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 \fBcrc32\fR package is available. +.PP +.SH OPTIONS +.TP +-filename \fIname\fR +Return a checksum for the file contents instead of for parameter data. +.TP +-format \fIstring\fR +Return the checksum using an alternative format template. +.TP +-seed \fIvalue\fR +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) +.TP +-implementation \fIprocname\fR +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. +.sp +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. +.TP +-- +Terminate option processing. +.PP +.SH EXAMPLES +.PP +.CS + + +% crc::crc16 "Hello, World!" +64077 + +.CE +.PP +.CS + + +% crc::crc-ccitt "Hello, World!" +26586 + +.CE +.PP +.CS + + +% crc::crc16 -format 0x%X "Hello, World!" +0xFA4D + +.CE +.PP +.CS + + +% crc::crc16 -file crc16.tcl +51675 + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcrc\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +cksum(n), crc32(n), sum(n) +.SH KEYWORDS +checksum, cksum, crc, crc16, crc32, cyclic redundancy check, data integrity, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/crc/crc32.n Index: embedded/man/files/modules/crc/crc32.n ================================================================== --- /dev/null +++ embedded/man/files/modules/crc/crc32.n @@ -0,0 +1,383 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/crc/crc32.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "crc32" n 1.3 tcllib "Cyclic Redundancy Checks" +.BS +.SH NAME +crc32 \- Perform a 32bit Cyclic Redundancy Check +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcrc32 ?1.3?\fR +.sp +\fB::crc::crc32\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? [ \fI-channel chan\fR | \fI-filename file\fR | \fImessage\fR ] +.sp +\fB::crc::Crc32Init\fR ?\fIseed\fR? +.sp +\fB::crc::Crc32Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::crc::Crc32Final\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBcritcl\fR package or the \fBTrf\fR package +are available then a compiled version may be used internally to +accelerate the checksum calculation. +.SH COMMANDS +.TP +\fB::crc::crc32\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? [ \fI-channel chan\fR | \fI-filename file\fR | \fImessage\fR ] +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 \fIformat\fR(n) specifier provided. The +default is to return the value as an unsigned integer (format %u). +.PP +.SH OPTIONS +.TP +-channel \fIname\fR +Return a checksum for the data read from a channel. The command will +read data from the channel until the \fBeof\fR is true. If you need +to be able to process events during this calculation see the +\fBPROGRAMMING INTERFACE\fR section +.TP +-filename \fIname\fR +This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the \fI-channel\fR option had +been used. The file is closed on completion. +.TP +-format \fIstring\fR +Return the checksum using an alternative format template. +.TP +-seed \fIvalue\fR +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 +\fBPROGRAMMING INTERFACE\fR which is intended for this mode of +operation. +.PP +.SH "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 \fBfileevent\fR handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption. +.TP +\fB::crc::Crc32Init\fR ?\fIseed\fR? +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. +.TP +\fB::crc::Crc32Update\fR \fItoken\fR \fIdata\fR +Add data to the checksum identified by token. Calling +\fICrc32Update $token "abcd"\fR is equivalent to calling +\fICrc32Update $token "ab"\fR followed by +\fICrc32Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::crc::Crc32Final\fR \fItoken\fR +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. +.PP +.SH EXAMPLES +.PP +.CS + + +% crc::crc32 "Hello, World!" +3964322768 + +.CE +.PP +.CS + + +% crc::crc32 -format 0x%X "Hello, World!" +0xEC4AC3D0 + +.CE +.PP +.CS + + +% crc::crc32 -file crc32.tcl +483919716 + +.CE +.PP +.CS + + +% set tok [crc::Crc32Init] +% crc::Crc32Update $tok "Hello, " +% crc::Crc32Update $tok "World!" +% crc::Crc32Final $tok +3964322768 + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcrc\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +cksum(n), crc16(n), sum(n) +.SH KEYWORDS +checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/crc/sum.n Index: embedded/man/files/modules/crc/sum.n ================================================================== --- /dev/null +++ embedded/man/files/modules/crc/sum.n @@ -0,0 +1,338 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/crc/sum.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "sum" n 1.1.0 tcllib "Cyclic Redundancy Checks" +.BS +.SH NAME +sum \- Calculate a sum(1) compatible checksum +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBsum ?1.1.0?\fR +.sp +\fB::crc::sum\fR ?\fI-bsd\fR | \fI-sysv\fR? ?\fI-format fmt\fR? ?\fI-chunksize size\fR? [ \fI-filename file\fR | \fI-channel chan\fR | \fIstring\fR ] +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::crc::sum\fR ?\fI-bsd\fR | \fI-sysv\fR? ?\fI-format fmt\fR? ?\fI-chunksize size\fR? [ \fI-filename file\fR | \fI-channel chan\fR | \fIstring\fR ] +The command takes string data or a file name or a channel and returns +a checksum value calculated using the \fBsum(1)\fR algorithm. The +result is formatted using the \fIformat\fR(n) specifier provided or as +an unsigned integer (%u) by default. +.PP +.SH OPTIONS +.TP +-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. +.TP +-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. +.TP +-filename \fIname\fR +Return a checksum for the file contents instead of for parameter data. +.TP +-channel \fIchan\fR +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. +.TP +-chunksize \fIsize\fR +Set the block size used when reading data from either files or +channels. This value defaults to 4096. +.TP +-format \fIstring\fR +Return the checksum using an alternative format template. +.PP +.SH EXAMPLES +.PP +.CS + + +% crc::sum "Hello, World!" +37287 + +.CE +.PP +.CS + + +% crc::sum -format 0x%X "Hello, World!" +0x91A7 + +.CE +.PP +.CS + + +% crc::sum -file sum.tcl +13392 + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcrc\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +cksum(n), crc32(n), sum(1) +.SH KEYWORDS +checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security, sum +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/csv/csv.n Index: embedded/man/files/modules/csv/csv.n ================================================================== --- /dev/null +++ embedded/man/files/modules/csv/csv.n @@ -0,0 +1,475 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/csv/csv.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002-2013 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "csv" n 0.8 tcllib "CSV processing" +.BS +.SH NAME +csv \- Procedures to handle CSV data. +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBcsv ?0.8?\fR +.sp +\fB::csv::iscomplete\fR \fIdata\fR +.sp +\fB::csv::join\fR \fIvalues\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +.sp +\fB::csv::joinlist\fR \fIvalues\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +.sp +\fB::csv::joinmatrix\fR \fImatrix\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +.sp +\fB::csv::read2matrix\fR ?\fB-alternate\fR? \fIchan m\fR {\fIsepChar\fR ,} {\fIexpand\fR none} +.sp +\fB::csv::read2queue\fR ?\fB-alternate\fR? \fIchan q\fR {\fIsepChar\fR ,} +.sp +\fB::csv::report\fR \fIcmd matrix\fR ?\fIchan\fR? +.sp +\fB::csv::split\fR ?\fB-alternate\fR? \fIline\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +.sp +\fB::csv::split2matrix\fR ?\fB-alternate\fR? \fIm line\fR {\fIsepChar\fR ,} {\fIexpand\fR none} +.sp +\fB::csv::split2queue\fR ?\fB-alternate\fR? \fIq line\fR {\fIsepChar\fR ,} +.sp +\fB::csv::writematrix\fR \fIm chan\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +.sp +\fB::csv::writequeue\fR \fIq chan\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBcsv\fR package provides commands to manipulate information +in CSV \fBFORMAT\fR (CSV = Comma Separated Values). +.SH COMMANDS +.PP +The following commands are available: +.TP +\fB::csv::iscomplete\fR \fIdata\fR +A predicate checking if the argument \fIdata\fR 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. +.TP +\fB::csv::join\fR \fIvalues\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +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 \fIdelMode\fR is "auto", surrounding +values with \fIdelChar\fR only when needed. When set to "always" +however, values are always surrounded by the \fIdelChar\fR instead. +.TP +\fB::csv::joinlist\fR \fIvalues\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +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 \fIdelMode\fR is "auto", surrounding +values with \fIdelChar\fR only when needed. When set to "always" +however, values are always surrounded by the \fIdelChar\fR 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 \fB::csv::join\fR). +.TP +\fB::csv::joinmatrix\fR \fImatrix\fR ?\fIsepChar\fR? ?\fIdelChar\fR? ?\fIdelMode\fR? +Takes a \fImatrix\fR 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 \fIdelMode\fR is "auto", surrounding +values with \fIdelChar\fR only when needed. When set to "always" +however, values are always surrounded by the \fIdelChar\fR 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 \fB::csv::join\fR). +.TP +\fB::csv::read2matrix\fR ?\fB-alternate\fR? \fIchan m\fR {\fIsepChar\fR ,} {\fIexpand\fR none} +A wrapper around \fB::csv::split2matrix\fR (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given matrix. For an explanation of the \fIexpand\fR +argument see \fB::csv::split2matrix\fR. +.TP +\fB::csv::read2queue\fR ?\fB-alternate\fR? \fIchan q\fR {\fIsepChar\fR ,} +A wrapper around \fB::csv::split2queue\fR (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given queue. +.TP +\fB::csv::report\fR \fIcmd matrix\fR ?\fIchan\fR? +A report command which can be used by the matrix methods +\fBformat 2string\fR and \fBformat 2chan\fR. For the latter this +command delegates the work to \fB::csv::writematrix\fR. \fIcmd\fR is +expected to be either \fBprintmatrix\fR or +\fBprintmatrix2channel\fR. The channel argument, \fIchan\fR, has +to be present for the latter and must not be present for the first. +.TP +\fB::csv::split\fR ?\fB-alternate\fR? \fIline\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +converts a \fIline\fR 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 \fIsepChar\fR, but this +is optional. The default is ",". The quoting character can be defined +by the caller, but this is optional. The default is '"'. +.sp +If the option \fB-alternate\fR is specified a slightly different +syntax is used to parse the input. This syntax is explained below, in +the section \fBFORMAT\fR. +.TP +\fB::csv::split2matrix\fR ?\fB-alternate\fR? \fIm line\fR {\fIsepChar\fR ,} {\fIexpand\fR none} +The same as \fB::csv::split\fR, but appends the resulting list as a +new row to the matrix \fIm\fR, using the method \fBadd row\fR. The +expansion mode specified via \fIexpand\fR determines how the command +handles a matrix with less columns than contained in \fIline\fR. The +allowed modes are: +.RS +.TP +\fBnone\fR +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. +.TP +\fBempty\fR +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 +\fBnone\fR was set. +.TP +\fBauto\fR +In this mode the command expands the matrix as needed to hold all +columns contained in \fIline\fR. 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. +.RE +.TP +\fB::csv::split2queue\fR ?\fB-alternate\fR? \fIq line\fR {\fIsepChar\fR ,} +The same as \fB::csv::split\fR, but appending the resulting list as a +single item to the queue \fIq\fR, using the method \fBput\fR. +.TP +\fB::csv::writematrix\fR \fIm chan\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +A wrapper around \fB::csv::join\fR taking all rows in the matrix +\fIm\fR and writing them CSV formatted into the channel \fIchan\fR. +.TP +\fB::csv::writequeue\fR \fIq chan\fR ?\fIsepChar\fR? ?\fIdelChar\fR? +A wrapper around \fB::csv::join\fR taking all items in the queue +\fIq\fR (assumes that they are lists) and writing them CSV formatted +into the channel \fIchan\fR. +.PP +.SH FORMAT +.PP +The format of regular CSV files is specified as +.IP [1] +Each record of a csv file (comma-separated values, as exported e.g. by +Excel) is a set of ASCII values separated by ",". For other languages +it may be ";" however, although this is not important for this case as +the functions provided here allow any separator character. +.IP [2] +If and only if a value contains itself the separator ",", then it (the +value) has to be put between "". If the value does not contain the +separator character then quoting is optional. +.IP [3] +If a value contains the character ", that character is represented by "". +.IP [4] +The output string "" represents the value ". In other words, it is +assumed that it was created through rule 3, and only this rule, +i.e. that the value was not quoted. +.PP +.PP +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. +.PP +The alternate format is activated through specification of the option +\fB-alternate\fR to the various split commands. +.SH EXAMPLE +Using the regular format the record +.PP +.CS + + +123,"123,521.2","Mary says ""Hello, I am Mary""","" + +.CE +.PP +is parsed into the items +.PP +.CS + + +a) 123 +b) 123,521.2 +c) Mary says "Hello, I am Mary" +d) " + +.CE +.PP +Using the alternate format the result is +.PP +.CS + + +a) 123 +b) 123,521.2 +c) Mary says "Hello, I am Mary" +d) (the empty string) + +.CE +instead. As can be seen only item (d) is different, now the empty string +instead of a ". +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIcsv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +matrix, queue +.SH KEYWORDS +csv, matrix, package, queue, tcllib +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2002-2013 Andreas Kupries + +.fi ADDED embedded/man/files/modules/des/des.n Index: embedded/man/files/modules/des/des.n ================================================================== --- /dev/null +++ embedded/man/files/modules/des/des.n @@ -0,0 +1,419 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/des/des.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "des" n 1.1 tcllib "Data Encryption Standard (DES)" +.BS +.SH NAME +des \- Implementation of the DES and triple-DES ciphers +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBdes 1.1\fR +.sp +\fB::DES::des\fR ?\fI-mode [ecb|cbc|cfb|ofb]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-hex\fR? ?\fI-weak\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? [ \fI-in channel\fR | \fIdata\fR ] +.sp +\fB::DES::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR ?\fIweak\fR? +.sp +\fB::DES::Encrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::DES::Decrypt\fR \fIKey\fR \fIdata\fR +.sp +\fB::DES::Reset\fR \fIKey\fR \fIiv\fR +.sp +\fB::DES::Final\fR \fIKey\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +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. +.SH COMMANDS +.TP +\fB::DES::des\fR ?\fI-mode [ecb|cbc|cfb|ofb]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-hex\fR? ?\fI-weak\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? [ \fI-in channel\fR | \fIdata\fR ] +Perform the \fBDES\fR algorithm on either the data provided +by the argument or on the data read from the \fI-in\fR channel. If +an \fI-out\fR channel is given then the result will be written to +this channel. +.sp +The \fI-key\fR 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. +.sp +The \fI-mode\fR and \fI-dir\fR options are optional and default to cbc +mode and encrypt respectively. The initialization vector \fI-iv\fR +takes an 8 byte binary argument. This defaults to all zeros. See +\fBMODES OF OPERATION\fR for more about \fI-mode\fR and the use +of the initialization vector. +.sp +DES is a 64-bit block cipher. This means that the data must be +provided in units that are a multiple of 8 bytes. +.PP +.SH "PROGRAMMING INTERFACE" +Internal state is maintained in an opaque structure that is returned +from the \fBInit\fR 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 \fBReset\fR function with a new +initialization vector value. +.TP +\fB::DES::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR ?\fIweak\fR? +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 \fBMODES OF OPERATION\fR. +.sp +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 \fIweak\fR +parameter can be set true to avoid the error being thrown. +.TP +\fB::DES::Encrypt\fR \fIKey\fR \fIdata\fR +Use a prepared key acquired by calling \fBInit\fR 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. +.TP +\fB::DES::Decrypt\fR \fIKey\fR \fIdata\fR +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. +.TP +\fB::DES::Reset\fR \fIKey\fR \fIiv\fR +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. +.TP +\fB::DES::Final\fR \fIKey\fR +This should be called to clean up resources associated with \fIKey\fR. +Once this function has been called the key may not be used again. +.PP +.SH "MODES OF OPERATION" +.TP +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. +.TP +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. +.TP +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. +.TP +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. +.PP +.SH EXAMPLES +.CS + + +% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext] +% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext] + +.CE +.CS + + +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 + +.CE +.SH REFERENCES +.IP [1] +"Data Encryption Standard", +Federal Information Processing Standards Publication 46-3, 1999, +(\fIhttp://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf\fR) +.IP [2] +"TclDES: munitions-grade Tcl scripting" +\fIhttp://tcldes.sourceforge.net/\fR +.PP +.SH AUTHORS +Jochen C Loewer, +Mac Cody, +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdes\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +aes(n), blowfish(n), md5(n), rc4(n), sha1(n) +.SH KEYWORDS +3DES, DES, block cipher, data integrity, encryption, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2005, Pat Thoyts + +.fi ADDED embedded/man/files/modules/dns/tcllib_dns.n Index: embedded/man/files/modules/dns/tcllib_dns.n ================================================================== --- /dev/null +++ embedded/man/files/modules/dns/tcllib_dns.n @@ -0,0 +1,505 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/dns/tcllib_dns.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "dns" n 1.3.3 tcllib "Domain Name Service" +.BS +.SH NAME +dns \- Tcl Domain Name Service Client +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBdns ?1.3.3?\fR +.sp +\fB::dns::resolve\fR \fIquery\fR ?\fIoptions\fR? +.sp +\fB::dns::configure\fR ?\fIoptions\fR? +.sp +\fB::dns::name\fR \fItoken\fR +.sp +\fB::dns::address\fR \fItoken\fR +.sp +\fB::dns::cname\fR \fItoken\fR +.sp +\fB::dns::result\fR \fItoken\fR +.sp +\fB::dns::status\fR \fItoken\fR +.sp +\fB::dns::error\fR \fItoken\fR +.sp +\fB::dns::reset\fR \fItoken\fR +.sp +\fB::dns::wait\fR \fItoken\fR +.sp +\fB::dns::cleanup\fR \fItoken\fR +.sp +\fB::dns::nameservers\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBuri\fR to support DNS URIs +(4) of the form \fIdns:what.host.com\fR or +\fIdns://my.nameserver/what.host.com\fR. The \fBdns::resolve\fR +command can handle DNS URIs or simple domain names as a query. +.PP +\fINote:\fR The package defaults to using DNS over TCP +connections. If you wish to use UDP you will need to have the +\fBtcludp\fR package installed and have a version that +correctly handles binary data (> 1.0.4). +This is available at \fIhttp://tcludp.sourceforge.net/\fR. +If the \fBudp\fR package is present then UDP will be used by default. +.SH COMMANDS +.TP +\fB::dns::resolve\fR \fIquery\fR ?\fIoptions\fR? +Resolve a domain name using the \fIDNS\fR protocol. \fIquery\fR is +the domain name to be lookup up. This should be either a fully +qualified domain name or a DNS URI. +.RS +.TP +\fB-nameserver\fR \fIhostname\fR or \fB-server\fR \fIhostname\fR +Specify an alternative name server for this request. +.TP +\fB-protocol\fR \fItcp|udp\fR +Specify the network protocol to use for this request. Can be one of +\fItcp\fR or \fIudp\fR. +.TP +\fB-port\fR \fIportnum\fR +Specify an alternative port. +.TP +\fB-search\fR \fIdomainlist\fR +.TP +\fB-timeout\fR \fImilliseconds\fR +Override the default timeout. +.TP +\fB-type\fR \fITYPE\fR +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 \fIhttp://spf.pobox.com/\fR about SPF. +See (3) about AAAA records and RFC2782 for details of SRV records. +.TP +\fB-class\fR \fICLASS\fR +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. +.TP +\fB-recurse\fR \fIboolean\fR +Set to \fIfalse\fR if you do not want the name server to recursively +act upon your request. Normally set to \fItrue\fR. +.TP +\fB-command\fR \fIprocname\fR +Set a procedure to be called upon request completion. The procedure +will be passed the token as its only argument. +.RE +.sp +.TP +\fB::dns::configure\fR ?\fIoptions\fR? +The \fB::dns::configure\fR 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. +.RS +.TP +\fB-nameserver\fR \fIhostname\fR +Set the default name server to be used by all queries. The default is +\fIlocalhost\fR. +.TP +\fB-protocol\fR \fItcp|udp\fR +Set the default network protocol to be used. Default is \fItcp\fR. +.TP +\fB-port\fR \fIportnum\fR +Set the default port to use on the name server. The default is 53. +.TP +\fB-search\fR \fIdomainlist\fR +Set the domain search list. This is currently not used. +.TP +\fB-timeout\fR \fImilliseconds\fR +Set the default timeout value for DNS lookups. Default is 30 seconds. +.TP +\fB-loglevel\fR \fIlevel\fR +Set the log level used for emitting diagnostic messages from this +package. The default is \fIwarn\fR. See the \fBlog\fR package +for details of the available levels. +.RE +.sp +.TP +\fB::dns::name\fR \fItoken\fR +Returns a list of all domain names returned as an answer to your query. +.sp +.TP +\fB::dns::address\fR \fItoken\fR +Returns a list of the address records that match your query. +.sp +.TP +\fB::dns::cname\fR \fItoken\fR +Returns a list of canonical names (usually just one) matching your query. +.sp +.TP +\fB::dns::result\fR \fItoken\fR +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. +.sp +.TP +\fB::dns::status\fR \fItoken\fR +Returns the status flag. For a successfully completed query this will be +\fIok\fR. May be \fIerror\fR or \fItimeout\fR or \fIeof\fR. +See also \fB::dns::error\fR +.sp +.TP +\fB::dns::error\fR \fItoken\fR +Returns the error message provided for requests whose status is \fIerror\fR. +If there is no error message then an empty string is returned. +.sp +.TP +\fB::dns::reset\fR \fItoken\fR +Reset or cancel a DNS query. +.sp +.TP +\fB::dns::wait\fR \fItoken\fR +Wait for a DNS query to complete and return the status upon completion. +.sp +.TP +\fB::dns::cleanup\fR \fItoken\fR +Remove all state variables associated with the request. +.sp +.TP +\fB::dns::nameservers\fR +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. +.PP +.SH EXAMPLES +.PP +.CS + + +% 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 + +.CE +.PP +Using DNS URIs as queries: +.CS + + +% set tok [dns::resolve "dns:tcl.tk;type=MX"] +% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"] + +.CE +.PP +Reverse address lookup: +.CS + + +% set tok [dns::resolve 127.0.0.1] +::dns::1 +% dns::name $tok +localhost +% dns::cleanup $tok + +.CE +.SH REFERENCES +.IP [1] +Mockapetris, P., "Domain Names - Concepts and Facilities", +RFC 1034, November 1987. +(\fIhttp://www.ietf.org/rfc/rfc1034.txt\fR) +.IP [2] +Mockapetris, P., "Domain Names - Implementation and Specification", +RFC 1035, November 1087. +(\fIhttp://www.ietf.org/rfc/rfc1035.txt\fR) +.IP [3] +Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", +RFC 1886, December 1995. +(\fIhttp://www.ietf.org/rfc/rfc1886.txt\fR) +.IP [4] +Josefsson, S., "Domain Name System Uniform Resource Identifiers", +Internet-Draft, October 2003, +(\fIhttp://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt\fR) +.IP [5] +Gulbrandsen, A., Vixie, P. and Esibov, L., +"A DNS RR for specifying the location of services (DNS SRV)", +RFC 2782, February 2000, +(\fIhttp://www.ietf.org/rfc/rfc2782.txt\fR) +.IP [6] +Ohta, M. "Incremental Zone Transfer in DNS", +RFC 1995, August 1996, +(\fIhttp://www.ietf.org/rfc/rfc1995.txt\fR) +.PP +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdns\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +resolver(5) +.SH KEYWORDS +DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts + +.fi ADDED embedded/man/files/modules/dns/tcllib_ip.n Index: embedded/man/files/modules/dns/tcllib_ip.n ================================================================== --- /dev/null +++ embedded/man/files/modules/dns/tcllib_ip.n @@ -0,0 +1,693 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/dns/tcllib_ip.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004, Pat Thoyts +'\" Copyright (c) 2005 Aamer Akhter +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcllib_ip" n 1.3 tcllib "Domain Name Service" +.BS +.SH NAME +tcllib_ip \- IPv4 and IPv6 address manipulation +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBip ?1.2?\fR +.sp +\fB::ip::version\fR \fIaddress\fR +.sp +\fB::ip::is\fR \fIclass\fR \fIaddress\fR +.sp +\fB::ip::equal\fR \fIaddress\fR \fIaddress\fR +.sp +\fB::ip::normalize\fR \fIaddress\fR +.sp +\fB::ip::contract\fR \fIaddress\fR +.sp +\fB::ip::prefix\fR \fIaddress\fR +.sp +\fB::ip::type\fR \fIaddress\fR +.sp +\fB::ip::mask\fR \fIaddress\fR +.sp +\fB::ip::prefixToNative\fR \fIprefix\fR +.sp +\fB::ip::nativeToPrefix\fR \fInativeList\fR|\fInative\fR ?\fB-ipv4\fR? +.sp +\fB::ip::intToString\fR \fInumber\fR ?\fB-ipv4\fR? +.sp +\fB::ip::toInteger\fR \fIipaddr\fR +.sp +\fB::ip::toHex\fR \fIipaddr\fR +.sp +\fB::ip::maskToInt\fR \fIipmask\fR +.sp +\fB::ip::broadcastAddress\fR \fIprefix\fR ?\fB-ipv4\fR? +.sp +\fB::ip::maskToLength\fR \fIdottedMask\fR|\fIintegerMask\fR|\fIhexMask\fR ?\fB-ipv4\fR? +.sp +\fB::ip::lengthToMask\fR \fImaskLength\fR ?\fB-ipv4\fR? +.sp +\fB::ip::nextNet\fR \fIipaddr\fR \fIipmask\fR ?\fIcount\fR? ?\fB-ipv4\fR? +.sp +\fB::ip::isOverlap\fR \fIprefix\fR \fIprefix\fR... +.sp +\fB::ip::isOverlapNative\fR ?\fB-all\fR? ?\fB-inline\fR? ?\fB-ipv4\fR? \fIhexipaddr\fR \fIhexipmask\fR \fIhexiplist\fR +.sp +\fB::ip::ipToLayer2Multicast\fR \fIipaddr\fR +.sp +\fB::ip::ipHostFromPrefix\fR \fIprefix\fR ?\fB-exclude\fR \fIprefixExcludeList\fR? +.sp +\fB::ip::reduceToAggregates\fR \fIprefixlist\fR +.sp +\fB::ip::longestPrefixMatch\fR \fIipaddr\fR \fIprefixlist\fR ?\fB-ipv4\fR? +.sp +\fB::ip::collapse\fR \fIprefixlist\fR +.sp +\fB::ip::subtract\fR \fIprefixlist\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::ip::version\fR \fIaddress\fR +Returns the protocol version of the address (4 or 6) or 0 if the +address is neither IPv4 or IPv6. +.TP +\fB::ip::is\fR \fIclass\fR \fIaddress\fR +Returns true if the address is a member of the given protocol +class. The class parameter may be either \fIipv4\fR or \fIipv6\fR +This is effectively a boolean equivalent of the \fBversion\fR +command. The \fIclass\fR argument may be shortened to \fI4\fR or +\fI6\fR. +.TP +\fB::ip::equal\fR \fIaddress\fR \fIaddress\fR +Compare two address specifications for equivalence. The arguments are +normalized and the address prefix determined (if a mask is +supplied). The normalized addresses are then compared bit-by-bit and +the procedure returns true if they match. +.TP +\fB::ip::normalize\fR \fIaddress\fR +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 digts.. This procedure is the opposite of +\fBcontract\fR. +.TP +\fB::ip::contract\fR \fIaddress\fR +Convert a \fBnormalize\fRd internet address into a more compact form +suitable for displaying to users. +.TP +\fB::ip::prefix\fR \fIaddress\fR +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 \fBnormalize\fR +.TP +\fB::ip::type\fR \fIaddress\fR +.TP +\fB::ip::mask\fR \fIaddress\fR +If the address supplied includes a mask then this is returned +otherwise returns an empty string. +.TP +\fB::ip::prefixToNative\fR \fIprefix\fR +This command converts the string \fIprefix\fR from dotted form +(/ format) to native (hex) form. Returns a list +containing two elements, ipaddress and mask, in this order, in +hexadecimal notation. +.sp +.CS + + + % ip::prefixToNative 1.1.1.0/24 + 0x01010100 0xffffff00 + +.CE +.TP +\fB::ip::nativeToPrefix\fR \fInativeList\fR|\fInative\fR ?\fB-ipv4\fR? +This command converts from native (hex) form to dotted form. +It is the complement of \fB::ip::prefixToNative\fR. +.sp +.RS +.TP +list \fInativeList\fR (in) +List of several ip addresses in native form. The native form is a list +as returned by \fB::ip::prefixToNative\fR. +.TP +list \fInative\fR (in) +A list as returned by \fB::ip::prefixToNative\fR. +.RE +.sp +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. +.sp +.CS + + + % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4 + 1.1.1.0/24 + +.CE +.TP +\fB::ip::intToString\fR \fInumber\fR ?\fB-ipv4\fR? +This command converts from an ip address specified as integer number +to dotted form. +.sp +.CS + + + ip::intToString 4294967295 + 255.255.255.255 + +.CE +.TP +\fB::ip::toInteger\fR \fIipaddr\fR +This command converts a dotted form ip into an integer number. +.sp +.CS + + + % ::ip::toInteger 1.1.1.0 + 16843008 + +.CE +.TP +\fB::ip::toHex\fR \fIipaddr\fR +This command converts dotted form ip into a hexadecimal number. +.sp +.CS + + + % ::ip::toHex 1.1.1.0 + 0x01010100 + +.CE +.TP +\fB::ip::maskToInt\fR \fIipmask\fR +This command convert an ipmask in either dotted (255.255.255.0) form +or mask length form (24) into an integer number. +.sp +.CS + + + ::ip::maskToInt 24 + 4294967040 + +.CE +.TP +\fB::ip::broadcastAddress\fR \fIprefix\fR ?\fB-ipv4\fR? +This commands returns a broadcast address in dotted form for the given +route \fIprefix\fR, either in the form "addr/mask", or in native +form. The result is in dotted form. +.sp +.CS + + + ::ip::broadcastAddress 1.1.1.0/24 + 1.1.1.255 + + ::ip::broadcastAddress {0x01010100 0xffffff00} + 0x010101ff + +.CE +.TP +\fB::ip::maskToLength\fR \fIdottedMask\fR|\fIintegerMask\fR|\fIhexMask\fR ?\fB-ipv4\fR? +This command converts the dotted or integer form of an ipmask to +the mask length form. +.sp +.CS + + + ::ip::maskToLength 0xffffff00 -ipv4 + 24 + + % ::ip::maskToLength 255.255.255.0 + 24 + +.CE +.TP +\fB::ip::lengthToMask\fR \fImaskLength\fR ?\fB-ipv4\fR? +This command converts an ipmask in mask length form to its dotted +form. +.sp +.CS + + + ::ip::lengthToMask 24 + 255.255.255.0 + +.CE +.TP +\fB::ip::nextNet\fR \fIipaddr\fR \fIipmask\fR ?\fIcount\fR? ?\fB-ipv4\fR? +This command returns an ipaddress in the same position in the +\fIcount\fR next network. The default value for \fIcount\fR is +\fB1\fR. +.sp +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. +.sp +The result is in hex form. +.TP +\fB::ip::isOverlap\fR \fIprefix\fR \fIprefix\fR... +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. +.sp +.CS + + + % ::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 + +.CE +.TP +\fB::ip::isOverlapNative\fR ?\fB-all\fR? ?\fB-inline\fR? ?\fB-ipv4\fR? \fIhexipaddr\fR \fIhexipmask\fR \fIhexiplist\fR +This command is similar to \fB::ip::isOverlap\fR, however the +arguments are in the native form, and the form of the result is under +greater control of the caller. +If the option \fB-all\fR is specified it checks all addresses for +overlap, not only until the first one is found. +If the option \fB-inline\fR is specified the command returns the +overlapping prefix instead of index values. +.sp +The result of the command is, depending on the specified options, +.RS +.TP +no options +The index of the first overlap found, or 0 if there is none. +.TP +-all +A list containing the indices of all overlaps found, or an empty list +if there are none. +.TP +-inline +The first overlapping prefix, or an empoty string if there is none. +.TP +-all -inline +A list containing the prefixes of all overlaps found, or an empty list +if there are none. +.RE +.sp +.CS + + + % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}} + 0 + + % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}} + 2 + +.CE +.TP +\fB::ip::ipToLayer2Multicast\fR \fIipaddr\fR +This command an converts ipv4 address in dotted form into a layer 2 +multicast address, also in dotted form. +.sp +.CS + + + % ::ip::ipToLayer2Multicast 224.0.0.2 + 01.00.5e.00.00.02 + +.CE +.TP +\fB::ip::ipHostFromPrefix\fR \fIprefix\fR ?\fB-exclude\fR \fIprefixExcludeList\fR? +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 \fIprefixExcludeList\fR. +The result is an ip address in dotted form. +.sp +.CS + + + %::ip::ipHostFromPrefix 1.1.1.5/24 + 1.1.1.1 + + %::ip::ipHostFromPrefix 1.1.1.1/32 + 1.1.1.1 + +.CE +.TP +\fB::ip::reduceToAggregates\fR \fIprefixlist\fR +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. +.sp +.CS + + + % ::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 + +.CE +.TP +\fB::ip::longestPrefixMatch\fR \fIipaddr\fR \fIprefixlist\fR ?\fB-ipv4\fR? +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. +.sp +.CS + + + % ::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 + +.CE +.TP +\fB::ip::collapse\fR \fIprefixlist\fR +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. +.sp +This is different from \fB::ip::reduceToAggregates\fR 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. +.sp +.CS + + +% ::ip::collapse {1.2.2.0/24 1.2.3.0/24} +1.2.2.0/23 + +.CE +.TP +\fB::ip::subtract\fR \fIprefixlist\fR +This command takes a list of prefixes, some of which are prefixed by a +dash. These latter \fInegative\fR prefixes are used to punch holes +into the ranges described by the other, \fIpositive\fR, +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. +.PP +.SH EXAMPLES +.PP +.CS + + +% ip::version ::1 +6 +% ip::version 127.0.0.1 +4 + +.CE +.CS + + +% 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 + +.CE +.CS + + +% ip::equal 192.168.0.4/16 192.168.0.0/16 +1 +% ip::equal fec0::1/10 fec0::fe01/10 +1 + +.CE +.SH REFERENCES +.IP [1] +Postel, J. "Internet Protocol." RFC 791, September 1981, +(\fIhttp://www.ietf.org/rfc/rfc791.txt\fR) +.IP [2] +Hinden, R. and Deering, S., +"Internet Protocol Version 6 (IPv6) Addressing Architecture", +RFC 3513, April 2003 +(\fIhttp://www.ietf.org/rfc/rfc3513.txt\fR) +.PP +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdns\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +inet(3), ip(7), ipv6(7) +.SH KEYWORDS +internet address, ip, ipv4, ipv6, rfc 3513 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2004, Pat Thoyts +Copyright (c) 2005 Aamer Akhter + +.fi ADDED embedded/man/files/modules/docstrip/docstrip.n Index: embedded/man/files/modules/docstrip/docstrip.n ================================================================== --- /dev/null +++ embedded/man/files/modules/docstrip/docstrip.n @@ -0,0 +1,692 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/docstrip/docstrip.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003–2010 Lars Hellström +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docstrip" n 1.2 tcllib "Literate programming tool" +.BS +.SH NAME +docstrip \- Docstrip style source code extraction +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdocstrip ?1.2?\fR +.sp +\fBdocstrip::extract\fR \fItext\fR \fIterminals\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::sourcefrom\fR \fIfilename\fR \fIterminals\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +.BE +.SH DESCRIPTION +\fBDocstrip\fR 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 \fBdocstrip\fR which prevents using it +for other types of software. +.PP +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 \fBdocstrip\fR Tcl package handles this translation. +.PP +Even for those who do not whole-hartedly subscribe to the philosophy +behind literate programming, \fBdocstrip\fR can bring greater +clarity to in particular: +.IP \(bu +programs employing non-obvious mathematics +.IP \(bu +projects where separate pieces of code, perhaps in +different languages, need to be closely coordinated. +.PP +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. +.PP +The way it works is that the programmer edits directly only one or +several "master" source code files, from which \fBdocstrip\fR +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 \fIdoc\fRumentation was \fIstrip\fRped 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 \fBdocstrip\fR Tcl package contains a reimplementation of +the basic extraction functionality from the \fBdocstrip\fR +program, and thus makes it possible for a Tcl interpreter to read +and interpret the master source files directly. +.PP +Readers who are not previously familiar with \fBdocstrip\fR but +want to know more about it may consult the following sources. +.IP [1] +\fIThe tclldoc package and class\fR, +\fIhttp://ctan.org/tex-archive/macros/latex/contrib/tclldoc/\fR. +.IP [2] +\fIThe DocStrip utility\fR, +\fIhttp://ctan.org/tex-archive/macros/latex/base/docstrip.dtx\fR. +.IP [3] +\fIThe doc and shortvrb Packages\fR, +\fIhttp://ctan.org/tex-archive/macros/latex/base/doc.dtx\fR. +.IP [4] +Chapter 14 of +\fIThe LaTeX Companion\fR (second edition), +Addison-Wesley, 2004; ISBN 0-201-36299-6. +.PP +.SH "FILE FORMAT" +The basic unit \fBdocstrip\fR operates on are the \fIlines\fR 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 \fIcode lines\fR (which are copied and +do not begin with a percent character) and \fIcomment lines\fR +(which begin with a percent character and are not copied). +.CS + + + docstrip::extract [join { + {% comment} + {% more comment !"#$%&/(} + {some command} + { % blah $blah "Not a comment."} + {% abc; this is comment} + {# def; this is code} + {ghi} + {% jkl} + } \\n] {} + +.CE +returns the same sequence of lines as +.CS + + + join { + {some command} + { % blah $blah "Not a comment."} + {# def; this is code} + {ghi} "" + } \\n + +.CE +It does not matter to \fBdocstrip\fR 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 +\fBdocstrip::util\fR package also gives some support for +\fIdoctools\fR-like markup. +.PP +Besides the basic code and comment lines, there are also +\fIguard lines\fR, which begin with the two characters '%<', and +\fImeta-comment lines\fR, which begin with the two characters +\'%%'. Within guard lines there is furthermore the distinction between +\fIverbatim guard lines\fR, which begin with '%<<', and ordinary +guard lines, where the '%<' is not followed by another '<'. The last +category is by far the most common. +.PP +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 +.CS + + + '%' '<' STARSLASH EXPRESSION '>' + '%' '<' PLUSMINUS EXPRESSION '>' CODE + +.CE +where +.CS + + + STARSLASH ::= '*' | '/' + PLUSMINUS ::= | '+' | '-' + EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION + | SECONDARY '|' EXPRESSION + SECONDARY ::= PRIMARY | PRIMARY '&' SECONDARY + PRIMARY ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')' + CODE ::= { any character except end-of-line } + +.CE +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 \fBdocstrip\fR 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 \fBdocstrip::extract\fR 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. +.PP +In the case of a '%<*\fIEXPRESSION\fR>' guard, the lines guarded are +all lines up to the next '%' guard with the same +\fIEXPRESSION\fR (compared as strings). The blocks of code delimited +by such '*' and '/' guard lines must be properly nested. +.CS + + + set text [join { + {begin} + {%<*foo>} + {1} + {%<*bar>} + {2} + {%} + {%<*!bar>} + {3} + {%} + {4} + {%} + {5} + {%<*bar>} + {6} + {%} + {end} + } \\n] + set res [docstrip::extract $text foo] + append res [docstrip::extract $text {foo bar}] + append res [docstrip::extract $text bar] + +.CE +sets $res to the result of +.CS + + + join { + {begin} + {1} + {3} + {4} + {5} + {end} + {begin} + {1} + {2} + {4} + {5} + {6} + {end} + {begin} + {5} + {6} + {end} "" + } \\n + +.CE +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. +.PP +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 \fB-metaprefix\fR, which +is customarily set to some "comment until end of line" character (or +character sequence) of the language of the code being extracted. +.CS + + + set text [join { + {begin} + {% foo} + {%<+foo>plusfoo} + {%<-foo>minusfoo} + {middle} + {%% some metacomment} + {%<*foo>} + {%%another metacomment} + {%} + {end} + } \\n] + set res [docstrip::extract $text foo -metaprefix {# }] + append res [docstrip::extract $text bar -metaprefix {#}] + +.CE +sets $res to the result of +.CS + + + join { + {begin} + { foo} + {plusfoo} + {middle} + {# some metacomment} + {# another metacomment} + {end} + {begin} + {minusfoo} + {middle} + {# some metacomment} + {end} "" + } \\n + +.CE +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 '%<<\fIEND-TAG\fR' and the verbatim block is terminated by the +first line that is exactly '%\fIEND-TAG\fR'. +.CS + + + set text [join { + {begin} + {%<*myblock>} + {some stupid()} + { #computer} + {%<} + {%QQQ-98765} + { using*strange@programming} + {%} + {end} + } \\n] + set res [docstrip::extract $text myblock -metaprefix {# }] + append res [docstrip::extract $text {}] + +.CE +sets $res to the result of +.CS + + + join { + {begin} + {some stupid()} + { #computer} + {% These three lines are copied verbatim (including percents} + {%% even if -metaprefix is something different than %%).} + {%} + { using*strange@programming} + {end} + {begin} + {end} "" + } \\n + +.CE +The processing of verbatim guards takes place also inside blocks of +lines which due to some outer block guard will not be copied. +.PP +The final piece of \fBdocstrip\fR 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. +.SH COMMANDS +The package defines two commands. +.TP +\fBdocstrip::extract\fR \fItext\fR \fIterminals\fR ?\fIoption\fR \fIvalue\fR ...? +The \fBextract\fR command docstrips the \fItext\fR and returns the +extracted lines of code, as a string with each line terminated with +a newline. The \fIterminals\fR is the list of those guard +expression terminals which should evaluate to true. +The available options are: +.RS +.TP +\fB-annotate\fR \fIlines\fR +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. +.TP +\fB-metaprefix\fR \fIstring\fR +The string by which the '%%' prefix of a metacomment line will +be replaced. Defaults to '%%'. For Tcl code this would typically +be '#'. +.TP +\fB-onerror\fR \fIkeyword\fR +Controls what will be done when a format error in the \fItext\fR +being processed is detected. The settings are: +.RS +.TP +\fBignore\fR +Just ignore the error; continue as if nothing happened. +.TP +\fBputs\fR +Write an error message to \fBstderr\fR, then continue +processing. +.TP +\fBthrow\fR +Throw an error. The \fB-errorcode\fR is set to a list whose +first element is \fBDOCSTRIP\fR, second element is the +type of error, and third element is the line number where +the error is detected. This is the default. +.RE +.TP +\fB-trimlines\fR \fIboolean\fR +Controls whether \fIspaces\fR at the end of a line should be +trimmed away before the line is processed. Defaults to true. +.RE +.IP +It should be remarked that the \fIterminals\fR are often called +"options" in the context of the \fBdocstrip\fR program, since +these specify which optional code fragments should be included. +.TP +\fBdocstrip::sourcefrom\fR \fIfilename\fR \fIterminals\fR ?\fIoption\fR \fIvalue\fR ...? +The \fBsourcefrom\fR command is a docstripping emulation of +\fBsource\fR. It opens the file \fIfilename\fR, reads it, closes it, +docstrips the contents as specified by the \fIterminals\fR, and +evaluates the result in the local context of the caller, during +which time the \fBinfo\fR \fBscript\fR value will be the +\fIfilename\fR. The options are passed on to \fBfconfigure\fR to +configure the file before its contents are read. The +\fB-metaprefix\fR is set to '#', all other \fBextract\fR +options have their default values. +.PP +.SH "DOCUMENT STRUCTURE" +The file format (as described above) determines whether a master +source code file can be processed correctly by \fBdocstrip\fR, +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. +.PP +For a document format that does not require any non-Tcl software, see +the \fBddt2man\fR command in the \fBdocstrip::util\fR package. It +is suggested that files employing that document format are given the +suffix "\fI.ddt\fR", to distinguish them from the more traditional +LaTeX-based "\fI.dtx\fR" files. +.PP +Master source files with "\fI.dtx\fR" extension are usually set up so +that they can be typeset directly by \fBlatex\fR without any +support from other files. This is achieved by beginning the file +with the lines +.CS + + + % \\iffalse + %<*driver> + \\documentclass{tclldoc} + \\begin{document} + \\DocInput{\fIfilename.dtx\fR} + \\end{document} + % + % \\fi + +.CE +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. +.PP +The function of the \\iffalse ... \\fi is to skip lines two to seven +on this second time through; this is similar to the "if 0 { ... }" +idiom for block comments in Tcl code, and it is needed here because +(amongst other things) the \\documentclass command may only be +executed once. The function of the guards is to prevent this +short piece of LaTeX code from being extracted by \fBdocstrip\fR. +The total effect is that the file can function both as a LaTeX +document and as a \fBdocstrip\fR master source code file. +.PP +It is not necessary to use the tclldoc document class, but that does +provide a number of features that are convenient for "\fI.dtx\fR" +files containing Tcl code. More information on this matter can be +found in the references above. +.SH "SEE ALSO" +docstrip_util +.SH KEYWORDS +.dtx, LaTeX, docstrip, documentation, literate programming, source +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003–2010 Lars Hellström + +.fi ADDED embedded/man/files/modules/docstrip/docstrip_util.n Index: embedded/man/files/modules/docstrip/docstrip_util.n ================================================================== --- /dev/null +++ embedded/man/files/modules/docstrip/docstrip_util.n @@ -0,0 +1,891 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/docstrip/docstrip_util.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003–2010 Lars Hellström +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docstrip_util" n 1.3 tcllib "Literate programming tool" +.BS +.SH NAME +docstrip_util \- Docstrip-related utilities +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdocstrip ?1.2?\fR +.sp +package require \fBdocstrip::util ?1.3?\fR +.sp +\fBpkgProvide\fR \fIname\fR \fIversion\fR \fIterminals\fR +.sp +\fBpkgIndex\fR ?\fIterminal\fR ...? +.sp +\fBfileoptions\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::util::index_from_catalogue\fR \fIdir\fR \fIpattern\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::util::modules_from_catalogue\fR \fItarget\fR \fIsource\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::util::classical_preamble\fR \fImetaprefix\fR \fImessage\fR \fItarget\fR ?\fIsource\fR \fIterminals\fR ...? +.sp +\fBdocstrip::util::classical_postamble\fR \fImetaprefix\fR \fImessage\fR \fItarget\fR ?\fIsource\fR \fIterminals\fR ...? +.sp +\fBdocstrip::util::packages_provided\fR \fItext\fR ?\fIsetup-script\fR? +.sp +\fBdocstrip::util::ddt2man\fR \fItext\fR +.sp +\fBdocstrip::util::guards\fR \fIsubcmd\fR \fItext\fR +.sp +\fBdocstrip::util::patch\fR \fIsource-var\fR \fIterminals\fR \fIfromtext\fR \fIdiff\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::util::thefile\fR \fIfilename\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fBdocstrip::util::import_unidiff\fR \fIdiff-text\fR ?\fIwarning-var\fR? +.sp +.BE +.SH DESCRIPTION +The \fBdocstrip::util\fR 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 \fBsource\fR code. +.PP +.SH "PACKAGE INDEXING COMMANDS" +Like raw "\fI.tcl\fR" 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 +"\fI.ins\fR" file, but parsing one of those is not an easy task. +Therefore \fBdocstrip::util\fR introduces an alternative encoding +of such information, in the form of a declarative Tcl script: the +\fIcatalogue\fR (of the contents in a source file). +.PP +The special commands which are available inside a catalogue are: +.TP +\fBpkgProvide\fR \fIname\fR \fIversion\fR \fIterminals\fR +Declares that the code for a package with name \fIname\fR and +version \fIversion\fR is made up from those modules in the source +file which are selected by the \fIterminals\fR list of guard +expression terminals. This code should preferably not contain a +\fBpackage\fR \fBprovide\fR command for the package, as one +will be provided by the package loading mechanisms. +.TP +\fBpkgIndex\fR ?\fIterminal\fR ...? +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 \fIterminal\fRs. The name and version of this package is +determined from \fBpackage\fR \fBprovide\fR command(s) found +in that code (hence there must be such a command in there). +.TP +\fBfileoptions\fR ?\fIoption\fR \fIvalue\fR ...? +Declares the \fBfconfigure\fR 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 \fB-encoding\fR 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. +.PP +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. +.PP +To simplify distribution of catalogues together with their source +files, the catalogue is stored \fIin the source file itself\fR as +a module selected by the terminal '\fBdocstrip.tcl::catalogue\fR'. +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. +.PP +Putting catalogue entries next to the code they declare may look as +follows +.CS + + +% First there's the catalogue entry +% \\begin{tcl} +%pkgProvide foo::bar 1.0 {foobar load} +% \\end{tcl} +% second a metacomment used to include a copyright message +% \\begin{macrocode} +%<*foobar> +%% This file is placed in the public domain. +% \\end{macrocode} +% third the package implementation +% \\begin{tcl} +namespace eval foo::bar { + # ... some clever piece of Tcl code elided ... +% \\end{tcl} +% which at some point may have variant code to make use of a +% |load|able extension +% \\begin{tcl} +%<*load> + load [file rootname [info script]][info sharedlibextension] +% +%<*!load> + # ... even more clever scripted counterpart of the extension + # also elided ... +% +} +% +% \\end{tcl} +% and that's it! + +.CE +The corresponding set-up with \fBpkgIndex\fR would be +.CS + + +% First there's the catalogue entry +% \\begin{tcl} +%pkgIndex foobar load +% \\end{tcl} +% second a metacomment used to include a copyright message +% \\begin{tcl} +%<*foobar> +%% This file is placed in the public domain. +% \\end{tcl} +% third the package implementation +% \\begin{tcl} +package provide foo::bar 1.0 +namespace eval foo::bar { + # ... some clever piece of Tcl code elided ... +% \\end{tcl} +% which at some point may have variant code to make use of a +% |load|able extension +% \\begin{tcl} +%<*load> + load [file rootname [info script]][info sharedlibextension] +% +%<*!load> + # ... even more clever scripted counterpart of the extension + # also elided ... +% +} +% +% \\end{tcl} +% and that's it! + +.CE +.TP +\fBdocstrip::util::index_from_catalogue\fR \fIdir\fR \fIpattern\fR ?\fIoption\fR \fIvalue\fR ...? +This command is a sibling of the standard \fBpkg_mkIndex\fR +command, in that it adds package entries to "\fIpkgIndex.tcl\fR" +files. The difference is that it indexes \fBdocstrip\fR-style +source files rather than raw "\fI.tcl\fR" or loadable library files. +Only packages listed in the catalogue of a file are considered. +.sp +The \fIdir\fR argument is the directory in which to look for files +(and whose "\fIpkgIndex.tcl\fR" file should be amended). +The \fIpattern\fR argument is a \fBglob\fR pattern of files to look +into; a typical value would be \fB*.dtx\fR or +\fB*.{dtx,ddt}\fR. Remaining arguments are option-value pairs, +where the supported options are: +.RS +.TP +\fB-recursein\fR \fIdirpattern\fR +If this option is given, then the \fBindex_from_catalogue\fR +operation will be repeated in each subdirectory whose name +matches the \fIdirpattern\fR. \fB-recursein\fR \fB*\fR will +cause the entire subtree rooted at \fIdir\fR to be indexed. +.TP +\fB-sourceconf\fR \fIdictionary\fR +Specify \fBfileoptions\fR to use when reading the catalogues of +files (and also for reading the packages if the catalogue does +not contain a \fBfileoptions\fR 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). \fBascii\fR and +\fButf-8\fR are not very different in that sense. +.TP +\fB-options\fR \fIterminals\fR +The \fIterminals\fR is a list of terminals in addition to +\fBdocstrip.tcl::catalogue\fR 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 \fB-options\fR. +.TP +\fB-report\fR \fIboolean\fR +If the \fIboolean\fR 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. +.TP +\fB-reportcmd\fR \fIcommandPrefix\fR +Every item in the report is handed as an extra argument to the +command prefix. Since \fBindex_from_catalogue\fR would typically +be used at a rather high level in installation scripts and the +like, the \fIcommandPrefix\fR defaults to +"\fBputs\fR \fBstdout\fR". +Use \fBlist\fR to effectively disable this feature. The return +values from the prefix are ignored. +.RE +.IP +The \fBpackage ifneeded\fR scripts that are generated contain +one \fBpackage require docstrip\fR command and one +\fBdocstrip::sourcefrom\fR command. If the catalogue entry was +of the \fBpkgProvide\fR kind then the \fBpackage ifneeded\fR +script also contains the \fBpackage provide\fR command. +.sp +Note that \fBindex_from_catalogue\fR never removes anything from an +existing "\fIpkgIndex.tcl\fR" file. Hence you may need to delete it +(or have \fBpkg_mkIndex\fR recreate it from scratch) before running +\fBindex_from_catalogue\fR to update some piece of information, such +as a package version number. +.sp +.TP +\fBdocstrip::util::modules_from_catalogue\fR \fItarget\fR \fIsource\fR ?\fIoption\fR \fIvalue\fR ...? +This command is an alternative to \fBindex_from_catalogue\fR which +creates Tcl Module ("\fI.tm\fR") files rather than +"\fIpkgIndex.tcl\fR" entries. Since this action is more similar to +what \fBdocstrip\fR classically does, it has features for +putting pre- and postambles on the generated files. +.sp +The \fIsource\fR argument is the name of the source file to +generate "\fI.tm\fR" files from. The \fItarget\fR 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: +.RS +.TP +\fB-preamble\fR \fImessage\fR +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. +.TP +\fB-postamble\fR \fImessage\fR +Like \fB-preamble\fR, but the message is put at the end of the +file instead of the beginning. Defaults to being empty. +.TP +\fB-sourceconf\fR \fIdictionary\fR +Specify \fBfileoptions\fR to use when reading the catalogue of +the \fIsource\fR (and also for reading the packages if the +catalogue does not contain a \fBfileoptions\fR 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). \fBascii\fR and +\fButf-8\fR are not very different in that sense. +.TP +\fB-options\fR \fIterminals\fR +The \fIterminals\fR is a list of terminals in addition to +\fBdocstrip.tcl::catalogue\fR 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 \fB-options\fR. +.TP +\fB-formatpreamble\fR \fIcommandPrefix\fR +Command prefix used to actually format the preamble. Takes four +additional arguments \fImessage\fR, \fItargetFilename\fR, +\fIsourceFilename\fR, and \fIterminalList\fR and returns a fully +formatted preamble. Defaults to using \fBclassical_preamble\fR +with a \fImetaprefix\fR of '##'. +.TP +\fB-formatpostamble\fR \fIcommandPrefix\fR +Command prefix used to actually format the postamble. Takes four +additional arguments \fImessage\fR, \fItargetFilename\fR, +\fIsourceFilename\fR, and \fIterminalList\fR and returns a fully +formatted postamble. Defaults to using \fBclassical_postamble\fR +with a \fImetaprefix\fR of '##'. +.TP +\fB-report\fR \fIboolean\fR +If the \fIboolean\fR 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. +.TP +\fB-reportcmd\fR \fIcommandPrefix\fR +Every item in the report is handed as an extra argument to this +command prefix. Defaults to \fBlist\fR, which effectively disables +this feature. The return values from the prefix are ignored. Use +for example "\fBputs\fR \fBstdout\fR" to get report items +written immediately to the terminal. +.RE +.IP +An existing file of the same name as one to be created will be +overwritten. +.TP +\fBdocstrip::util::classical_preamble\fR \fImetaprefix\fR \fImessage\fR \fItarget\fR ?\fIsource\fR \fIterminals\fR ...? +This command returns a preamble in the classical +\fBdocstrip\fR style +.CS + + +## +## 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 + +.CE +.IP +if called as +.CS + + +docstrip::util::classical_preamble {##}\\ + "\\nSome message line 1\\nline2\\nline3" TARGET SOURCE {foo bar} + +.CE +.IP +The command supports preambles for files generated from multiple +sources, even though \fBmodules_from_catalogue\fR at present does +not need that. +.TP +\fBdocstrip::util::classical_postamble\fR \fImetaprefix\fR \fImessage\fR \fItarget\fR ?\fIsource\fR \fIterminals\fR ...? +This command returns a postamble in the classical +\fBdocstrip\fR style +.CS + + +## Some message line 1 +## line2 +## line3 +## +## End of file `TARGET'. + +.CE +.IP +if called as +.CS + + +docstrip::util::classical_postamble {##}\\ + "Some message line 1\\nline2\\nline3" TARGET SOURCE {foo bar} + +.CE +.IP +In other words, the \fIsource\fR and \fIterminals\fR arguments are +ignored, but supported for symmetry with \fBclassical_preamble\fR. +.TP +\fBdocstrip::util::packages_provided\fR \fItext\fR ?\fIsetup-script\fR? +This command returns a list where every even index element is the +name of a package \fBprovide\fRd by \fItext\fR 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 \fBpkg_mkIndex\fR. +.sp +One difference to \fBpkg_mkIndex\fR is that the \fItext\fR gets +evaluated in a safe interpreter. \fBpackage require\fR commands +are silently ignored, as are unknown commands (which includes +\fBsource\fR and \fBload\fR). Other errors cause +processing of the \fItext\fR to stop, in which case only those +package declarations that had been encountered before the error +will be included in the return value. +.sp +The \fIsetup-script\fR argument can be used to customise the +evaluation environment, if the code in \fItext\fR has some very +special needs. The \fIsetup-script\fR is evaluated in the local +context of the \fBpackages_provided\fR procedure just before the +\fItext\fR 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 \fBc\fR. To for example copy the +contents of the \fB::env\fR array to the safe interpreter, one +might use a \fIsetup-script\fR of +.CS + + $c eval [list array set env [array get ::env]] +.CE +.PP +.SH "SOURCE PROCESSING COMMANDS" +Unlike the previous group of commands, which would use +\fBdocstrip::extract\fR to extract some code lines and then process +those further, the following commands operate on text consisting of +all types of lines. +.TP +\fBdocstrip::util::ddt2man\fR \fItext\fR +The \fBddt2man\fR command reformats \fItext\fR from the general +\fBdocstrip\fR format to \fBdoctools\fR "\fI.man\fR" format +(Tcl Markup Language for Manpages). The different line types are +treated as follows: +.RS +.TP +comment and metacomment lines +The '%' and '%%' prefixes are removed, the rest of the text is +kept as it is. +.TP +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.) +.TP +code lines +\fBexample_begin\fR and \fBexample_end\fR commands are placed +at the beginning and end of every block of consecutive code +lines. Brackets in a code line are converted to \fBlb\fR and +\fBrb\fR commands. +.TP +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. +.TP +other guards +These are treated as code lines, except that the actual guard is +\fBemph\fRasised. +.RE +.IP +At the time of writing, no project has employed \fBdoctools\fR +markup in master source files, so experience of what works well is +not available. A source file could however look as follows +.CS + + +% [manpage_begin gcd n 1.0] +% [moddesc {Greatest Common Divisor}] +% [require gcd [opt 1.0]] +% [description] +% +% [list_begin definitions] +% [call [cmd gcd] [arg a] [arg b]] +% The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which +% must be integers and returns their greatest common divisor. +proc gcd {a b} { +% The first step is to take the absolute values of the arguments. +% This relieves us of having to worry about how signs will be treated +% by the remainder operation. + set a [expr {abs($a)}] + set b [expr {abs($b)}] +% The next line does all of Euclid's algorithm! We can make do +% without a temporary variable, since $a is substituted before the +% [lb]set a $b[rb] and thus continues to hold a reference to the +% "old" value of [var a]. + while {$b>0} { set b [expr { $a % [set a $b] }] } +% In Tcl 8.3 we might want to use [cmd set] instead of [cmd return] +% to get the slight advantage of byte-compilation. +% set a +% return $a +} +% [list_end] +% +% [manpage_end] + +.CE +.IP +If the above text is fed through \fBdocstrip::util::ddt2man\fR then +the result will be a syntactically correct \fBdoctools\fR +manpage, even though its purpose is a bit different. +.sp +It is suggested that master source code files with \fBdoctools\fR +markup are given the suffix "\fI.ddt\fR", hence the "ddt" in +\fBddt2man\fR. +.TP +\fBdocstrip::util::guards\fR \fIsubcmd\fR \fItext\fR +The \fBguards\fR command returns information (mostly of a +statistical nature) about the ordinary docstrip guards that occur +in the \fItext\fR. The \fIsubcmd\fR selects what is returned. +.RS +.TP +\fBcounts\fR +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. +.TP +\fBexprcount\fR +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. +.TP +\fBexprerr\fR +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. +.TP +\fBexpressions\fR +List the guard expressions. The return value is a list, with the +elements in no particular order. +.TP +\fBexprmods\fR +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 \fBguards\fR. +.TP +\fBnames\fR +List the guard expression terminals. The return value is a list, +with the elements in no particular order. +.TP +\fBrotten\fR +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. +.RE +.TP +\fBdocstrip::util::patch\fR \fIsource-var\fR \fIterminals\fR \fIfromtext\fR \fIdiff\fR ?\fIoption\fR \fIvalue\fR ...? +This command tries to apply a \fBdiff\fR file (for example a +contributed patch) that was computed for a generated file to the +\fBdocstrip\fR 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. +.sp +\fBpatch\fR 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 \fIsource-var\fR argument. +The \fIterminals\fR is the list of terminals used to extract the +file that has been patched. The \fIdiff\fR is the actual diff to +apply (in a format as explained below) and the \fIfromtext\fR is +the contents of the file which served as "from" when the diff was +computed. Options can be used to further control the process. +.sp +The process works by "lifting" the hunks in the \fIdiff\fR from +generated to source file, and then applying them to the elements of +the \fIsource-var\fR. In order to do this lifting, it is necessary +to determine how lines in the \fIfromtext\fR correspond to elements +of the \fIsource-var\fR, and that is where the \fIterminals\fR come +in; the source is first \fBextract\fRed under the given +\fIterminals\fR, and the result of that is then matched against +the \fIfromtext\fR. This produces a map which translates line +numbers stated in the \fIdiff\fR to element numbers in +\fIsource-var\fR, which is what is needed to lift the hunks. +.sp +The reason that both the \fIterminals\fR and the \fIfromtext\fR +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 \fIfromtext\fR which +matches what can be extracted from the source. This matching is +affected by the following options: +.RS +.TP +\fB-matching\fR \fImode\fR +How equal must two lines be in order to match? The supported +\fImode\fRs are: +.RS +.TP +\fBexact\fR +Lines must be equal as strings. This is the default. +.TP +\fBanyspace\fR +All sequences of whitespace characters are converted to single +spaces before comparing. +.TP +\fBnonspace\fR +Only non-whitespace characters are considered when comparing. +.TP +\fBnone\fR +Any two lines are considered to be equal. +.RE +.TP +\fB-metaprefix\fR \fIstring\fR +The \fB-metaprefix\fR value to use when extracting. Defaults +to "%%", but for Tcl code it is more likely that "#" or "##" had +been used for the generated file. +.TP +\fB-trimlines\fR \fIboolean\fR +The \fB-trimlines\fR value to use when extracting. Defaults to +true. +.RE +.IP +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 \fBpatch\fR and the patched text itself, as this command +cannot adjust comment lines to match new content. +.sp +An example use would look like +.CS + + +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 + +.CE +.IP +Here, "\fIfrom.dtx\fR" was used as source for "\fIfrom.tcl\fR", which +someone modified into "\fIto.tcl\fR". We're trying to construct a +"\fIto.dtx\fR" which can be used as source for "\fIto.tcl\fR". +.TP +\fBdocstrip::util::thefile\fR \fIfilename\fR ?\fIoption\fR \fIvalue\fR ...? +The \fBthefile\fR command opens the file \fIfilename\fR, 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 \fBfconfigure\fR to configure the open file channel +before anything is read from it. +.TP +\fBdocstrip::util::import_unidiff\fR \fIdiff-text\fR ?\fIwarning-var\fR? +This command parses a unified (\fBdiff\fR flags \fB-U\fR and +\fB--unified\fR) format diff into the list-of-hunks format +expected by \fBdocstrip::util::patch\fR. The \fIdiff-text\fR +argument is the text to parse and the \fIwarning-var\fR is, if +specified, the name in the calling context of a variable to which +any warnings about parsing problems will be \fBappend\fRed. +.sp +The return value is a list of \fIhunks\fR. Each hunk is a list of +five elements "\fIstart1\fR \fIend1\fR \fIstart2\fR \fIend2\fR +\fIlines\fR". \fIstart1\fR and \fIend1\fR are line numbers in the +"from" file of the first and last respectively lines of the hunk. +\fIstart2\fR and \fIend2\fR are the corresponding line numbers in +the "to" file. Line numbers start at 1. The \fIlines\fR 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 \fB-\fR for lines only in the "from" file, \fB+\fR for lines +that are only in the "to" file, and \fB0\fR for lines that are +in both. +.PP +.SH "SEE ALSO" +docstrip, doctools, doctools_fmt +.SH KEYWORDS +.ddt, Tcl module, catalogue, diff, docstrip, doctools, documentation, literate programming, module, package indexing, patch, source +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003–2010 Lars Hellström + +.fi ADDED embedded/man/files/modules/doctools/changelog.n Index: embedded/man/files/modules/doctools/changelog.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/changelog.n @@ -0,0 +1,336 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/changelog.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2013 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::changelog" n 1.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::changelog \- Processing text in Emacs ChangeLog format +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil \fR +.sp +package require \fBdoctools::changelog ?1.1?\fR +.sp +\fB::doctools::changelog::scan\fR \fItext\fR +.sp +\fB::doctools::changelog::flatten\fR \fIentries\fR +.sp +\fB::doctools::changelog::toDoctools\fR \fItitle\fR \fImodule\fR \fIversion\fR \fIentries\fR +.sp +\fB::doctools::changelog::merge\fR \fIentries\fR... +.sp +.BE +.SH DESCRIPTION +This package provides Tcl commands for the processing and reformatting +of text in the "\fIChangeLog\fR" format generated by \fBemacs\fR. +.SH API +.TP +\fB::doctools::changelog::scan\fR \fItext\fR +The command takes the \fItext\fR and parses it under the assumption +that it contains a ChangeLog as generated by \fBemacs\fR. It +returns a data structure describing the contents of this ChangeLog. +.sp +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. +.sp +.CS + + + { + { + date + author + { + { + {file ...} + commenttext + } + ... + } + } + {...} + } + +.CE +.TP +\fB::doctools::changelog::flatten\fR \fIentries\fR +This command converts a list of entries as generated by +\fBchange::scan\fR above into a simpler list of plain +text blocks each containing all the information of a +single entry. +.TP +\fB::doctools::changelog::toDoctools\fR \fItitle\fR \fImodule\fR \fIversion\fR \fIentries\fR +This command converts the pre-parsed ChangeLog \fIentries\fR as +generated by the command \fB::doctools::changelog::scan\fR into a +document in \fIdoctools\fR format and returns it as the result of the +command. +.sp +The other three arguments supply the information for the header of +that document which is not available from the changelog itself. +.TP +\fB::doctools::changelog::merge\fR \fIentries\fR... +Each argument of the command is assumed to be a pre-parsed Changelog +as generated by the command \fB::doctools::changelog::scan\fR. 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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +changelog, doctools, emacs +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2013 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/cvs.n Index: embedded/man/files/modules/doctools/cvs.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/cvs.n @@ -0,0 +1,333 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/cvs.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2008 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::cvs" n 1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::cvs \- Processing text in 'cvs log' format +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil \fR +.sp +package require \fBdoctools::cvs ?1?\fR +.sp +\fB::doctools::cvs::scanLog\fR \fItext\fR \fIevar\fR \fIcvar\fR \fIfvar\fR +.sp +\fB::doctools::cvs::toChangeLog\fR \fIevar\fR \fIcvar\fR \fIfvar\fR +.sp +.BE +.SH DESCRIPTION +This package provides Tcl commands for the processing and reformatting +text in the format generated by the \fBcvs log\fR command. +.PP +The commands \fB::doctools::cvs::scanLog\fR +and \fB::doctools::cvs::toChangeLog\fR are derived from code found on +the \fITcl'ers Wiki\fR [http://wiki.tcl.tk]. See the references at the +end of the page. +.SH API +.TP +\fB::doctools::cvs::scanLog\fR \fItext\fR \fIevar\fR \fIcvar\fR \fIfvar\fR +The command takes the \fItext\fR and parses it under the assumption +that it contains a CVS log as generated by \fBcvs log\fR. The +resulting information is stored in the variables whose names were +specified via \fIevar\fR, \fIcvar\fR, and \fIfvar\fR. +.sp +Already existing information in the referenced variables is preserved, +allowing the caller to merge data from multiple logs into one +database. +.RS +.TP +varname \fIevar\fR (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. +.sp +It should be noted that the entries are listed in the same order as +they were found in the \fItext\fR. This is not necessarily sorted by +date or author. +.sp +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 +\fByear\fR/\fBmonth\fR/\fBday\fR. +.TP +varname \fIcvar\fR (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. +.sp +The values are lists of comments made for the entry. +.TP +varname \fIfvar\fR (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. +.sp +The values are lists of the files the entry is touching. +.RE +.sp +.TP +\fB::doctools::cvs::toChangeLog\fR \fIevar\fR \fIcvar\fR \fIfvar\fR +] +The three arguments for this command are the same as the last three +arguments of the command \fB::doctools::cvs::scanLog\fR. This command +however expects them to be filled with information about one or more +logs. It takes this information and converts it into a text in the +format of a ChangeLog as accepted and generated by \fBemacs\fR. The +constructed text is returned as the result of the command. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +\fIhttp://wiki.tcl.tk/log2changelog\fR +.SH KEYWORDS +changelog, cvs, cvs log, emacs, log +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2008 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx.n Index: embedded/man/files/modules/doctools/docidx.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx.n @@ -0,0 +1,567 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2010 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx" n 1.0.4 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx \- docidx - Processing indices +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBdoctools::idx ?1.0.4?\fR +.sp +\fB::doctools::idx::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR ...? +.sp +\fB::doctools::idx::help\fR +.sp +\fB::doctools::idx::search\fR \fIpath\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBconfigure\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +.sp +\fIobjectName\fR \fBcget\fR \fB-option\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBformat\fR \fItext\fR +.sp +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +.sp +\fIobjectName\fR \fBparameters\fR +.sp +\fIobjectName\fR \fBsearch\fR \fIpath\fR +.sp +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +.sp +\fIobjectName\fR \fBwarnings\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for the creation of objects able to +process and convert text written in the \fIdocidx\fR markup language +into any output format X for which a \fIformatting engine\fR is +available. +.PP +A reader interested in the markup language itself should start with +the \fIdocidx language introduction\fR and proceed from there to +the formal specifications, i.e. the \fIdocidx language syntax\fR +and the \fIdocidx language command reference\fR. +.PP +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a \fIplugin writer\fR then reading +and understanding the \fIdocidx plugin API reference\fR is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. +.SH "PUBLIC API" +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::idx::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR ...? +This command creates a new docidx object with an associated Tcl +command whose name is \fIobjectName\fR. This \fIobject\fR command is +explained in full detail in the sections \fBOBJECT COMMAND\fR +and \fBOBJECT METHODS\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.sp +The options and their values coming after the name of the object are +used to set the initial configuration of the object. +.TP +\fB::doctools::idx::help\fR +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. +.TP +\fB::doctools::idx::search\fR \fIpath\fR +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 \fBFORMAT MAPPING\fR for more explanations. +.sp +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 \fIpath\fR to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the \fIpath\fR added +last is later searched through first. +.sp +An error will be thrown if the \fIpath\fR either does not exist, is +not a directory, or is not readable. +.PP +.SS "OBJECT COMMAND" +All commands created by \fB::doctools::idx::new\fR have the following +general form and may be used to invoke various operations on their +docidx converter object. +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the exact +behavior of the command. See section \fBOBJECT METHODS\fR for +the detailed specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBconfigure\fR +The method returns a list of all known options and their current +values when called without any arguments. +.TP +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +The method behaves like the method \fBcget\fR when called with a +single argument and returns the value of the option specified by said +argument. +.TP +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +The method reconfigures the specified \fBoption\fRs of the object, +setting them to the associated \fIvalue\fRs, when called with an even +number of arguments, at least two. +.sp +The legal options are described in the section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBcget\fR \fB-option\fR +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. +.sp +The legal configuration options are described in section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBformat\fR \fItext\fR +This method runs the \fItext\fR through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no \fB-format\fR was configured for the object. +.sp +The method assumes that the \fItext\fR is in \fIdocidx\fR format as +specified in the companion document \fIdocidx_fmt\fR. Errors will be +thrown otherwise. +.TP +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +This methods add one entry to the per-object mapping from +\fIsymbolic\fR filenames to the \fIactual\fR uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command \fBdt_fmap\fR. +This command is described in more detail in the +\fIdocidx plugin API reference\fR which specifies the interaction +between the objects created by this package and index formatting +engines. +.TP +\fIobjectName\fR \fBparameters\fR +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. +.TP +\fIobjectName\fR \fBsearch\fR \fIpath\fR +This method extends the per-object list of paths searched for index +formatting engines. See also the command \fB::doctools::idx::search\fR +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 \fBFORMAT MAPPING\fR. +.TP +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +This method sets the \fIname\fRd engine parameter to the specified +\fIvalue\fR. +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 \fIname\fR. +The list of parameters provided by the configured formatting engine +can be retrieved through the method \fBparameters\fR. +.TP +\fIobjectName\fR \fBwarnings\fR +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method \fBformat\fR. +.PP +.SS "OBJECT CONFIGURATION" +All docidx objects understand the following configuration options: +.TP +\fB-file\fR \fIfile\fR +The argument of this option is stored in the object and made available +to the configured formatting engine through the command \fBdt_file\fR. +This command is described in more detail in the companion document +\fIdocidx_api\fR which specifies the API between the object and +formatting engines. +.sp +The default value of this option is the empty string. +.sp +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. +.TP +\fB-format\fR \fItext\fR +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method \fBformat\fR. Its default value is the empty string. The +method \fBformat\fR cannot be used if this option is not set to a +valid value at least once. +.sp +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. +.sp +The section \fBFORMAT MAPPING\fR explains in detail how the +package and object will look for engine implementations. +.PP +.SS "FORMAT MAPPING" +The package and object will perform the following algorithm when +trying to map a format name \fIfoo\fR to a file containing an +implementation of a formatting engine for \fIfoo\fR: +.IP [1] +If \fIfoo\fR is the name of an existing file then this file is +directly taken as the implementation. +.IP [2] +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "\fIidx.\fIfoo\fR\fR". If yes, then that file is taken as the +implementation. +.sp +Note that this list of paths is initially empty and can be extended +through the object method \fBsearch\fR. +.IP [3] +If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "\fIidx.\fIfoo\fR\fR". If yes, then that file is taken +as the implementation. +.sp +This list of paths can be extended +through the command \fB::doctools::idx::search\fR. +It contains initially one path, the subdirectory "\fImpformats\fR" of +the directory the package itself is located in. In other words, if the +package implementation "\fIdocidx.tcl\fR" is installed in the directory +"\fI/usr/local/lib/tcllib/doctools\fR" then it will by default search +the directory "\fI/usr/local/lib/tcllib/doctools/mpformats\fR" for +format implementations. +.IP [4] +The mapping fails. +.PP +.SH "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. +.TP +html +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters: +.RS +.TP +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 \fB\fR tag, closing the body of the generated +HTML. +.sp +This can be used to insert boilerplate footer markup into the +generated document. +.TP +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 \fB\fR tag, starting the body of the generated HTML. +.sp +This can be used to insert boilerplate header markup into the +generated document. +.TP +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 \fB\fR tag, starting the header section of the +generated HTML. +.sp +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. +.RE +.sp +.TP +latex +This engine generates output suitable for the \fBlatex\fR text +processor coming out of the TeX world. +.TP +list +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. +.TP +nroff +This engine generates nroff output, for processing by \fBnroff\fR, +or \fBgroff\fR. The result will be standard man pages as they are +known in the unix world. +.TP +null +This engine generates no outout at all. This can be used if one just +wants to validate some input. +.TP +tmml +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. +.TP +wiki +This engine generates Wiki markup as understood by Jean Claude +Wippler's \fBwikit\fR application. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +docidx_intro, docidx_lang_cmdref, docidx_lang_intro, docidx_lang_syntax, docidx_plugin_apiref +.SH KEYWORDS +HTML, TMML, conversion, docidx, documentation, index, keyword index, latex, manpage, markup, nroff, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2010 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_intro.n Index: embedded/man/files/modules/doctools/docidx_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_intro.n @@ -0,0 +1,319 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_intro \- docidx introduction +.SH DESCRIPTION +.PP +\fIdocidx\fR (short for \fIdocumentation tables of contents\fR) +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 +.IP [1] +A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands. +.IP [2] +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. +.IP [3] +An API describing the interface between the package above and a +plugin. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. +.PP +.IP [1] +A \fIwriter\fR of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +\fIdocidx language introduction\fR first. Having digested this +the formal \fIdocidx language syntax\fR specification should +become understandable. A writer experienced with docidx may only +need the \fIdocidx language command reference\fR from time to +time to refresh her memory. +.sp +While a document is written the \fBdtp\fR 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 \fBdtplite\fR application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them. +.IP [2] +A \fIprocessor\fR of documentation written in the \fIdocidx\fR +markup language has to know which tools are available for use. +.sp +The main tool is the aforementioned \fBdtp\fR application provided +by Tcllib. The simpler \fBdtplite\fR does not expose docidx to the +user. +At the bottom level, common to both applications, however sits the +package \fBdoctoools::idx\fR, providing the basic facilities to +read and process files containing text in the docidx format. +.IP [3] +At last, but not least, \fIplugin writers\fR have to understand the +interaction between the \fBdoctools::idx\fR package and its +plugins, as described in the \fIdocidx plugin API reference\fR. +.PP +.SH "RELATED FORMATS" +docidx does not stand alone, it has two companion formats. These are +called \fIdoctoc\fR and \fIdoctools\fR, and they are for the markup +of \fItables of contents\fR, and general documentation, +respectively. +They are described in their own sets of documents, starting at the +\fIdoctoc introduction\fR and the \fIdoctools introduction\fR, +respectively. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax, docidx_plugin_apiref, doctoc_intro, doctools::idx, doctools_intro +.SH KEYWORDS +index, keyword index, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_lang_cmdref.n Index: embedded/man/files/modules/doctools/docidx_lang_cmdref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_lang_cmdref.n @@ -0,0 +1,362 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_lang_cmdref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_lang_cmdref" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_lang_cmdref \- docidx language command reference +.SH SYNOPSIS +\fBcomment\fR \fIplaintext\fR +.sp +\fBinclude\fR \fIfilename\fR +.sp +\fBindex_begin\fR \fItext\fR \fItitle\fR +.sp +\fBindex_end\fR +.sp +\fBkey\fR \fItext\fR +.sp +\fBlb\fR +.sp +\fBmanpage\fR \fIfile\fR \fItext\fR +.sp +\fBrb\fR +.sp +\fBurl\fR \fIurl\fR \fIlabel\fR +.sp +\fBvset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBvset\fR \fIvarname\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fIdocidx language introduction\fR first. +.SH COMMANDS +.TP +\fBcomment\fR \fIplaintext\fR +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. +.TP +\fBinclude\fR \fIfilename\fR +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. +.TP +\fBindex_begin\fR \fItext\fR \fItitle\fR +Document structure. The command to start an index. The arguments are a +label for the whole group of documents the index refers to +(\fItext\fR) and the overall title text for the index (\fItitle\fR), +without markup. +.sp +The label often is the name of the package (or extension) the +documents belong to. +.TP +\fBindex_end\fR +Document structure. Command to end an index. Anything in the document +coming after this command is in error. +.TP +\fBkey\fR \fItext\fR +Index structure. This command adds the keyword \fItext\fR to the +index. +.TP +\fBlb\fR +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. +.TP +\fBmanpage\fR \fIfile\fR \fItext\fR +Index structure. This command adds an element to the index which +refers to a document. The document is specified through the symbolic +name \fIfile\fR. The \fItext\fR argument is used to label the +reference. +.sp +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. +.TP +\fBrb\fR +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. +.TP +\fBurl\fR \fIurl\fR \fIlabel\fR +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. +.TP +\fBvset\fR \fIvarname\fR \fIvalue\fR +Templating. In this form the command sets the named document variable +to the specified \fIvalue\fR. It does not generate output. I.e. the +command is replaced by the empty string. +.TP +\fBvset\fR \fIvarname\fR +Templating. In this form the command is replaced by the value of the +named document variable +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +docidx_intro, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax +.SH KEYWORDS +docidx commands, docidx language, docidx markup, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_lang_faq.n Index: embedded/man/files/modules/doctools/docidx_lang_faq.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_lang_faq.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_lang_faq.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_lang_faq" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_lang_faq \- docidx language faq +.SH DESCRIPTION +.PP +.SH OVERVIEW +.SS "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. +.PP +Please report any questions (and, if possible, answers) we should +consider for this document in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +.SH EXAMPLES +.SS "WHERE DO I FIND DOCIDX EXAMPLES?" +We have no direct examples of documents written using docidx +markup. However the doctools processor \fBdtplite\fR does generate +keyword indices when processing a set of documents written in doctools +markup. The intermediate files use docidx markup and are not deleted +when generation completes. These files can therefore serve as +examples. +.PP +\fBdtplite\fR is distributed as part of Tcllib, so to get it you +need one of +.IP [1] +A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +\fIhttp://sourceforge.net/cvs/?group_id=12883\fR +.IP [2] +A Tcllib release archive. They are available at +\fIhttp://sourceforge.net/project/showfiles.php?group_id=12883\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report any such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +the package and/or the documentation. +.SH "SEE ALSO" +docidx_lang_cmdref, docidx_lang_intro, docidx_lang_syntax +.SH KEYWORDS +docidx commands, docidx language, docidx markup, docidx syntax, examples, faq, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_lang_intro.n Index: embedded/man/files/modules/doctools/docidx_lang_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_lang_intro.n @@ -0,0 +1,434 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_lang_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_lang_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_lang_intro \- docidx language introduction +.SH DESCRIPTION +.PP +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 \fIdocidx language syntax\fR specification +and the \fIdocidx language command reference\fR. +.SS FUNDAMENTALS +While the \fIdocidx markup language\fR is quite similar to the +\fIdoctools markup language\fR, 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. +.PP +Each markup command is a Tcl command surrounded by a matching pair of +\fB[\fR and \fB]\fR. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. +.PP +.CS + + + ... [key {markup language}] ... + +.CE +.CS + + + ... [manpage thefile \\\\ + {file description}] ... + +.CE +.SS "BASIC STRUCTURE" +The most simple document which can be written in docidx is +.CS + + + [index_begin GROUPTITLE TITLE] + [index_end] + +.CE +.PP +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. +.PP +A more useful index will contain at least keywords, or short 'keys', +i.e. the phrases which were indexed. So: +.CS + + +[index_begin GROUPTITLE TITLE] +[\fBkey markup\fR] +[\fBkey {semantic markup}]\fR] +[\fBkey {docidx markup}\fR] +[\fBkey {docidx language}\fR] +[\fBkey {docidx commands}\fR] +[index_end] + +.CE +.PP +In the above example the command \fBkey\fR is used to declare the +keyword phrases we wish to be part of the index. +.PP +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 +\fIbase64\fR: +.CS + + +[index_begin tcllib/base64 {De- & Encoding}] +[key base64] +[\fBmanpage base64\fR] +[key encoding] +[\fBmanpage base64\fR] +[\fBmanpage uuencode\fR] +[\fBmanpage yencode\fR] +[key uuencode] +[\fBmanpage uuencode\fR] +[key yEnc] +[\fBmanpage yencode\fR] +[key ydecode] +[\fBmanpage yencode\fR] +[key yencode] +[\fBmanpage yencode\fR] +[index_end] + +.CE +.PP +In the above example the command \fBmanpage\fR is used to insert +references to documents, using symbolic file names, with each command +belonging to the last \fBkey\fR command coming before it. +.PP +The other command to insert references is \fBurl\fR. In contrast to +\fBmanpage\fR 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. +.SS "ADVANCED STRUCTURE" +In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the \fBindex_begin\fR command opening the +document. +.PP +Instead of only whitespace the two templating commands \fBinclude\fR +and \fBvset\fR 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 +.CS + + +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +[index_begin GROUPTITLE TITLE] +... +[index_end] + +.CE +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. +.CS + + +[index_begin GROUPTITLE TITLE] +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +... +[index_end] + +.CE +The only restriction \fBinclude\fR 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 \fBindex_begin\fR may contain only the templating +commands \fBvset\fR and \fBinclude\fR, a file included after a key +may contain only manape or url references, and other keys, etc. +.SS 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 \fB[\fR and \fB]\fR. +These commands, \fBlb\fR and \fBrb\fR respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text. +.PP +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. +.CS + + + ... + These commands, [cmd lb] and [cmd lb] respectively, are required + because our use of [\fBlb\fR] and [\fBrb\fR] to bracket markup commands makes it + impossible to directly use [\fBlb\fR] and [\fBrb\fR] within the text. + ... + +.CE +.SH "FURTHER READING" +Now that this document has been digested the reader, assumed to be a +\fIwriter\fR of documentation should be fortified enough to be able +to understand the formal \fIdocidx language syntax\fR +specification as well. From here on out the +\fIdocidx language command reference\fR will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. +.PP +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +\fBdtp\fR. +.PP +On the other hand, docidx is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple \fBdtplite\fR goes, creating an index for a set of +documents behind the scenes, without the writer having to do so on +their own. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_intro, docidx_lang_cmdref, docidx_lang_syntax +.SH KEYWORDS +docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_lang_syntax.n Index: embedded/man/files/modules/doctools/docidx_lang_syntax.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_lang_syntax.n @@ -0,0 +1,338 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_lang_syntax.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_lang_syntax" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_lang_syntax \- docidx language syntax +.SH DESCRIPTION +.PP +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 +\fIdocidx language command reference\fR. +A beginner should read the much more informally written +\fIdocidx language introduction\fR first before trying to +understand either this document or the command reference. +.SH FUNDAMENTALS +In the broadest terms possible the \fIdocidx markup language\fR 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. +.PP +Each markup command is a just Tcl command surrounded by a matching +pair of \fB[\fR and \fB]\fR. Which commands are available, +and their arguments, i.e. syntax is specified in the +\fIdocidx language command reference\fR. +.PP +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. +.SH "LEXICAL DEFINITIONS" +In the syntax rules listed in the next section +.IP [1] + stands for all text except markup commands. +.IP [2] +Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of \fB[\fR and \fB]\fR. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. +.IP [3] + stands for all text consisting only of spaces, newlines, +tabulators and the \fBcomment\fR markup command. +.PP +.SH SYNTAX +The rules listed here specify only the syntax of docidx documents. The +lexical level of the language was covered in the previous section. +.PP +Regarding the syntax of the (E)BNF itself +.IP [1] +The construct { X } stands for zero or more occurrences of X. +.IP [2] +The construct [ X ] stands for zero or one occurrence of X. +.PP +The syntax: +.CS + + +index = defs + INDEX_BEGIN + [ contents ] + INDEX_END + { } + +defs = { INCLUDE | VSET | } +contents = keyword { keyword } + +keyword = defs KEY ref { ref } +ref = MANPAGE | URL | defs + +.CE +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. +.IP [1] +The arguments of all markup commands have to be plain text, and/or text +markup commands, i.e. one of +.RS +.IP [1] +\fBlb\fR, +.IP [2] +\fBrb\fR, or +.IP [3] +\fBvset\fR (1-argument form). +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro +.SH KEYWORDS +docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/docidx_plugin_apiref.n Index: embedded/man/files/modules/doctools/docidx_plugin_apiref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/docidx_plugin_apiref.n @@ -0,0 +1,616 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/docidx_plugin_apiref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "docidx_plugin_apiref" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +docidx_plugin_apiref \- docidx plugin API reference +.SH SYNOPSIS +\fBdt_fmap\fR \fIsymfname\fR +.sp +\fBdt_format\fR +.sp +\fBdt_read\fR \fIfile\fR +.sp +\fBdt_source\fR \fIfile\fR +.sp +\fBex_cappend\fR \fItext\fR +.sp +\fBex_cget\fR \fIvarname\fR +.sp +\fBex_cis\fR \fIcname\fR +.sp +\fBex_cname\fR +.sp +\fBex_cpop\fR \fIcname\fR +.sp +\fBex_cpush\fR \fIcname\fR +.sp +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBex_lb\fR ?\fInewbracket\fR? +.sp +\fBex_rb\fR ?\fInewbracket\fR? +.sp +\fBidx_initialize\fR +.sp +\fBidx_listvariables\fR +.sp +\fBidx_numpasses\fR +.sp +\fBidx_postprocess\fR \fItext\fR +.sp +\fBidx_setup\fR \fIn\fR +.sp +\fBidx_shutdown\fR +.sp +\fBidx_varset\fR \fIvarname\fR \fItext\fR +.sp +\fBfmt_plain_text\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +This document is intended for \fIplugin writers\fR, i.e. developers +wishing to write an index \fIformatting engine\fR for some output +format X. +.PP +It specifies the interaction between the \fBdoctools::idx\fR +package and its plugins, i.e. the interface any index formatting +engine has to comply with. +.PP +This document deals with version 1 of the interface. +.PP +A reader who is on the other hand more interested in the markup +language itself should start with the +\fIdocidx language introduction\fR and proceed from there to the +formal specifications, i.e. the \fIdocidx language syntax\fR and +the \fIdocidx language command reference\fR. +.SH OVERVIEW +The API for an index formatting engine consists of two major sections. +.PP +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 +\fBFRONTEND COMMANDS\fR for their detailed specification. +.PP +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 \fBPLUGIN COMMANDS\fR and its subsections for +their detailed specification. +.SH "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. +.PP +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 \fBPLUGIN COMMANDS\fR) are executed. +.PP +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. +.PP +Coming back to the imported commands, all the commands with prefix +\fIdt_\fR provide limited access to specific parts of the frontend, +whereas the commands with prefix \fIex_\fR provide access to the +state of the \fBtextutil::expander\fR object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. +.PP +.TP +\fBdt_fmap\fR \fIsymfname\fR +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename \fIsymfname\fR. It will return the +unchanged input if no mapping was established for \fIsymfname\fR. +.sp +The required mappings are established with the method \fBmap\fR of +a frontend, as explained in section \fBOBJECT METHODS\fR +of the documentation for the package \fBdoctools::idx\fR. +.TP +\fBdt_format\fR +Query command. It returns the name of the format associated with the +index formatting engine. +.TP +\fBdt_read\fR \fIfile\fR +Controlled filesystem access. Returns contents of \fIfile\fR 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. +.TP +\fBdt_source\fR \fIfile\fR +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. +.TP +\fBex_cappend\fR \fItext\fR +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. +.TP +\fBex_cget\fR \fIvarname\fR +Retrieves the value of variable \fIvarname\fR, defined in the current +context. +.TP +\fBex_cis\fR \fIcname\fR +Determines whether or not the name of the current context is +\fIcname\fR. +.TP +\fBex_cname\fR +Returns the name of the current context. +.TP +\fBex_cpop\fR \fIcname\fR +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named \fIcname\fR, or an +error results. +.TP +\fBex_cpush\fR \fIcname\fR +Pushes a context named \fIcname\fR onto the context stack. The +context must be popped by \fBcpop\fR before expansion ends or an +error results. +.TP +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +Sets variable \fIvarname\fR to \fIvalue\fR in the current context. +.TP +\fBex_lb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the new +bracket, and is returned. +.TP +\fBex_rb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the +new bracket, and is returned. +.PP +.SH "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. +.SS "MANAGEMENT COMMANDS" +The management commands a plugin has to provide are used by the +frontend to +.IP [1] +initialize and shutdown the plugin +.IP [2] +determine the number of passes it has +to make over the input +.IP [3] +initialize and shutdown each pass +.IP [4] +query and initialize engine parameters +.PP +.PP +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: +.CS + + + 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 + ... + +.CE +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. +.PP +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 \fBidx_varset\fR. +.PP +In each of the passes, i.e. after the calls of \fBidx_setup\fR 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 \fIdocidx language syntax\fR specification. +.PP +A different way of looking at the sequence is: +.IP \(bu +First some basic parameters are determined. +.IP \(bu +Then everything starting at the first \fBidx_varset\fR to +\fBidx_shutdown\fR forms a \fIrun\fR, the formatting of a +single input. Each run can be followed by more. +.IP \(bu +Embedded within each run we have one or more \fIpasses\fR, +each starting with \fBidx_setup\fR and going until either the next +\fBidx_setup\fR or \fBidx_postprocess\fR is reached. +.sp +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. +.PP +.PP +The commands, their names, signatures, and responsibilities are, in +detail: +.TP +\fBidx_initialize\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBidx_listvariables\fR +\fIInitialization/Shutdown\fR and \fIEngine parameters\fR. +Second command is called after the plugin code has been loaded, +i.e. immediately after \fBidx_numpasses\fR. +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. +.TP +\fBidx_numpasses\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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. +.TP +\fBidx_postprocess\fR \fItext\fR +\fIInitialization/Shutdown\fR. +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. +.sp +Expected to return a value, the final result of formatting the input. +.TP +\fBidx_setup\fR \fIn\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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 \fB1\fR 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. +.TP +\fBidx_shutdown\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBidx_varset\fR \fIvarname\fR \fItext\fR +\fIEngine parameters\fR. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by \fIvarname\fR, the value to +set in \fItext\fR. +.sp +The command has to throw an error if an unknown \fIvarname\fR is +used. Only the names returned by \fBidx_listvariables\fR have to be +considered as known. +.sp +The values of all engine parameters have to persist between passes and +runs. +.PP +.SS "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 \fBlb\fR, \fBrb\fR, \fBvset\fR, \fBinclude\fR, and +\fBcomment\fR. 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. +.PP +This means, that each of the five markup commands specified in the +\fIdocidx language command reference\fR 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 \fIfmt_\fR added to it. +.PP +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. +.PP +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +\fIdocidx language command reference\fR for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. +.PP +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 \fIdocidx language syntax\fR +specification. +.PP +.TP +\fBfmt_plain_text\fR \fItext\fR +\fINo associated markup command\fR. +.sp +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. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax, doctools::idx +.SH KEYWORDS +formatting engine, index, index formatter, keywords, markup, plugin, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc.n Index: embedded/man/files/modules/doctools/doctoc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc.n @@ -0,0 +1,567 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2010 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc" n 1.1.3 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc \- doctoc - Processing tables of contents +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBdoctools::toc ?1.1.3?\fR +.sp +\fB::doctools::toc::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR ...? +.sp +\fB::doctools::toc::help\fR +.sp +\fB::doctools::toc::search\fR \fIpath\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBconfigure\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +.sp +\fIobjectName\fR \fBcget\fR \fB-option\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBformat\fR \fItext\fR +.sp +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +.sp +\fIobjectName\fR \fBparameters\fR +.sp +\fIobjectName\fR \fBsearch\fR \fIpath\fR +.sp +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +.sp +\fIobjectName\fR \fBwarnings\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for the creation of objects able to +process and convert text written in the \fIdoctoc\fR markup language +into any output format X for which a \fIformatting engine\fR is +available. +.PP +A reader interested in the markup language itself should start with +the \fIdoctoc language introduction\fR and proceed from there to +the formal specifications, i.e. the \fIdoctoc language syntax\fR +and the \fIdoctoc language command reference\fR. +.PP +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a \fIplugin writer\fR then reading +and understanding the \fIdoctoc plugin API reference\fR is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. +.SH "PUBLIC API" +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::toc::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR ...? +This command creates a new doctoc object with an associated Tcl +command whose name is \fIobjectName\fR. This \fIobject\fR command is +explained in full detail in the sections \fBOBJECT COMMAND\fR +and \fBOBJECT METHODS\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.sp +The options and their values coming after the name of the object are +used to set the initial configuration of the object. +.TP +\fB::doctools::toc::help\fR +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. +.TP +\fB::doctools::toc::search\fR \fIpath\fR +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 \fBFORMAT MAPPING\fR for more explanations. +.sp +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 \fIpath\fR to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the \fIpath\fR added +last is later searched through first. +.sp +An error will be thrown if the \fIpath\fR either does not exist, is +not a directory, or is not readable. +.PP +.SS "OBJECT COMMAND" +All commands created by \fB::doctools::toc::new\fR have the following +general form and may be used to invoke various operations on their +doctoc converter object. +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the exact +behavior of the command. See section \fBOBJECT METHODS\fR for +the detailed specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBconfigure\fR +The method returns a list of all known options and their current +values when called without any arguments. +.TP +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +The method behaves like the method \fBcget\fR when called with a +single argument and returns the value of the option specified by said +argument. +.TP +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +The method reconfigures the specified \fBoption\fRs of the object, +setting them to the associated \fIvalue\fRs, when called with an even +number of arguments, at least two. +.sp +The legal options are described in the section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBcget\fR \fB-option\fR +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. +.sp +The legal configuration options are described in section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBformat\fR \fItext\fR +This method runs the \fItext\fR through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no \fB-format\fR was configured for the object. +.sp +The method assumes that the \fItext\fR is in \fIdoctoc\fR format as +specified in the companion document \fIdoctoc_fmt\fR. Errors will be +thrown otherwise. +.TP +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +This methods add one entry to the per-object mapping from +\fIsymbolic\fR filenames to the \fIactual\fR uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command \fBdt_fmap\fR. +This command is described in more detail in the +\fIdoctoc plugin API reference\fR which specifies the interaction +between the objects created by this package and toc formatting +engines. +.TP +\fIobjectName\fR \fBparameters\fR +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. +.TP +\fIobjectName\fR \fBsearch\fR \fIpath\fR +This method extends the per-object list of paths searched for toc +formatting engines. See also the command \fB::doctools::toc::search\fR +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 \fBFORMAT MAPPING\fR. +.TP +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +This method sets the \fIname\fRd engine parameter to the specified +\fIvalue\fR. +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 \fIname\fR. +The list of parameters provided by the configured formatting engine +can be retrieved through the method \fBparameters\fR. +.TP +\fIobjectName\fR \fBwarnings\fR +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method \fBformat\fR. +.PP +.SS "OBJECT CONFIGURATION" +All doctoc objects understand the following configuration options: +.TP +\fB-file\fR \fIfile\fR +The argument of this option is stored in the object and made available +to the configured formatting engine through the command \fBdt_file\fR. +This command is described in more detail in the companion document +\fIdoctoc_api\fR which specifies the API between the object and +formatting engines. +.sp +The default value of this option is the empty string. +.sp +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. +.TP +\fB-format\fR \fItext\fR +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method \fBformat\fR. Its default value is the empty string. The +method \fBformat\fR cannot be used if this option is not set to a +valid value at least once. +.sp +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. +.sp +The section \fBFORMAT MAPPING\fR explains in detail how the +package and object will look for engine implementations. +.PP +.SS "FORMAT MAPPING" +The package and object will perform the following algorithm when +trying to map a format name \fIfoo\fR to a file containing an +implementation of a formatting engine for \fIfoo\fR: +.IP [1] +If \fIfoo\fR is the name of an existing file then this file is +directly taken as the implementation. +.IP [2] +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "\fItoc.\fIfoo\fR\fR". If yes, then that file is taken as the +implementation. +.sp +Note that this list of paths is initially empty and can be extended +through the object method \fBsearch\fR. +.IP [3] +If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "\fItoc.\fIfoo\fR\fR". If yes, then that file is taken +as the implementation. +.sp +This list of paths can be extended +through the command \fB::doctools::toc::search\fR. +It contains initially one path, the subdirectory "\fImpformats\fR" of +the directory the package itself is located in. In other words, if the +package implementation "\fIdoctoc.tcl\fR" is installed in the directory +"\fI/usr/local/lib/tcllib/doctools\fR" then it will by default search +the directory "\fI/usr/local/lib/tcllib/doctools/mpformats\fR" for +format implementations. +.IP [4] +The mapping fails. +.PP +.SH "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. +.TP +html +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters: +.RS +.TP +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 \fB\fR tag, closing the body of the generated +HTML. +.sp +This can be used to insert boilerplate footer markup into the +generated document. +.TP +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 \fB\fR tag, starting the body of the generated HTML. +.sp +This can be used to insert boilerplate header markup into the +generated document. +.TP +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 \fB\fR tag, starting the header section of the +generated HTML. +.sp +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. +.RE +.sp +.TP +latex +This engine generates output suitable for the \fBlatex\fR text +processor coming out of the TeX world. +.TP +list +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. +.TP +nroff +This engine generates nroff output, for processing by \fBnroff\fR, +or \fBgroff\fR. The result will be standard man pages as they are +known in the unix world. +.TP +null +This engine generates no outout at all. This can be used if one just +wants to validate some input. +.TP +tmml +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. +.TP +wiki +This engine generates Wiki markup as understood by Jean Claude +Wippler's \fBwikit\fR application. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctoc_intro, doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syntax, doctoc_plugin_apiref +.SH KEYWORDS +HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup, nroff, table of contents, toc, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2010 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_intro.n Index: embedded/man/files/modules/doctools/doctoc_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_intro.n @@ -0,0 +1,318 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_intro \- doctoc introduction +.SH DESCRIPTION +.PP +\fIdoctoc\fR (short for \fIdocumentation tables of contents\fR) +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 +.IP [1] +A tcl based language for the semantic markup of a table of +contents. Markup is represented by Tcl commands. +.IP [2] +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. +.IP [3] +An API describing the interface between the package above and a +plugin. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. +.PP +.IP [1] +A \fIwriter\fR of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +\fIdoctoc language introduction\fR first. Having digested this +the formal \fIdoctoc language syntax\fR specification should +become understandable. A writer experienced with doctoc may only +need the \fIdoctoc language command reference\fR from time to +time to refresh her memory. +.sp +While a document is written the \fBdtp\fR 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 \fBdtplite\fR application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them. +.IP [2] +A \fIprocessor\fR of documentation written in the \fIdoctoc\fR +markup language has to know which tools are available for use. +.sp +The main tool is the aforementioned \fBdtp\fR application provided +by Tcllib. The simpler \fBdtplite\fR does not expose doctoc to the +user. +At the bottom level, common to both applications, however sits the +package \fBdoctoools::toc\fR, providing the basic facilities to +read and process files containing text in the doctoc format. +.IP [3] +At last, but not least, \fIplugin writers\fR have to understand the +interaction between the \fBdoctools::toc\fR package and its +plugins, as described in the \fIdoctoc plugin API reference\fR. +.PP +.SH "RELATED FORMATS" +doctoc does not stand alone, it has two companion formats. These are +called \fIdocidx\fR and \fIdoctools\fR, and they are for the markup +of \fIkeyword indices\fR, and general documentation, respectively. +They are described in their own sets of documents, starting at the +\fIdocidx introduction\fR and the \fIdoctools introduction\fR, +respectively. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax, doctoc_plugin_apiref, doctools::toc, doctools_intro +.SH KEYWORDS +markup, semantic markup, table of contents, toc +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_lang_cmdref.n Index: embedded/man/files/modules/doctools/doctoc_lang_cmdref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_lang_cmdref.n @@ -0,0 +1,369 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_lang_cmdref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_lang_cmdref" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_lang_cmdref \- doctoc language command reference +.SH SYNOPSIS +\fBcomment\fR \fIplaintext\fR +.sp +\fBdivision_end\fR +.sp +\fBdivision_start\fR \fItext\fR ?\fIsymfile\fR? +.sp +\fBinclude\fR \fIfilename\fR +.sp +\fBitem\fR \fIfile\fR \fItext\fR \fIdesc\fR +.sp +\fBlb\fR +.sp +\fBrb\fR +.sp +\fBtoc_begin\fR \fItext\fR \fItitle\fR +.sp +\fBtoc_end\fR +.sp +\fBvset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBvset\fR \fIvarname\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fIdoctoc language introduction\fR first. +.SH COMMANDS +.TP +\fBcomment\fR \fIplaintext\fR +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. +.TP +\fBdivision_end\fR +Toc structure. This command closes the division opened by the last +\fBdivision_begin\fR command coming before it, and not yet closed. +.TP +\fBdivision_start\fR \fItext\fR ?\fIsymfile\fR? +Toc structure. This command opens a division in the table of +contents. Its counterpart is \fBdivision_end\fR. Together they allow a +user to give a table of contents additional structure. +.sp +The title of the new division is provided by the argument \fItext\fR. +.sp +If the symbolic filename \fIsymfile\fR is present then the section +title should link to the referenced document, if links are supported +by the output format. +.TP +\fBinclude\fR \fIfilename\fR +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. +.TP +\fBitem\fR \fIfile\fR \fItext\fR \fIdesc\fR +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 \fIfile\fR. The \fItext\fR +argument is used to label the reference, whereas the \fIdesc\fR +provides a short descriptive text of that document. +.sp +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. +.TP +\fBlb\fR +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. +.TP +\fBrb\fR +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. +.TP +\fBtoc_begin\fR \fItext\fR \fItitle\fR +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 (\fItext\fR) and the overall title text for the index +(\fItitle\fR), without markup. +.sp +The label often is the name of the package (or extension) the +documents belong to. +.TP +\fBtoc_end\fR +Document structure. Command to end a table of contents. Anything in +the document coming after this command is in error. +.TP +\fBvset\fR \fIvarname\fR \fIvalue\fR +Templating. In this form the command sets the named document variable +to the specified \fIvalue\fR. It does not generate output. I.e. the +command is replaced by the empty string. +.TP +\fBvset\fR \fIvarname\fR +Templating. In this form the command is replaced by the value of the +named document variable +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctoc_intro, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax +.SH KEYWORDS +doctoc commands, doctoc language, doctoc markup, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_lang_faq.n Index: embedded/man/files/modules/doctools/doctoc_lang_faq.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_lang_faq.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_lang_faq.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_lang_faq" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_lang_faq \- doctoc language faq +.SH DESCRIPTION +.PP +.SH OVERVIEW +.SS "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. +.PP +Please report any questions (and, if possible, answers) we should +consider for this document in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +.SH EXAMPLES +.SS "WHERE DO I FIND DOCTOC EXAMPLES?" +We have no direct examples of documents written using doctoc +markup. However the doctools processor \fBdtplite\fR 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. +.PP +\fBdtplite\fR is distributed as part of Tcllib, so to get it you +need one of +.IP [1] +A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +\fIhttp://sourceforge.net/cvs/?group_id=12883\fR +.IP [2] +A Tcllib release archive. They are available at +\fIhttp://sourceforge.net/project/showfiles.php?group_id=12883\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report any such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +the package and/or the documentation. +.SH "SEE ALSO" +doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syntax +.SH KEYWORDS +doctoc commands, doctoc language, doctoc markup, doctoc syntax, examples, faq, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_lang_intro.n Index: embedded/man/files/modules/doctools/doctoc_lang_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_lang_intro.n @@ -0,0 +1,505 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_lang_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_lang_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_lang_intro \- doctoc language introduction +.SH DESCRIPTION +.PP +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 \fIdoctoc language syntax\fR specification +and the \fIdoctoc language command reference\fR. +.SS FUNDAMENTALS +While the \fIdoctoc markup language\fR is quite similar to the +\fIdoctools markup language\fR, 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. +.PP +Each markup command is a Tcl command surrounded by a matching pair of +\fB[\fR and \fB]\fR. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. +.PP +.CS + + + ... [division_start {Appendix 1}] ... + +.CE +.CS + + + ... [item thefile \\\\ + label {file description}] ... + +.CE +.SS "BASIC STRUCTURE" +The most simple document which can be written in doctoc is +.CS + + + [toc_begin GROUPTITLE TITLE] + [toc_end] + +.CE +This also shows us that all doctoc documents consist of only one +part where we will list \fIitems\fR and \fIdivisions\fR. +.PP +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. +.PP +We will discuss the commands for each of these two possibilities in +the next sections. +.SS ITEMS +Use the command \fBitem\fR to put an \fIitem\fR 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. +.PP +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. +.PP +Here a made up example for a table of contents of this document: +.CS + + +[toc_begin Doctoc {Language Introduction}] +[\fBitem 1 DESCRIPTION\fR] +[\fBitem 1.1 {Basic structure}\fR] +[\fBitem 1.2 Items\fR] +[\fBitem 1.3 Divisions\fR] +[\fBitem 2 {FURTHER READING}\fR] +[toc_end] + +.CE +.SS 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. +.PP +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. +.PP +Of course, instead of the nested items we can again use divisions and +thus nest arbitrarily deep. +.PP +A division is marked by two commands instead of one, one to start it, +the other to close the last opened division. They are: +.TP +\fBdivision_start\fR +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. +.TP +\fBdivision_end\fR +This command closes the last opened and not yet closed division. +.PP +.PP +Using this we can recast the last example like this +.CS + + +[toc_begin Doctoc {Language Introduction}] +[\fBdivision_start DESCRIPTION\fR] +[item 1 {Basic structure}] +[item 2 Items] +[item 3 Divisions] +[\fBdivision_end\fR] +[\fBdivision_start {FURTHER READING}\fR] +[\fBdivision_end\fR] +[toc_end] + +.CE +.PP +Or, to demonstrate deeper nesting +.CS + + +[toc_begin Doctoc {Language Introduction}] +[\fBdivision_start DESCRIPTION\fR] +[\fBdivision_start {Basic structure}\fR] +[item 1 Do] +[item 2 Re] +[\fBdivision_end\fR] +[\fBdivision_start Items\fR] +[item a Fi] +[item b Fo] +[item c Fa] +[\fBdivision_end\fR] +[\fBdivision_start Divisions\fR] +[item 1 Sub] +[item 1 Zero] +[\fBdivision_end\fR] +[\fBdivision_end\fR] +[\fBdivision_start {FURTHER READING}\fR] +[\fBdivision_end\fR] +[toc_end] + +.CE +And do not forget, it is possible to freely mix items and divisions, +and to have empty divisions. +.CS + + +[toc_begin Doctoc {Language Introduction}] +[item 1 Do] +[\fBdivision_start DESCRIPTION\fR] +[\fBdivision_start {Basic structure}\fR] +[item 2 Re] +[\fBdivision_end\fR] +[item a Fi] +[\fBdivision_start Items\fR] +[item b Fo] +[item c Fa] +[\fBdivision_end\fR] +[\fBdivision_start Divisions\fR] +[\fBdivision_end\fR] +[\fBdivision_end\fR] +[\fBdivision_start {FURTHER READING}\fR] +[\fBdivision_end\fR] +[toc_end] + +.CE +.SS "ADVANCED STRUCTURE" +In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the \fBtoc_begin\fR command opening the +document. +.PP +Instead of only whitespace the two templating commands \fBinclude\fR +and \fBvset\fR 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 +.CS + + +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +[toc_begin GROUPTITLE TITLE] +... +[toc_end] + +.CE +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. +.CS + + +[toc_begin GROUPTITLE TITLE] +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +... +[toc_end] + +.CE +The only restriction \fBinclude\fR 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 \fBtoc_begin\fR may contain only the templating +commands \fBvset\fR and \fBinclude\fR, a file included in a division +may contain only items or divisions commands, etc. +.SS 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 \fB[\fR and \fB]\fR. +These commands, \fBlb\fR and \fBrb\fR respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text. +.PP +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. +.CS + + + ... + These commands, [cmd lb] and [cmd lb] respectively, are required + because our use of [\fBlb\fR] and [\fBrb\fR] to bracket markup commands makes it + impossible to directly use [\fBlb\fR] and [\fBrb\fR] within the text. + ... + +.CE +.SH "FURTHER READING" +Now that this document has been digested the reader, assumed to be a +\fIwriter\fR of documentation should be fortified enough to be able +to understand the formal \fIdoctoc language syntax\fR +specification as well. From here on out the +\fIdoctoc language command reference\fR will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. +.PP +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +\fBdtp\fR. +.PP +On the other hand, doctoc is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple \fBdtplite\fR goes, creating a table of contents +for a set of documents behind the scenes, without the writer having to +do so on their own. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctoc_intro, doctoc_lang_cmdref, doctoc_lang_syntax +.SH KEYWORDS +doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_lang_syntax.n Index: embedded/man/files/modules/doctools/doctoc_lang_syntax.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_lang_syntax.n @@ -0,0 +1,326 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_lang_syntax.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_lang_syntax" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_lang_syntax \- doctoc language syntax +.SH DESCRIPTION +.PP +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 +\fIdoctoc language command reference\fR. +A beginner should read the much more informally written +\fIdoctoc language introduction\fR first before trying to +understand either this document or the command reference. +.SH FUNDAMENTALS +In the broadest terms possible the \fIdoctoc markup language\fR 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. +.PP +Each markup command is a just Tcl command surrounded by a matching +pair of \fB[\fR and \fB]\fR. Which commands are available, +and their arguments, i.e. syntax is specified in the +\fIdoctoc language command reference\fR. +.PP +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. +.SH "LEXICAL DEFINITIONS" +In the syntax rules listed in the next section +.IP [1] + stands for all text except markup commands. +.IP [2] +Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of \fB[\fR and \fB]\fR. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. +.IP [3] + stands for all text consisting only of spaces, newlines, +tabulators and the \fBcomment\fR markup command. +.PP +.SH SYNTAX +The rules listed here specify only the syntax of doctoc documents. The +lexical level of the language was covered in the previous section. +.PP +Regarding the syntax of the (E)BNF itself +.IP [1] +The construct { X } stands for zero or more occurrences of X. +.IP [2] +The construct [ X ] stands for zero or one occurrence of X. +.PP +The syntax: +.CS + + +toc = defs + TOC_BEGIN + contents + TOC_END + { } + +defs = { INCLUDE | VSET | } +contents = { defs entry } [ defs ] + +entry = ITEM | division + +division = DIVISION_START + contents + DIVISION_END + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro +.SH KEYWORDS +doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctoc_plugin_apiref.n Index: embedded/man/files/modules/doctools/doctoc_plugin_apiref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctoc_plugin_apiref.n @@ -0,0 +1,616 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctoc_plugin_apiref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctoc_plugin_apiref" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctoc_plugin_apiref \- doctoc plugin API reference +.SH SYNOPSIS +\fBdt_fmap\fR \fIsymfname\fR +.sp +\fBdt_format\fR +.sp +\fBdt_read\fR \fIfile\fR +.sp +\fBdt_source\fR \fIfile\fR +.sp +\fBex_cappend\fR \fItext\fR +.sp +\fBex_cget\fR \fIvarname\fR +.sp +\fBex_cis\fR \fIcname\fR +.sp +\fBex_cname\fR +.sp +\fBex_cpop\fR \fIcname\fR +.sp +\fBex_cpush\fR \fIcname\fR +.sp +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBex_lb\fR ?\fInewbracket\fR? +.sp +\fBex_rb\fR ?\fInewbracket\fR? +.sp +\fBtoc_initialize\fR +.sp +\fBtoc_listvariables\fR +.sp +\fBtoc_numpasses\fR +.sp +\fBtoc_postprocess\fR \fItext\fR +.sp +\fBtoc_setup\fR \fIn\fR +.sp +\fBtoc_shutdown\fR +.sp +\fBtoc_varset\fR \fIvarname\fR \fItext\fR +.sp +\fBfmt_plain_text\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +This document is intended for \fIplugin writers\fR, i.e. developers +wishing to write a toc \fIformatting engine\fR for some output +format X. +.PP +It specifies the interaction between the \fBdoctools::toc\fR +package and its plugins, i.e. the interface any toc formatting engine +has to comply with. +.PP +This document deals with version 1 of the interface. +.PP +A reader who is on the other hand more interested in the markup +language itself should start with the +\fIdoctoc language introduction\fR and proceed from there to the +formal specifications, i.e. the \fIdoctoc language syntax\fR and +the \fIdoctoc language command reference\fR. +.SH OVERVIEW +The API for a toc formatting engine consists of two major sections. +.PP +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 +\fBFRONTEND COMMANDS\fR for their detailed specification. +.PP +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 \fBPLUGIN COMMANDS\fR and its subsections for +their detailed specification. +.SH "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. +.PP +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 \fBPLUGIN COMMANDS\fR) are executed. +.PP +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. +.PP +Coming back to the imported commands, all the commands with prefix +\fIdt_\fR provide limited access to specific parts of the frontend, +whereas the commands with prefix \fIex_\fR provide access to the +state of the \fBtextutil::expander\fR object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. +.PP +.TP +\fBdt_fmap\fR \fIsymfname\fR +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename \fIsymfname\fR. It will return the +unchanged input if no mapping was established for \fIsymfname\fR. +.sp +The required mappings are established with the method \fBmap\fR of +a frontend, as explained in section \fBOBJECT METHODS\fR +of the documentation for the package \fBdoctools::toc\fR. +.TP +\fBdt_format\fR +Query command. It returns the name of the format associated with the +toc formatting engine. +.TP +\fBdt_read\fR \fIfile\fR +Controlled filesystem access. Returns contents of \fIfile\fR 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. +.TP +\fBdt_source\fR \fIfile\fR +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. +.TP +\fBex_cappend\fR \fItext\fR +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. +.TP +\fBex_cget\fR \fIvarname\fR +Retrieves the value of variable \fIvarname\fR, defined in the current +context. +.TP +\fBex_cis\fR \fIcname\fR +Determines whether or not the name of the current context is +\fIcname\fR. +.TP +\fBex_cname\fR +Returns the name of the current context. +.TP +\fBex_cpop\fR \fIcname\fR +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named \fIcname\fR, or an +error results. +.TP +\fBex_cpush\fR \fIcname\fR +Pushes a context named \fIcname\fR onto the context stack. The +context must be popped by \fBcpop\fR before expansion ends or an +error results. +.TP +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +Sets variable \fIvarname\fR to \fIvalue\fR in the current context. +.TP +\fBex_lb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the new +bracket, and is returned. +.TP +\fBex_rb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the +new bracket, and is returned. +.PP +.SH "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. +.SS "MANAGEMENT COMMANDS" +The management commands a plugin has to provide are used by the +frontend to +.IP [1] +initialize and shutdown the plugin +.IP [2] +determine the number of passes it has +to make over the input +.IP [3] +initialize and shutdown each pass +.IP [4] +query and initialize engine parameters +.PP +.PP +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: +.CS + + + 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 + ... + +.CE +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. +.PP +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 \fBtoc_varset\fR. +.PP +In each of the passes, i.e. after the calls of \fBtoc_setup\fR 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 \fIdoctoc language syntax\fR specification. +.PP +A different way of looking at the sequence is: +.IP \(bu +First some basic parameters are determined. +.IP \(bu +Then everything starting at the first \fBtoc_varset\fR to +\fBtoc_shutdown\fR forms a \fIrun\fR, the formatting of a +single input. Each run can be followed by more. +.IP \(bu +Embedded within each run we have one or more \fIpasses\fR, +each starting with \fBtoc_setup\fR and going until either the next +\fBtoc_setup\fR or \fBtoc_postprocess\fR is reached. +.sp +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. +.PP +.PP +The commands, their names, signatures, and responsibilities are, in +detail: +.TP +\fBtoc_initialize\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBtoc_listvariables\fR +\fIInitialization/Shutdown\fR and \fIEngine parameters\fR. +Second command is called after the plugin code has been loaded, +i.e. immediately after \fBtoc_numpasses\fR. +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. +.TP +\fBtoc_numpasses\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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. +.TP +\fBtoc_postprocess\fR \fItext\fR +\fIInitialization/Shutdown\fR. +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. +.sp +Expected to return a value, the final result of formatting the input. +.TP +\fBtoc_setup\fR \fIn\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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 \fB1\fR 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. +.TP +\fBtoc_shutdown\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBtoc_varset\fR \fIvarname\fR \fItext\fR +\fIEngine parameters\fR. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by \fIvarname\fR, the value to +set in \fItext\fR. +.sp +The command has to throw an error if an unknown \fIvarname\fR is +used. Only the names returned by \fBtoc_listvariables\fR have to be +considered as known. +.sp +The values of all engine parameters have to persist between passes and +runs. +.PP +.SS "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 \fBlb\fR, \fBrb\fR, \fBvset\fR, \fBinclude\fR, and +\fBcomment\fR. 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. +.PP +This means, that each of the five markup commands specified in the +\fIdoctoc language command reference\fR 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 \fIfmt_\fR added to it. +.PP +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. +.PP +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +\fIdoctoc language command reference\fR for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. +.PP +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 \fIdoctoc language syntax\fR +specification. +.PP +.TP +\fBfmt_plain_text\fR \fItext\fR +\fINo associated markup command\fR. +.sp +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. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax, doctools::toc +.SH KEYWORDS +formatting engine, markup, plugin, semantic markup, table of contents, toc, toc formatter +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools.n Index: embedded/man/files/modules/doctools/doctools.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools.n @@ -0,0 +1,675 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2013 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools" n 1.4.14 tcllib "Documentation tools" +.BS +.SH NAME +doctools \- doctools - Processing documents +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBdoctools ?1.4.14?\fR +.sp +\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR...? +.sp +\fB::doctools::help\fR +.sp +\fB::doctools::search\fR \fIpath\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBconfigure\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +.sp +\fIobjectName\fR \fBcget\fR \fB-option\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBformat\fR \fItext\fR +.sp +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +.sp +\fIobjectName\fR \fBparameters\fR +.sp +\fIobjectName\fR \fBsearch\fR \fIpath\fR +.sp +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +.sp +\fIobjectName\fR \fBwarnings\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for the creation of objects able to +process and convert text written in the \fIdoctools\fR markup +language into any output format X for which a +\fIformatting engine\fR is available. +.PP +A reader interested in the markup language itself should start with +the \fIdoctools language introduction\fR and proceed from there to +the formal specifications, i.e. the \fIdoctools language syntax\fR +and the \fIdoctools language command reference\fR. +.PP +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a \fIplugin writer\fR then reading +and understanding the \fIdoctools plugin API reference\fR is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. +.SH "PUBLIC API" +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR...? +This command creates a new doctools object with an associated Tcl +command whose name is \fIobjectName\fR. This \fIobject\fR command is +explained in full detail in the sections \fBOBJECT COMMAND\fR +and \fBOBJECT METHODS\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.sp +The options and their values coming after the name of the object are +used to set the initial configuration of the object. +.TP +\fB::doctools::help\fR +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. +.TP +\fB::doctools::search\fR \fIpath\fR +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 \fBFORMAT MAPPING\fR for more explanations. +.sp +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 \fIpath\fR to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the \fIpath\fR added +last is later searched through first. +.sp +An error will be thrown if the \fIpath\fR either does not exist, is +not a directory, or is not readable. +.PP +.SS "OBJECT COMMAND" +All commands created by \fB::doctools::new\fR have the following +general form and may be used to invoke various operations on their +doctools converter object. +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the exact +behavior of the command. See section \fBOBJECT METHODS\fR for +the detailed specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBconfigure\fR +The method returns a list of all known options and their current +values when called without any arguments. +.TP +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +The method behaves like the method \fBcget\fR when called with a +single argument and returns the value of the option specified by said +argument. +.TP +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +The method reconfigures the specified \fBoption\fRs of the object, +setting them to the associated \fIvalue\fRs, when called with an even +number of arguments, at least two. +.sp +The legal options are described in the section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBcget\fR \fB-option\fR +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. +.sp +The legal configuration options are described in section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBformat\fR \fItext\fR +This method runs the \fItext\fR through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no \fB-format\fR was configured for the object. +.sp +The method assumes that the \fItext\fR is in \fIdoctools\fR format as +specified in the companion document \fIdoctools_fmt\fR. Errors will +be thrown otherwise. +.TP +\fIobjectName\fR \fBmap\fR \fIsymbolic\fR \fIactual\fR +This methods add one entry to the per-object mapping from +\fIsymbolic\fR filenames to the \fIactual\fR uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command \fBdt_fmap\fR. +This command is described in more detail in the +\fIdoctools plugin API reference\fR which specifies the interaction +between the objects created by this package and doctools formatting +engines. +.TP +\fIobjectName\fR \fBparameters\fR +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. +.TP +\fIobjectName\fR \fBsearch\fR \fIpath\fR +This method extends the per-object list of paths searched for doctools +formatting engines. See also the command \fB::doctools::search\fR 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 \fBFORMAT MAPPING\fR. +.TP +\fIobjectName\fR \fBsetparam\fR \fIname\fR \fIvalue\fR +This method sets the \fIname\fRd engine parameter to the specified +\fIvalue\fR. +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 \fIname\fR. +The list of parameters provided by the configured formatting engine +can be retrieved through the method \fBparameters\fR. +.TP +\fIobjectName\fR \fBwarnings\fR +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method \fBformat\fR. +.PP +.SS "OBJECT CONFIGURATION" +All doctools objects understand the following configuration options: +.TP +\fB-file\fR \fIfile\fR +The argument of this option is stored in the object and made available +to the configured formatting engine through the commands \fBdt_file\fR +and \fBdt_mainfile\fR. +These commands are described in more detail in the companion document +\fIdoctools_api\fR which specifies the API between the object and +formatting engines. +.sp +The default value of this option is the empty string. +.sp +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. +.TP +\fB-ibase\fR \fIfile\fR +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 \fB-file\fR is used instead. +.sp +Note that \fB-file\fR and \fB-ibase\fR, while similar looking, +are actually very different. The value of \fB-file\fR is used by +some engines for the generation of proper relative references between +output documents (HTML). As such this is a \fIdestination\fR +path. The \fB-ibase\fR on the other hand is used to resolve +relative include paths, and as such deals with \fIsource\fR paths. +.sp +The default value of this option is the empty string. +.TP +\fB-module\fR \fItext\fR +The argument of this option is stored in the object and made available +to the configured formatting engine through the command \fBdt_module\fR. +This command is described in more detail in the companion document +\fIdoctools_api\fR which specifies the API between the object and +formatting engines. +.sp +The default value of this option is the empty string. +.sp +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. +.TP +\fB-format\fR \fItext\fR +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method \fBformat\fR. Its default value is the empty string. The +method \fBformat\fR cannot be used if this option is not set to a +valid value at least once. +.sp +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. +.sp +The section \fBFORMAT MAPPING\fR explains in detail how the +package and object will look for engine implementations. +.TP +\fB-deprecated\fR \fIboolean\fR +This option is a boolean flag. The object will generate warnings if +this flag is set and the text given to method \fBformat\fR contains +the deprecated markup command \fBstrong\fR. +Its default value is \fBFALSE\fR. In other words, no warnings will +be generated. +.TP +\fB-copyright\fR \fItext\fR +The argument of this option is stored in the object and made available +to the configured formatting engine through the command \fBdt_copyright\fR. +This command is described in more detail in the companion document +\fIdoctools_api\fR which specifies the API between the object and +formatting engines. +.sp +The default value of this option is the empty string. +.sp +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. +.sp +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 \fBcopyright\fR. This command is +described in more detail in the companion document \fIdoctools_fmt\fR +which specifies the \fIdoctools\fR format itself. +.PP +.SS "FORMAT MAPPING" +The package and object will perform the following algorithm when +trying to map a format name \fIfoo\fR to a file containing an +implementation of a formatting engine for \fIfoo\fR: +.IP [1] +If \fIfoo\fR is the name of an existing file then this file is +directly taken as the implementation. +.IP [2] +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "\fIfmt.\fIfoo\fR\fR". If yes, then that file is taken as the +implementation. +.sp +Note that this list of paths is initially empty and can be extended +through the object method \fBsearch\fR. +.IP [3] +If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "\fIfmt.\fIfoo\fR\fR". If yes, then that file is taken +as the implementation. +.sp +This list of paths can be extended +through the command \fB::doctools::search\fR. +It contains initially one path, the subdirectory "\fImpformats\fR" of +the directory the package itself is located in. +In other words, if the package implementation "\fIdoctools.tcl\fR" is +installed in the directory "\fI/usr/local/lib/tcllib/doctools\fR" then +it will by default search the +directory "\fI/usr/local/lib/tcllib/doctools/mpformats\fR" for format +implementations. +.IP [4] +The mapping fails. +.PP +.SH "PREDEFINED ENGINES" +The package provides predefined engines for the following +formats. Some of the engines support parameters. These will be +explained below as well. +.TP +html +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports four parameters: +.RS +.TP +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 \fB\fR tag, closing the body of the generated +HTML. +.sp +This can be used to insert boilerplate footer markup into the +generated document. +.TP +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 \fB\fR tag, starting the body of the generated HTML. +.sp +This can be used to insert boilerplate header markup into the +generated document. +.TP +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 \fB\fR tag, starting the header section of the +generated HTML. +.sp +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. +.TP +xref +The value for this parameter has to be a list of triples specifying +cross-reference information. This information is used by the engine to +create more hyperlinks. Each triple is a list containing a pattern, +symbolic filename and fragment reference, in this order. If a pattern +is specified multiple times the last occurence of the pattern will be +used. +.sp +The engine will consult the xref database when encountering specific +commands and will create a link if the relevant text matches one of +the patterns. No link will be created if no match was found. The link +will go to the uri \fBfile#fragment\fR listed in the relevant +triple, after conversion of the symbolic file name to the actual uri +via \fBdt_fmap\fR (see the \fIdoctools plugin API reference\fR). +This file-to-uri mapping was build by calls to the method \fBmap\fR +of the doctools object (See section \fBOBJECT METHODS\fR). +.sp +The following formatting commands will consult the xref database: +.RS +.TP +\fBcmd\fR \fIword\fR +The command will look for the patterns \fBsa,\fR\fIword\fR, and +\fIword\fR, in this order. If this fails if it will convert \fIword\fR +to all lowercase and try again. +.TP +\fBsyscmd\fR \fIword\fR +The command will look for the patterns \fBsa,\fR\fIword\fR, and +\fIword\fR, in this order. If this fails if it will convert \fIword\fR +to all lowercase and try again. +.TP +\fBterm\fR \fIword\fR +The command will look for the patterns \fBkw,\fR\fIword\fR, +\fBsa,\fR\fIword\fR, and \fIword\fR, in this order. If this fails if +it will convert \fIword\fR to all lowercase and try again. +.TP +\fBpackage\fR \fIword\fR +The command will look for the patterns \fBsa,\fR\fIword\fR, +\fBkw,\fR\fIword\fR, and \fIword\fR, in this order. If this fails if +it will convert \fIword\fR to all lowercase and try again. +.TP +\fBsee_also\fR \fIword\fR... +The command will look for the patterns \fBsa,\fR\fIword\fR, and +\fIword\fR, in this order, for each \fIword\fR given to the +command. If this fails if it will convert \fIword\fR to all lowercase +and try again. +.TP +\fBkeywords\fR \fIword\fR... +The command will look for the patterns \fBkw,\fR\fIword\fR, and +\fIword\fR, in this order, for each \fIword\fR given to the +command. If this fails if it will convert \fIword\fR to all lowercase +and try again. +.RE +.RE +.sp +.TP +latex +This engine generates output suitable for the \fBlatex\fR text +processor coming out of the TeX world. +.TP +list +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. +.TP +nroff +This engine generates nroff output, for processing by \fBnroff\fR, +or \fBgroff\fR. The result will be standard man pages as they are +known in the unix world. +.TP +null +This engine generates no outout at all. This can be used if one just +wants to validate some input. +.TP +tmml +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. +.TP +wiki +This engine generates Wiki markup as understood by Jean Claude +Wippler's \fBwikit\fR application. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref +.SH KEYWORDS +HTML, TMML, conversion, documentation, manpage, markup, nroff +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2013 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_intro.n Index: embedded/man/files/modules/doctools/doctools_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_intro.n @@ -0,0 +1,317 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools_intro \- doctools introduction +.SH DESCRIPTION +.PP +\fIdoctools\fR (short for \fIdocumentation tools\fR) stands for +a set of related, yet different, entities which are working together +for the easy creation and transformation of documentation. These are +.IP [1] +A tcl based language for the semantic markup of text. Markup is +represented by Tcl commands interspersed with the actual text. +.IP [2] +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. +.IP [3] +An API describing the interface between the package above and a +plugin. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. +.PP +.IP [1] +A \fIwriter\fR of documentation has to understand the markup language +itself. A beginner to doctools should read the more informally written +\fIdoctools language introduction\fR first. Having digested this +the formal \fIdoctools language syntax\fR specification should +become understandable. A writer experienced with doctools may only +need the \fIdoctools language command reference\fR from time to +time to refresh her memory. +.sp +While a document is written the \fBdtplite\fR 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. +.IP [2] +A \fIprocessor\fR of documentation written in the \fIdoctools\fR +markup language has to know which tools are available for use. +.sp +The main tool is the aforementioned \fBdtplite\fR application +provided by Tcllib. A more powerful one (in terms of options and +ability to configure it) is the \fBdtp\fR application, provided by +Tclapps. +At the bottom level, common to both applications, however sits the +package \fBdoctools\fR, providing the basic facilities to read and +process files containing text in the doctools format. +.IP [3] +At last, but not least, \fIplugin writers\fR have to understand the +interaction between the \fBdoctools\fR package and its plugins, as +described in the \fIdoctools plugin API reference\fR. +.PP +.SH "RELATED FORMATS" +doctools does not stand alone, it has two companion formats. These are +called \fIdocidx\fR and \fIdoctoc\fR, and they are for the markup of +\fIkeyword indices\fR, and \fItables of contents\fR, +respectively. +They are described in their own sets of documents, starting at the +\fIdocidx introduction\fR and the \fIdoctoc introduction\fR, +respectively. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +docidx_intro, doctoc_intro, doctools, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref +.SH KEYWORDS +markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_lang_cmdref.n Index: embedded/man/files/modules/doctools/doctools_lang_cmdref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_lang_cmdref.n @@ -0,0 +1,782 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_lang_cmdref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2010 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_lang_cmdref" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools_lang_cmdref \- doctools language command reference +.SH SYNOPSIS +\fBarg\fR \fItext\fR +.sp +\fBarg_def\fR \fItype\fR \fIname\fR ?\fImode\fR? +.sp +\fBbullet\fR +.sp +\fBcall\fR \fIargs\fR +.sp +\fBcategory\fR \fItext\fR +.sp +\fBclass\fR \fItext\fR +.sp +\fBcmd\fR \fItext\fR +.sp +\fBcmd_def\fR \fIcommand\fR +.sp +\fBcomment\fR \fIplaintext\fR +.sp +\fBconst\fR \fItext\fR +.sp +\fBcopyright\fR \fItext\fR +.sp +\fBdef\fR \fItext\fR +.sp +\fBdescription\fR +.sp +\fBenum\fR +.sp +\fBemph\fR \fItext\fR +.sp +\fBexample\fR \fItext\fR +.sp +\fBexample_begin\fR +.sp +\fBexample_end\fR +.sp +\fBfile\fR \fItext\fR +.sp +\fBfun\fR \fItext\fR +.sp +\fBimage\fR \fIname\fR ?\fIlabel\fR? +.sp +\fBinclude\fR \fIfilename\fR +.sp +\fBitem\fR +.sp +\fBkeywords\fR \fIargs\fR +.sp +\fBlb\fR +.sp +\fBlist_begin\fR \fIwhat\fR +.sp +\fBlist_end\fR +.sp +\fBlst_item\fR \fItext\fR +.sp +\fBmanpage_begin\fR \fIcommand\fR \fIsection\fR \fIversion\fR +.sp +\fBmanpage_end\fR +.sp +\fBmethod\fR \fItext\fR +.sp +\fBmoddesc\fR \fItext\fR +.sp +\fBnamespace\fR \fItext\fR +.sp +\fBnl\fR +.sp +\fBopt\fR \fItext\fR +.sp +\fBopt_def\fR \fIname\fR ?\fIarg\fR? +.sp +\fBoption\fR \fItext\fR +.sp +\fBpackage\fR \fItext\fR +.sp +\fBpara\fR +.sp +\fBrb\fR +.sp +\fBrequire\fR \fIpackage\fR ?\fIversion\fR? +.sp +\fBsection\fR \fIname\fR +.sp +\fBsectref\fR \fIid\fR ?\fItext\fR? +.sp +\fBsectref-external\fR \fItext\fR +.sp +\fBsee_also\fR \fIargs\fR +.sp +\fBstrong\fR \fItext\fR +.sp +\fBsubsection\fR \fIname\fR +.sp +\fBsyscmd\fR \fItext\fR +.sp +\fBterm\fR \fItext\fR +.sp +\fBtitledesc\fR \fIdesc\fR +.sp +\fBtkoption_def\fR \fIname\fR \fIdbname\fR \fIdbclass\fR +.sp +\fBtype\fR \fItext\fR +.sp +\fBuri\fR \fItext\fR ?\fItext\fR? +.sp +\fBusage\fR \fIargs\fR +.sp +\fBvar\fR \fItext\fR +.sp +\fBvset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBvset\fR \fIvarname\fR +.sp +\fBwidget\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fIdoctools language introduction\fR first. +.SH COMMANDS +.TP +\fBarg\fR \fItext\fR +Text markup. The argument text is marked up as the \fIargument\fR of +a command. Main uses are the highlighting of command arguments in +free-form text, and for the argument parameters of the markup commands +\fBcall\fR and \fBusage\fR. +.TP +\fBarg_def\fR \fItype\fR \fIname\fR ?\fImode\fR? +Text structure. List element. Argument list. Automatically closes the +previous list element. Specifies the data-\fItype\fR of the described +argument of a command, its \fIname\fR and its i/o-\fImode\fR. The +latter is optional. +.TP +\fBbullet\fR +\fIDeprecated\fR. Text structure. List element. Itemized list. See +\fBitem\fR for the canonical command to open a list item in an +itemized list. +.TP +\fBcall\fR \fIargs\fR +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 \fBarg\fR, +\fBmethod\fR, \fBoption\fR etc., as is appropriate, and that the +command itself is marked up with \fBcmd\fR. +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. +.TP +\fBcategory\fR \fItext\fR +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. +.TP +\fBclass\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIclass\fR. The text may have other markup already applied to +it. Main use is the highlighting of class names in free-form text. +.TP +\fBcmd\fR \fItext\fR +Text markup. The argument text is marked up as the name of a +\fITcl command\fR. 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 \fBcall\fR and +\fBusage\fR. +.TP +\fBcmd_def\fR \fIcommand\fR +Text structure. List element. Command list. Automatically closes the +previous list element. The argument specifies the name of the +\fITcl command\fR to be described by the list element. Expected to +be marked up in the output as if it had been formatted with \fBcmd\fR. +.TP +\fBcomment\fR \fIplaintext\fR +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. +.TP +\fBconst\fR \fItext\fR +Text markup. The argument is marked up as a \fIconstant\fR value. The +text may have other markup already applied to it. Main use is the +highlighting of constants in free-form text. +.TP +\fBcopyright\fR \fItext\fR +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. +.TP +\fBdef\fR \fItext\fR +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. +.TP +\fBdescription\fR +Document structure. This command separates the header from the +document body. Implicitly starts a section named "DESCRIPTION" (See +command \fBsection\fR). +.TP +\fBenum\fR +Text structure. List element. Enumerated list. Automatically closes +the previous list element. +.TP +\fBemph\fR \fItext\fR +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. +.TP +\fBexample\fR \fItext\fR +Text structure, Text markup. This command marks its argument up as an +\fIexample\fR. Main use is the simple embedding of examples in +free-form text. It should be used if the example does \fInot\fR need +special markup of its own. Otherwise use a sequence of +\fBexample_begin\fR ... \fBexample_end\fR. +.TP +\fBexample_begin\fR +Text structure. This commands starts an example. All text until the +next \fBexample_end\fR belongs to the example. Line breaks, spaces, +and tabs have to be preserved literally. Examples cannot be nested. +.TP +\fBexample_end\fR +Text structure. This command closes the example started by the last +\fBexample_begin\fR. +.TP +\fBfile\fR \fItext\fR +Text markup. The argument is marked up as a \fIfile\fR or +\fIdirectory\fR, i.e. in general a \fIpath\fR. The text may have +other markup already applied to it. Main use is the highlighting of +paths in free-form text. +.TP +\fBfun\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIfunction\fR. The text may have other markup already applied to +it. Main use is the highlighting of function names in free-form text. +.TP +\fBimage\fR \fIname\fR ?\fIlabel\fR? +Text markup. The argument is the symbolic name of an \fIimage\fR +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 \fIalt\fR +attribute of image references. +.TP +\fBinclude\fR \fIfilename\fR +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. +.TP +\fBitem\fR +Text structure. List element. Itemized list. Automatically closes the +previous list element. +.TP +\fBkeywords\fR \fIargs\fR +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. +.TP +\fBlb\fR +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. +.TP +\fBlist_begin\fR \fIwhat\fR +Text structure. This command starts a list. The exact nature of the +list is determined by the argument \fIwhat\fR 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. +.sp +The allowed types (and their associated item commands) are: +.RS +.TP +\fBarguments\fR +\fBarg_def\fR. +.TP +\fBcommands\fR +\fBcmd_def\fR. +.TP +\fBdefinitions\fR +\fBdef\fR and \fBcall\fR. +.TP +\fBenumerated\fR +\fBenum\fR +.TP +\fBitemized\fR +\fBitem\fR +.TP +\fBoptions\fR +\fBopt_def\fR +.TP +\fBtkoptions\fR +\fBtkoption_def\fR +.RE +.sp +Additionally the following names are recognized as shortcuts for some +of the regular types: +.RS +.TP +\fBargs\fR +Short for \fBarguments\fR. +.TP +\fBcmds\fR +Short for \fBcommands\fR. +.TP +\fBenum\fR +Short for \fBenumerated\fR. +.TP +\fBitem\fR +Short for \fBitemized\fR. +.TP +\fBopts\fR +Short for \fBoptions\fR. +.RE +.sp +At last the following names are still recognized for backward +compatibility, but are otherwise considered to be \fIdeprecated\fR. +.RS +.TP +\fBarg\fR +\fIDeprecated\fR. See \fBarguments\fR. +.TP +\fBbullet\fR +\fIDeprecated\fR. See \fBitemized\fR. +.TP +\fBcmd\fR +\fIDeprecated\fR. See \fBcommands\fR. +.TP +\fBopt\fR +\fIDeprecated\fR. See \fBoptions\fR. +.TP +\fBtkoption\fR +\fIDeprecated\fR. See \fBtkoptions\fR. +.RE +.sp +.TP +\fBlist_end\fR +Text structure. This command closes the list opened by the last +\fBlist_begin\fR command coming before it. +.TP +\fBlst_item\fR \fItext\fR +\fIDeprecated\fR. Text structure. List element. Definition list. See +\fBdef\fR for the canonical command to open a general list item in a +definition list. +.TP +\fBmanpage_begin\fR \fIcommand\fR \fIsection\fR \fIversion\fR +Document structure. The command to start a manpage. The arguments are +the name of the \fIcommand\fR described by the manpage, the +\fIsection\fR of the manpages this manpage resides in, and the +\fIversion\fR of the module containing the command. All arguments have +to be plain text, without markup. +.TP +\fBmanpage_end\fR +Document structure. Command to end a manpage/document. Anything in the document +coming after this command is in error. +.TP +\fBmethod\fR \fItext\fR +Text markup. The argument text is marked up as the name of an +\fIobject\fR \fImethod\fR, 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 \fBcall\fR and \fBusage\fR. +.TP +\fBmoddesc\fR \fItext\fR +Document information. Header. Registers the plain text argument as a short +description of the module the manpage resides in. +.TP +\fBnamespace\fR \fItext\fR +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. +.TP +\fBnl\fR +\fIDeprecated\fR. Text structure. See \fBpara\fR for the canonical +command to insert paragraph breaks into the text. +.TP +\fBopt\fR \fItext\fR +Text markup. The argument text is marked up as \fIoptional\fR. The text may +have other markup already applied to it. Main use is the highlighting of +optional arguments, see the command arg \fBarg\fR. +.TP +\fBopt_def\fR \fIname\fR ?\fIarg\fR? +Text structure. List element. Option list. Automatically closes the +previous list element. Specifies \fIname\fR and arguments of the +\fIoption\fR described by the list element. It is expected that the +name is marked up using \fBoption\fR. +.TP +\fBoption\fR \fItext\fR +Text markup. The argument is marked up as \fIoption\fR. 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 \fBcall\fR and \fBusage\fR commands. +.TP +\fBpackage\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIpackage\fR. The text may have other markup already applied to +it. Main use is the highlighting of package names in free-form text. +.TP +\fBpara\fR +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. +.TP +\fBrb\fR +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. +.TP +\fBrequire\fR \fIpackage\fR ?\fIversion\fR? +Document information. Header. This command registers its argument +\fIpackage\fR 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 \fBopt\fR. +.TP +\fBsection\fR \fIname\fR +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. +.TP +\fBsectref\fR \fIid\fR ?\fItext\fR? +Text markup. Formats a reference to the section identified by \fIid\fR. +If no \fItext\fR is specified the title of the referenced section is +used in the output, otherwise \fItext\fR is used. +.TP +\fBsectref-external\fR \fItext\fR +Text markup. Like \fBsectref\fR, 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. +.TP +\fBsee_also\fR \fIargs\fR +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. +.TP +\fBstrong\fR \fItext\fR +\fIDeprecated\fR. Text markup. See \fBemph\fR for the canonical +command to emphasize text. +.TP +\fBsubsection\fR \fIname\fR +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. +.TP +\fBsyscmd\fR \fItext\fR +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. +.TP +\fBterm\fR \fItext\fR +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. +.TP +\fBtitledesc\fR \fIdesc\fR +Document information. Header. Optional. Registers the plain text +argument as the title of the manpage. Defaults to the value registered +by \fBmoddesc\fR. +.TP +\fBtkoption_def\fR \fIname\fR \fIdbname\fR \fIdbclass\fR +Text structure. List element. Widget option list. Automatically closes +the previous list element. Specifies the \fIname\fR of the option as +used in scripts, the name used by the option database (\fIdbname\fR), +and its class (\fIdbclass\fR), i.e. its type. It is expected that the +name is marked up using \fBoption\fR. +.TP +\fBtype\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIdata type\fR. The text may have other markup already applied to +it. Main use is the highlighting of data types in free-form text. +.TP +\fBuri\fR \fItext\fR ?\fItext\fR? +Text markup. The argument is marked up as an \fIuri\fR (i.e. a +\fIuniform resource identifier\fR. 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. +.TP +\fBusage\fR \fIargs\fR +Text markup. See \fBcall\fR for the full description, this command is +syntactically identical, as it is in its expectations for the markup +of its arguments. +In contrast to \fBcall\fR it is however not allowed to generate output +where this command occurs in the text. The command is \fIsilent\fR. +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. +.TP +\fBvar\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIvariable\fR. The text may have other markup already applied to +it. Main use is the highlighting of variables in free-form text. +.TP +\fBvset\fR \fIvarname\fR \fIvalue\fR +Templating. In this form the command sets the named document variable +to the specified \fIvalue\fR. It does not generate output. I.e. the +command is replaced by the empty string. +.TP +\fBvset\fR \fIvarname\fR +Templating. In this form the command is replaced by the value of the +named document variable +.TP +\fBwidget\fR \fItext\fR +Text markup. The argument is marked up as the name of a +\fIwidget\fR. The text may have other markup already applied to +it. Main use is the highlighting of widget names in free-form text. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctools_intro, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax +.SH KEYWORDS +doctools commands, doctools language, doctools markup, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2010 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_lang_faq.n Index: embedded/man/files/modules/doctools/doctools_lang_faq.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_lang_faq.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_lang_faq.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_lang_faq" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools_lang_faq \- doctools language faq +.SH DESCRIPTION +.PP +.SH OVERVIEW +.SS "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. +.PP +Please report any questions (and, if possible, answers) we should +consider for this document in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +.SH EXAMPLES +.SS "WHERE DO I FIND DOCTOOLS EXAMPLES?" +The most examples of doctools markup currently known can be found in +the Tcllib and Tklib package bundles where basically the documentation +of all packages is written in it. +In Tcllib you will also find the sources for the doctools +documentation themselves, which makes use of nearly all of the +available markup commands. +You need one of +.IP [1] +A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +\fIhttp://sourceforge.net/cvs/?group_id=12883\fR +.IP [2] +A Tcllib release archive. They are available at +\fIhttp://sourceforge.net/project/showfiles.php?group_id=12883\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report any such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +the package and/or the documentation. +.SH "SEE ALSO" +doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax +.SH KEYWORDS +doctools commands, doctools language, doctools markup, doctools syntax, examples, faq, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_lang_intro.n Index: embedded/man/files/modules/doctools/doctools_lang_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_lang_intro.n @@ -0,0 +1,828 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_lang_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_lang_intro" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools_lang_intro \- doctools language introduction +.SH DESCRIPTION +.PP +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 \fIdoctools language syntax\fR specification +and the \fIdoctools language command reference\fR. +.SS FUNDAMENTALS +In the broadest terms possible the \fIdoctools markup language\fR +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. +.PP +Each markup command is a Tcl command surrounded by a matching pair of +\fB[\fR and \fB]\fR. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. +.PP +.CS + + + ... [list_begin enumerated] ... + +.CE +.CS + + + ... [call [cmd foo] \\\\ + [arg bar]] ... + +.CE +.CS + + + ... [term {complex concept}] ... + +.CE +.CS + + + ... [opt "[arg key] [arg value]"] ... + +.CE +.SS "BASIC STRUCTURE" +The most simple document which can be written in doctools is +.CS + + + [manpage_begin NAME SECTION VERSION] + [description] + [manpage_end] + +.CE +This also shows us that all doctools documents are split into two +parts, the \fIheader\fR and the \fIbody\fR. Everything coming before +[\fBdescription\fR] belongs to the header, and everything coming +after belongs to the body, with the whole document bracketed by the +two \fBmanpage_*\fR commands. Before and after these opening and +closing commands we have only \fIwhitespace\fR. +.PP +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 +\fBText structure\fR. +.PP +The header section can be empty, and otherwise may contain only an +arbitrary sequence of the four so-called \fIheader\fR commands, plus +\fIwhitespace\fR. These commands are +.TP +\fBtitledesc\fR +.TP +\fBmoddesc\fR +.TP +\fBrequire\fR +.TP +\fBcopyright\fR +.PP +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 \fBtitledesc\fR and \fBmoddesc\fR 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. +.PP +Given the above a less minimal example of a document is +.CS + + +[manpage_begin NAME SECTION VERSION] +[\fBcopyright {YEAR AUTHOR}\fR] +[\fBtitledesc TITLE\fR] +[\fBmoddesc MODULE_TITLE\fR] +[\fBrequire PACKAGE VERSION\fR] +[\fBrequire PACKAGE\fR] +[description] +[manpage_end] + +.CE +Remember that the whitespace is optional. The document +.CS + + + [manpage_begin NAME SECTION VERSION] + [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] + [require PACKAGE VERSION][require PACKAGE][description] + [manpage_end] + +.CE +has the same meaning as the example before. +.PP +On the other hand, if \fIwhitespace\fR 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 \fBcomment\fR +command. +.CS + + +[\fBcomment { ... }\fR] +[manpage_begin NAME SECTION VERSION] +[copyright {YEAR AUTHOR}] +[titledesc TITLE] +[moddesc MODULE_TITLE][\fBcomment { ... }\fR] +[require PACKAGE VERSION] +[require PACKAGE] +[description] +[manpage_end] +[\fBcomment { ... }\fR] + +.CE +.SS "ADVANCED STRUCTURE" +In the simple examples of the last section we fudged a bit regarding +the markup actually allowed to be used before the \fBmanpage_begin\fR +command opening the document. +.PP +Instead of only whitespace the two templating commands \fBinclude\fR +and \fBvset\fR are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the document. I.e. it +is possible to write +.CS + + +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +[manpage_begin NAME SECTION VERSION] +[description] +[manpage_end] + +.CE +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. I.e. for example in the header as well. +.CS + + +[manpage_begin NAME SECTION VERSION] +[\fBinclude FILE\fR] +[\fBvset VAR VALUE\fR] +[description] +[manpage_end] + +.CE +The only restriction \fBinclude\fR 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 \fBmanpage_begin\fR may contain only the +templating commands \fBvset\fR and \fBinclude\fR, a file included in +the header may contain only header commands, etc. +.SS "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. +.PP +This section explains the high-level structural commands, with +everything else deferred to the following sections. +.PP +The simplest way of structuring the body is through the introduction +of paragraphs. The command for doing so is \fBpara\fR. 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 \fBdescription\fR. In the same manner the last +paragraph automatically ends at \fBmanpage_end\fR. +.CS + + +[manpage_begin NAME SECTION VERSION] +[description] + ... +[\fBpara\fR] + ... +[\fBpara\fR] + ... +[manpage_end] + +.CE +Empty paragraphs are ignored. +.PP +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 \fBsection\fR. 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 \fBdescription\fR (This +section is labeled "DESCRIPTION"). In the same manner the last section +automatically ends at \fBmanpage_end\fR. +.PP +Empty sections are \fInot\fR ignored. We are free to (not) use +paragraphs within sections. +.CS + + +[manpage_begin NAME SECTION VERSION] +[description] + ... +[\fBsection {Section A}\fR] + ... +[para] + ... +[\fBsection {Section B}\fR] + ... +[manpage_end] + +.CE +Between sections and paragraphs we have subsections, to split sections. +The command for doing so is \fBsubsection\fR. 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 \fBdescription\fR, and at the +beginning of each section. In the same manner the last subsection +automatically ends at \fBmanpage_end\fR. +.PP +Empty subsections are \fInot\fR ignored. We are free to (not) use +paragraphs within subsections. +.CS + + +[manpage_begin NAME SECTION VERSION] +[description] + ... +[section {Section A}] + ... +[\fBsubsection {Sub 1}\fR] + ... +[para] + ... +[\fBsubsection {Sub 2}\fR] + ... +[section {Section B}] + ... +[manpage_end] + +.CE +.SS "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. +.PP +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. +.PP +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. +.PP +The commands available to us are +.TP +\fBarg\fR +Its argument is a the name of a command argument. +.TP +\fBclass\fR +Its argument is a class name. +.TP +\fBcmd\fR +Its argument is a command name (Tcl command). +.TP +\fBconst\fR +Its argument is a constant. +.TP +\fBemph\fR +General, non-semantic emphasis. +.TP +\fBfile\fR +Its argument is a filename / path. +.TP +\fBfun\fR +Its argument is a function name. +.TP +\fBmethod\fR +Its argument is a method name +.TP +\fBnamespace\fR +Its argument is namespace name. +.TP +\fBopt\fR +Its argument is some optional syntax element. +.TP +\fBoption\fR +Its argument is a command line switch / widget option. +.TP +\fBpackage\fR +Its argument is a package name. +.TP +\fBsectref\fR +Its argument is the title of a section or subsection, +i.e. a section reference. +.TP +\fBsyscmd\fR +Its argument is a command name (external, system command). +.TP +\fBterm\fR +Its argument is a concept, or general terminology. +.TP +\fBtype\fR +Its argument is a type name. +.TP +\fBuri\fR +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. +.TP +\fBusage\fR +The arguments describe the syntax of a Tcl command. +.TP +\fBvar\fR +Its argument is a variable. +.TP +\fBwidget\fR +Its argument is a widget name. +.PP +The example demonstrating the use of text markup is an excerpt from +the \fIdoctools language command reference\fR, with some +highlighting added. +It shows their use within a block of text, as the arguments of a list +item command (\fBcall\fR), and our ability to nest them. +.CS + + + ... + [call [\fBcmd arg_def\fR] [\fBarg type\fR] [\fBarg name\fR]] [\fBopt\fR [\fBarg mode\fR]]] + + Text structure. List element. Argument list. Automatically closes the + previous list element. Specifies the data-[\fBarg type\fR] of the described + argument of a command, its [\fBarg name\fR] and its i/o-[\fBarg mode\fR]. The + latter is optional. + ... + +.CE +.SS 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 \fB[\fR +and \fB]\fR. +These commands, \fBlb\fR and \fBrb\fR respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text. +.PP +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. +.CS + + + ... + These commands, [cmd lb] and [cmd lb] respectively, are required + because our use of [\fBlb\fR] and [\fBrb\fR] to bracket markup commands makes it + impossible to directly use [\fBlb\fR] and [\fBrb\fR] within the text. + ... + +.CE +.SS CROSS-REFERENCES +The last two commands we have to discuss are for the declaration of +cross-references between documents, explicit and implicit. They are +\fBkeywords\fR and \fBsee_also\fR. 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. +.TP +\fBkeywords\fR +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. +.TP +\fBsee_also\fR +The arguments of this command are interpreted as references to other +documents. A processor can format them as direct links to these +documents. +.PP +.PP +All the cross-reference commands can occur anywhere in the document +between \fBmanpage_begin\fR and \fBmanpage_end\fR. 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. +.PP +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. +.CS + + + ... + [\fBsee_also doctools_intro\fR] + [\fBsee_also doctools_lang_syntax\fR] + [\fBsee_also doctools_lang_cmdref\fR] + [\fBkeywords markup {semantic markup}\fR] + [\fBkeywords {doctools markup} {doctools language}\fR] + [\fBkeywords {doctools syntax} {doctools commands}\fR] + [manpage_end] + +.CE +.SS EXAMPLES +Where ever we can write plain text we can write examples too. For +simple examples we have the command \fBexample\fR 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 \fBexample_begin\fR / \fBexample_end\fR instead. +.PP +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 \fIcan\fR use templating commands within +example blocks to read their contents from a file (Remember section +\fBAdvanced structure\fR). +.PP +The source for the very first example in this document (see section +\fBFundamentals\fR), with some highlighting added, is +.CS + + + [\fBexample\fR { + ... [list_begin enumerated] ... + }] + +.CE +Using \fBexample_begin\fR / \fBexample_end\fR this would look like +.CS + + + [\fBexample_begin\fR] + ... [list_begin enumerated] ... + [\fBexample_end\fR] + +.CE +.SS LISTS +Where ever we can write plain text we can write lists too. The main +commands are \fBlist_begin\fR to start a list, and \fBlist_end\fR 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. +.PP +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. +.PP +The list types recognized by \fBlist_begin\fR and their associated +list item commands are: +.TP +\fBarguments\fR +(\fBarg_def\fR) This opens an \fIargument (declaration) list\fR. It +is a specialized form of a term definition list where the term is an +argument name, with its type and i/o-mode. +.TP +\fBcommands\fR +(\fBcmd_def\fR) This opens a \fIcommand (declaration) list\fR. It +is a specialized form of a term definition list where the term is a +command name. +.TP +\fBdefinitions\fR +(\fBdef\fR and \fBcall\fR) This opens a general +\fIterm definition list\fR. The terms defined by the list items are +specified through the argument(s) of the list item commands, either +general terms, possibly with markup (\fBdef\fR), or Tcl commands with +their syntax (\fBcall\fR). +.TP +\fBenumerated\fR +(\fBenum\fR) This opens a general \fIenumerated list\fR. +.TP +\fBitemized\fR +(\fBitem\fR) +This opens a general \fIitemized list\fR. +.TP +\fBoptions\fR +(\fBopt_def\fR) This opens an \fIoption (declaration) list\fR. It +is a specialized form of a term definition list where the term is an +option name, possibly with the option's arguments. +.TP +\fBtkoptions\fR +(\fBtkoption_def\fR) This opens a +\fIwidget option (declaration) list\fR. 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. +.PP +Our example is the source of the definition list in the previous +paragraph, with most of the content in the middle removed. +.CS + + + ... + [\fBlist_begin\fR definitions] + [\fBdef\fR [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. + + [\fBdef\fR [const itemized]] + + ([cmd item]) + This opens a general itemized list. + + ... + [\fBdef\fR [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. + + [\fBlist_end\fR] + ... + +.CE +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 \fIillegal\fR construct is +.CS + + + ... + [list_begin itemized] + [item] + ... + [\fBsection {ILLEGAL WITHIN THE LIST}\fR] + ... + [list_end] + ... + +.CE +.SH "FURTHER READING" +Now that this document has been digested the reader, assumed to be a +\fIwriter\fR of documentation should be fortified enough to be able +to understand the formal \fIdoctools language syntax\fR +specification as well. From here on out the +\fIdoctools language command reference\fR will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. +.PP +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with one of the applications for +the processing and conversion of doctools documents, i.e. either +Tcllib's easy and simple \fBdtplite\fR, or Tclapps' +ultra-configurable \fBdtp\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_syntax +.SH KEYWORDS +doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_lang_syntax.n Index: embedded/man/files/modules/doctools/doctools_lang_syntax.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_lang_syntax.n @@ -0,0 +1,363 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_lang_syntax.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_lang_syntax" n 1.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools_lang_syntax \- doctools language syntax +.SH DESCRIPTION +.PP +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 +\fIdoctools language command reference\fR. +A beginner should read the much more informally written +\fIdoctools language introduction\fR first before trying to +understand either this document or the command reference. +.SH FUNDAMENTALS +In the broadest terms possible the \fIdoctools markup language\fR +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. +.PP +Each markup command is a just Tcl command surrounded by a matching +pair of \fB[\fR and \fB]\fR. Which commands are available, +and their arguments, i.e. syntax is specified in the +\fIdoctools language command reference\fR. +.PP +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. +.SH "LEXICAL DEFINITIONS" +In the syntax rules listed in the next section +.IP [1] + stands for all text except markup commands. +.IP [2] +Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of \fB[\fR and \fB]\fR. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. +.IP [3] + stands for all text consisting only of spaces, newlines, +tabulators and the \fBcomment\fR markup command. +.PP +.SH SYNTAX +The rules listed here specify only the syntax of doctools +documents. The lexical level of the language was covered in the +previous section. +.PP +Regarding the syntax of the (E)BNF itself +.IP [1] +The construct { X } stands for zero or more occurrences of X. +.IP [2] +The construct [ X ] stands for zero or one occurrence of X. +.IP [3] +The construct LIST_BEGIN stands for the markup command +\fBlist_begin\fR with \fBX\fR as its type argument. +.PP +The syntax: +.CS + + +manpage = defs + MANPAGE_BEGIN + header + DESCRIPTION + body + MANPAGE_END + { } + +defs = { INCLUDE | VSET | } + +header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref } + +xref = KEYWORDS | SEE_ALSO | CATEGORY + +body = paras { SECTION sbody } +sbody = paras { SUBSECTION ssbody } +ssbody = paras + +paras = tblock { (PARA | NL) tblock } + +tblock = { | defs | markup | xref | an_example | a_list } + +markup = ARG | CLASS | CMD | CONST | EMPH | FILE + | FUN | LB | METHOD | NAMESPACE | OPT | OPTION + | PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM + | TYPE | URI | USAGE | VAR | WIDGET + +example = EXAMPLE + | EXAMPLE_BEGIN extext EXAMPLE_END + +extext = { | defs | markup } + +a_list = LIST_BEGIN argd_list LIST_END + | LIST_BEGIN cmdd_list LIST_END + | LIST_BEGIN def_list LIST_END + | LIST_BEGIN enum_list LIST_END + | LIST_BEGIN item_list LIST_END + | LIST_BEGIN optd_list LIST_END + | LIST_BEGIN tkoptd_list LIST_END + +argd_list = [ ] { ARG_DEF paras } +cmdd_list = [ ] { CMD_DEF paras } +def_list = [ ] { (DEF|CALL) paras } +enum_list = [ ] { ENUM paras } +item_list = [ ] { ITEM paras } +optd_list = [ ] { OPT_DEF paras } +tkoptd_list = [ ] { TKOPTION_DEF paras } + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro +.SH KEYWORDS +doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/doctools_plugin_apiref.n Index: embedded/man/files/modules/doctools/doctools_plugin_apiref.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/doctools_plugin_apiref.n @@ -0,0 +1,684 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/doctools_plugin_apiref.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2010 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools_plugin_apiref" n 1.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools_plugin_apiref \- doctools plugin API reference +.SH SYNOPSIS +\fBdt_copyright\fR +.sp +\fBdt_file\fR +.sp +\fBdt_mainfile\fR +.sp +\fBdt_fileid\fR +.sp +\fBdt_fmap\fR \fIsymfname\fR +.sp +\fBdt_format\fR +.sp +\fBdt_imgdata\fR \fIkey\fR \fIextensions\fR +.sp +\fBdt_imgdst\fR \fIkey\fR \fIextensions\fR +.sp +\fBdt_imgsrc\fR \fIkey\fR \fIextensions\fR +.sp +\fBdt_lnesting\fR +.sp +\fBdt_module\fR +.sp +\fBdt_read\fR \fIfile\fR +.sp +\fBdt_source\fR \fIfile\fR +.sp +\fBdt_user\fR +.sp +\fBex_cappend\fR \fItext\fR +.sp +\fBex_cget\fR \fIvarname\fR +.sp +\fBex_cis\fR \fIcname\fR +.sp +\fBex_cname\fR +.sp +\fBex_cpop\fR \fIcname\fR +.sp +\fBex_cpush\fR \fIcname\fR +.sp +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +.sp +\fBex_lb\fR ?\fInewbracket\fR? +.sp +\fBex_rb\fR ?\fInewbracket\fR? +.sp +\fBfmt_initialize\fR +.sp +\fBfmt_listvariables\fR +.sp +\fBfmt_numpasses\fR +.sp +\fBfmt_postprocess\fR \fItext\fR +.sp +\fBfmt_setup\fR \fIn\fR +.sp +\fBfmt_shutdown\fR +.sp +\fBfmt_varset\fR \fIvarname\fR \fItext\fR +.sp +\fBfmt_plain_text\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +This document is intended for \fIplugin writers\fR, i.e. developers +wishing to write a doctools \fIformatting engine\fR for some output +format X. +.PP +It specifies the interaction between the \fBdoctools\fR package +and its plugins, i.e. the interface any doctools formatting engine has +to comply with. +.PP +This document deals with version 1 of the interface. +.PP +A reader who is on the other hand more interested in the markup +language itself should start with the +\fIdoctools language introduction\fR and proceed from there to the +formal specifications, i.e. the \fIdoctools language syntax\fR and +the \fIdoctools language command reference\fR. +.SH OVERVIEW +The API for a doctools formatting engine consists of two major +sections. +.PP +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 +\fBFRONTEND COMMANDS\fR for their detailed specification. +.PP +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 \fBPLUGIN COMMANDS\fR and its subsections for +their detailed specification. +.SH "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. +.PP +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 \fBPLUGIN COMMANDS\fR) are executed. +.PP +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. +.PP +Coming back to the imported commands, all the commands with prefix +\fIdt_\fR provide limited access to specific parts of the frontend, +whereas the commands with prefix \fIex_\fR provide access to the +state of the \fBtextutil::expander\fR object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. +.PP +.TP +\fBdt_copyright\fR +Query command. It returns a string containing the copyright +information the doctools processor was configured with. The relevant +option is \fB-copyright\fR). +.TP +\fBdt_file\fR +Query command. It returns the full path of the file containing the +input currently processed by the engine. This may be an included file. +.TP +\fBdt_mainfile\fR +Query command. It returns the full path of the toplevel file containing +the input currently processed by the engine. +.TP +\fBdt_fileid\fR +Query command. It returns the name of the file containing the input +currently processed by the engine, without path, nor extension. +.TP +\fBdt_fmap\fR \fIsymfname\fR +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename \fIsymfname\fR. It will return the +unchanged input if no mapping was established for \fIsymfname\fR. +.sp +The required mappings are established with the method \fBmap\fR of +a frontend, as explained in section \fBOBJECT METHODS\fR +of the documentation for the package \fBdoctools\fR. +.TP +\fBdt_format\fR +Query command. It returns the name of the format associated with the +doctools formatting engine. +.TP +\fBdt_imgdata\fR \fIkey\fR \fIextensions\fR +Query command. Access to the image map. Looks for an image recorded +under the \fIkey\fR and having on the specified \fIextension\fR. If a +matching image is found its data is returned as the result of the +command. Otherwise an empty string is returned. +.TP +\fBdt_imgdst\fR \fIkey\fR \fIextensions\fR +Query command. Access to the image map. Looks for an image recorded +under the \fIkey\fR and having on the specified \fIextension\fR. 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. +.TP +\fBdt_imgsrc\fR \fIkey\fR \fIextensions\fR +Query command. Access to the image map. Looks for an image recorded +under the \fIkey\fR and having on the specified \fIextension\fR. If a +matching image is found its origin path is returned as the result of +the command. Otherwise an empty string is returned. +.TP +\fBdt_lnesting\fR +Query command. It returns the number of lists currently open. +.TP +\fBdt_module\fR +Query command. It returns the name of the module the input currently +processed belongs to. +.TP +\fBdt_read\fR \fIfile\fR +Controlled filesystem access. Returns contents of \fIfile\fR 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. +.TP +\fBdt_source\fR \fIfile\fR +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. +.TP +\fBdt_user\fR +Query command. It returns the name of the current user as known to the +tcl interpreter the frontend controlling the formatting engine resides +in. +.TP +\fBex_cappend\fR \fItext\fR +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. +.TP +\fBex_cget\fR \fIvarname\fR +Retrieves the value of variable \fIvarname\fR, defined in the current +context. +.TP +\fBex_cis\fR \fIcname\fR +Determines whether or not the name of the current context is +\fIcname\fR. +.TP +\fBex_cname\fR +Returns the name of the current context. +.TP +\fBex_cpop\fR \fIcname\fR +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named \fIcname\fR, or an +error results. +.TP +\fBex_cpush\fR \fIcname\fR +Pushes a context named \fIcname\fR onto the context stack. The +context must be popped by \fBcpop\fR before expansion ends or an +error results. +.TP +\fBex_cset\fR \fIvarname\fR \fIvalue\fR +Sets variable \fIvarname\fR to \fIvalue\fR in the current context. +.TP +\fBex_lb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the new +bracket, and is returned. +.TP +\fBex_rb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the +new bracket, and is returned. +.PP +.SH "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. +.SS "MANAGEMENT COMMANDS" +The management commands a plugin has to provide are used by the +frontend to +.IP [1] +initialize and shutdown the plugin +.IP [2] +determine the number of passes it has +to make over the input +.IP [3] +initialize and shutdown each pass +.IP [4] +query and initialize engine parameters +.PP +.PP +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: +.CS + + + 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 + ... + +.CE +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. +.PP +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 \fBfmt_varset\fR. +.PP +In each of the passes, i.e. after the calls of \fBfmt_setup\fR 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 \fIdoctools language syntax\fR specification. +.PP +A different way of looking at the sequence is: +.IP \(bu +First some basic parameters are determined. +.IP \(bu +Then everything starting at the first \fBfmt_varset\fR to +\fBfmt_shutdown\fR forms a \fIrun\fR, the formatting of a +single input. Each run can be followed by more. +.IP \(bu +Embedded within each run we have one or more \fIpasses\fR, +each starting with \fBfmt_setup\fR and going until either the next +\fBfmt_setup\fR or \fBfmt_postprocess\fR is reached. +.sp +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. +.PP +.PP +The commands, their names, signatures, and responsibilities are, in +detail: +.TP +\fBfmt_initialize\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBfmt_listvariables\fR +\fIInitialization/Shutdown\fR and \fIEngine parameters\fR. +Second command is called after the plugin code has been loaded, +i.e. immediately after \fBfmt_numpasses\fR. +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. +.TP +\fBfmt_numpasses\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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. +.TP +\fBfmt_postprocess\fR \fItext\fR +\fIInitialization/Shutdown\fR. +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. +.sp +Expected to return a value, the final result of formatting the input. +.TP +\fBfmt_setup\fR \fIn\fR +\fIInitialization/Shutdown\fR and \fIPass management\fR. +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 \fB1\fR 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. +.TP +\fBfmt_shutdown\fR +\fIInitialization/Shutdown\fR. +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. +.TP +\fBfmt_varset\fR \fIvarname\fR \fItext\fR +\fIEngine parameters\fR. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by \fIvarname\fR, the value to +set in \fItext\fR. +.sp +The command has to throw an error if an unknown \fIvarname\fR is +used. Only the names returned by \fBfmt_listvariables\fR have to be +considered as known. +.sp +The values of all engine parameters have to persist between passes and +runs. +.PP +.SS "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 \fBlb\fR, \fBrb\fR, \fBvset\fR, \fBinclude\fR, and +\fBcomment\fR. 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. +.PP +This means, that each of the 49 markup commands specified in the +\fIdoctools language command reference\fR 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 \fIfmt_\fR added to it. +.PP +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. +.PP +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +\fIdoctools language command reference\fR for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. +.PP +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 \fIdoctools language syntax\fR +specification. +.PP +.TP +\fBfmt_plain_text\fR \fItext\fR +\fINo associated markup command\fR. +.sp +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. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax +.SH KEYWORDS +document, formatter, formatting engine, manpage, markup, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2010 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools/mpexpand.n Index: embedded/man/files/modules/doctools/mpexpand.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools/mpexpand.n @@ -0,0 +1,319 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools/mpexpand.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries +'\" Copyright (c) 2003 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "mpexpand" n 1.0 tcllib "Documentation toolbox" +.BS +.SH NAME +mpexpand \- Markup processor +.SH SYNOPSIS +\fBmpexpand\fR ?-module \fImodule\fR? \fIformat\fR \fIinfile\fR|- \fIoutfile\fR|- +.sp +\fBmpexpand.all\fR ?\fI-verbose\fR? ?\fImodule\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This manpage describes a processor / converter for manpages in the +doctools format as specified in \fBdoctools_fmt\fR. The processor +is based upon the package \fBdoctools\fR. +.TP +\fBmpexpand\fR ?-module \fImodule\fR? \fIformat\fR \fIinfile\fR|- \fIoutfile\fR|- +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 +\fIinfile\fR is "\fB-\fR" the processor will read from +\fBstdin\fR. If \fIoutfile\fR is "\fB-\fR" the processor will +write to \fBstdout\fR. +.sp +If the option \fI-module\fR is present its value overrides the internal +definition of the module name. +.sp +The currently known output formats are +.RS +.TP +\fBnroff\fR +The processor generates *roff output, the standard format for unix +manpages. +.TP +\fBhtml\fR +The processor generates HTML output, for usage in and display by web +browsers. +.TP +\fBtmml\fR +The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML. +.TP +\fBlatex\fR +The processor generates LaTeX output. +.TP +\fBwiki\fR +The processor generates Wiki markup as understood by \fBwikit\fR. +.TP +\fBlist\fR +The processor extracts the information provided by \fBmanpage_begin\fR. +.TP +\fBnull\fR +The processor does not generate any output. +.RE +.TP +\fBmpexpand.all\fR ?\fI-verbose\fR? ?\fImodule\fR? +This command uses \fBmpexpand\fR to generate all possible output +formats for all manpages in the current directory. The manpages are +recognized through the extension "\fI.man\fR". If \fI-verbose\fR is +specified the command will list its actions before executing them. +.sp +The \fImodule\fR information is passed to \fBmpexpand\fR. +.PP +.SH NOTES +.PP +Possible future formats are plain text, pdf and postscript. +.SH "SEE ALSO" +expander(n), format(n), formatter(n) +.SH KEYWORDS +HTML, TMML, conversion, manpage, markup, nroff +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries +Copyright (c) 2003 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2base/html_cssdefaults.n Index: embedded/man/files/modules/doctools2base/html_cssdefaults.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2base/html_cssdefaults.n @@ -0,0 +1,282 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2base/html_cssdefaults.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::html::cssdefaults" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::html::cssdefaults \- Default CSS style for HTML export plugins +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::html::cssdefaults ?0.1?\fR +.sp +\fB::doctools::html::cssdefaults::contents\fR +.sp +.BE +.SH 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. +.PP +This is an internal package of doctools, for use by \fIexport\fR plugins, +i.e. the packages converting doctools related documented into other +formats, most notably \fIHTML\fR. +.SH API +.TP +\fB::doctools::html::cssdefaults::contents\fR +This command returns the text of the default CSS style to use for HTML +markup generated by the various HTML export plugins. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +CSS, HTML, doctools, export, plugin, style +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2base/nroff_manmacros.n Index: embedded/man/files/modules/doctools2base/nroff_manmacros.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2base/nroff_manmacros.n @@ -0,0 +1,282 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2base/nroff_manmacros.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::nroff::man_macros" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::nroff::man_macros \- Default CSS style for NROFF export plugins +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::nroff::man_macros ?0.1?\fR +.sp +\fB::doctools::nroff::man_macros::contents\fR +.sp +.BE +.SH DESCRIPTION +This package provides a single command providing access to the +definition of the nroff \fIman\fR macro set to use for NROFF markup +generated by the various NROFF export plugins. +.PP +This is an internal package of doctools, for use by \fIexport\fR plugins, +i.e. the packages converting doctools related documented into other +formats, most notably \fInroff\fR. +.SH API +.TP +\fB::doctools::nroff::man_macros::contents\fR +This command returns the text of the default CSS style to use for NROFF +generated by the various NROFF export plugins. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, macros, man_macros, nroff, plugin +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2base/tcl_parse.n Index: embedded/man/files/modules/doctools2base/tcl_parse.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2base/tcl_parse.n @@ -0,0 +1,408 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2base/tcl_parse.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::tcl::parse" n 1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::tcl::parse \- Processing text in 'subst -novariables' format +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit \fR +.sp +package require \fBfileutil \fR +.sp +package require \fBlogger \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::stack \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBtreeql \fR +.sp +\fB::doctools::tcl::parse\fR \fBtext\fR \fItree\fR \fItext\fR ?\fIroot\fR? +.sp +\fB::doctools::tcl::parse\fR \fBfile\fR \fItree\fR \fIpath\fR ?\fIroot\fR? +.sp +.BE +.SH DESCRIPTION +This package provides commands for parsing text with embedded Tcl +commands as accepted by the Tcl builtin command +\fBsubst -novariables\fR. The result of the parsing is an abstract +syntax tree. +.PP +This is an internal package of doctools, for use by the higher level +parsers processing the \fIdocidx\fR, \fIdoctoc\fR, and \fIdoctools\fR +markup languages. +.SH API +.TP +\fB::doctools::tcl::parse\fR \fBtext\fR \fItree\fR \fItext\fR ?\fIroot\fR? +The command takes the \fItext\fR and parses it under the assumption +that it contains a string acceptable to the Tcl builtin command +\fBsubst -novariables\fR. Errors are thrown otherwise during the +parsing. The format used for these errors in described in section +\fBError format\fR. +.sp +The command returns the empty string as it result. The actual result +of the parsing is entered into the tree structure \fItree\fR, under +the node \fIroot\fR. +If \fIroot\fR is not specified the root of \fItree\fR is used. The +\fItree\fR has to exist and be the command of a tree object which +supports the same methods as trees created by the package +\fBstruct::tree\fR. +.sp +In case of errors \fItree\fR will be left in an undefined state. +.TP +\fB::doctools::tcl::parse\fR \fBfile\fR \fItree\fR \fIpath\fR ?\fIroot\fR? +The same as \fBtext\fR, except that the text to parse is read from +the file specified by \fIpath\fR. +.PP +.SH "ERROR FORMAT" +When the parser encounters a problem in the input +it will throw an error using the format described +here. +.IP [1] +The message will contain the reason for the problem (unexpected +character or end of input in input), the character in question, if +any, and the line and column the problem was found at, in a human +readable form. This part is not documented further as its format may +change as we see fit. It is intended for human consumption, not +machine. +.IP [2] +The error code however will contain a machine-readable representation +of the problem, in the form of a 5-element list containing, in the +order listed below +.RS +.IP [1] +the constant string \fBdoctools::tcl::parse\fR +.IP [2] +the cause of the problem, one of +.RS +.TP +\fBchar\fR +Unexpected character in input +.TP +\fBeof\fR +Unexpected end of the input +.RE +.IP [3] +The location of the problem as offset from the beginning of the input, +counted in characters. Note: Line markers count as one character. +.IP [4] +The line the problem was found on (counted from 1 (one)), +.IP [5] +The column the problem was found at (counted from 0 (zero)) +.RE +.PP +.SH "TREE STRUCTURE" +After successfully parsing a string the generated tree will have the +following structure: +.IP [1] +In the following items the word 'root' refers to the node which was +specified as the root of the tree when invoking either \fBtext\fR +or \fBfile\fR. This may be the actual root of the tree. +.IP [2] +All the following items further ignore the possibility of pre-existing +attributes in the pre-existing nodes. If attributes exists with the +same names as the attributes used by the parser the pre-existing +values are written over. Attributes with names not clashing with the +parser's attributes are not touched. +.IP [3] +The root node has no attributes. +.IP [4] +All other nodes have the attributes +.RS +.TP +type +The value is a string from the set { Command , Text , Word } +.TP +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,. +.TP +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 (\fBone\fR). +.TP +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 (\fBzero\fR). +.RE +.IP [5] +The children of the root, if any, are of type Command and Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node. +.IP [6] +The children of a Command node, if any, are of type Command, and Text, +and Word, they describe the arguments of the command. +.IP [7] +The children of a Word node, if any, are of type Command, Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node. +.IP [8] +A Word node without children represents the empty string. +.IP [9] +All Text nodes are leaves of the tree. +.IP [10] +All leaves of the tree are either Text or Command nodes. +Word nodes cannot be leaves. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +Tcl syntax, command, doctools, parser, subst, word +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2base/tcllib_msgcat.n Index: embedded/man/files/modules/doctools2base/tcllib_msgcat.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2base/tcllib_msgcat.n @@ -0,0 +1,303 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2base/tcllib_msgcat.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat \- Message catalog management for the various document parsers +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat ?0.1?\fR +.sp +\fB::doctools::msgcat::init\fR \fIprefix\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +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. +.SH API +.TP +\fB::doctools::msgcat::init\fR \fIprefix\fR +The command locates and loads the message catalogs for all the +languages returned by \fBmsgcat::mcpreferences\fR, provided that they +could be found. It returns an integer number describing how many +packages were found and loaded. +.sp +The names of the packages the command will look for have the form +"doctools::msgcat::\fIprefix\fR::\fBlangcode\fR", with \fIprefix\fR +the argument to the command, and the \fBlangcode\fR supplied by the +result of \fBmsgcat::mcpreferences\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +catalog package, docidx, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2idx/container.n Index: embedded/man/files/modules/doctools2idx/container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/container.n @@ -0,0 +1,626 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx" n 2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx \- Holding keyword indices +.SH SYNOPSIS +package require \fBdoctools::idx ?2?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBsnit \fR +.sp +\fB::doctools::idx\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBkey add\fR \fIname\fR +.sp +\fIobjectName\fR \fBkey remove\fR \fIname\fR +.sp +\fIobjectName\fR \fBkey references\fR \fIname\fR +.sp +\fIobjectName\fR \fBkeys\fR +.sp +\fIobjectName\fR \fBreference add\fR \fItype\fR \fIkey\fR \fIname\fR \fIlabel\fR +.sp +\fIobjectName\fR \fBreference remove\fR \fIname\fR +.sp +\fIobjectName\fR \fBreference label\fR \fIname\fR +.sp +\fIobjectName\fR \fBreference keys\fR \fIname\fR +.sp +\fIobjectName\fR \fBreference type\fR \fIname\fR +.sp +\fIobjectName\fR \fBreferences\fR +.sp +\fIobjectName\fR \fBtitle\fR +.sp +\fIobjectName\fR \fBtitle\fR \fItext\fR +.sp +\fIobjectName\fR \fBlabel\fR +.sp +\fIobjectName\fR \fBlabel\fR \fItext\fR +.sp +\fIobjectName\fR \fBimporter\fR +.sp +\fIobjectName\fR \fBimporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fBexporter\fR +.sp +\fIobjectName\fR \fBexporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +.sp +.BE +.SH DESCRIPTION +This package provides a class to contain and programmatically +manipulate keyword indices +.PP +This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are +.IP [1] +\fIExporting keyword indices\fR, and +.IP [2] +\fIImporting keyword indices\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBKeyword index serialization format\fR. +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. +.SH CONCEPTS +.IP [1] +A \fIkeyword index\fR consists of a (possibly empty) set of \fIkeywords\fR. +.IP [2] +Each keyword in the set is identified by its name. +.IP [3] +Each keyword has a (possibly empty) set of \fIreferences\fR. +.IP [4] +A reference can be associated with more than one keyword. +.IP [5] +A reference not associated with at least one keyword is not possible +however. +.IP [6] +Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (\fBurl\fR, +or \fBmanpage\fR). +.IP [7] +The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with. +.IP [8] +In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with. +.PP +A few notes +.IP [1] +Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified. +.IP [2] +Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url. +.IP [3] +While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::idx\fR \fIobjectName\fR +This command creates a new container object with an associated Tcl +command whose name is \fIobjectName\fR. This \fIobject\fR command is +explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::idx\fR command have the +following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBkey add\fR \fIname\fR +This method adds the keyword \fIname\fR to the index. If the keyword +is already known nothing is done. The result of the method is the +empty string. +.TP +\fIobjectName\fR \fBkey remove\fR \fIname\fR +This method removes the keyword \fIname\fR 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. +.TP +\fIobjectName\fR \fBkey references\fR \fIname\fR +This method returns a list containing the names of all references +associated with the keyword \fIname\fR. An error is thrown in the +keyword is not known to the index. The order of the references in the +list is undefined. +.TP +\fIobjectName\fR \fBkeys\fR +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. +.TP +\fIobjectName\fR \fBreference add\fR \fItype\fR \fIkey\fR \fIname\fR \fIlabel\fR +This method adds the reference \fIname\fR to the index and associates +it with the keyword \fIkey\fR. +The other two arguments hold the \fItype\fR and \fIlabel\fR 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 +\fIkey\fR. If that is true already as well nothing is done, but the +\fIlabel\fR updated to the new value. The result of the method is the +empty string. +.sp +The \fItype\fR argument has be to one of \fBmanpage\fR or \fBurl\fR. +.TP +\fIobjectName\fR \fBreference remove\fR \fIname\fR +The reference \fIname\fR 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. +.TP +\fIobjectName\fR \fBreference label\fR \fIname\fR +This method returns the label associated with the reference +\fIname\fR. An error is thrown if the reference is not known. +.TP +\fIobjectName\fR \fBreference keys\fR \fIname\fR +This method returns a list containing the names of all keywords +associated with the reference \fIname\fR. An error is thrown in the +reference is not known to the index. The order of the keywords in the +list is undefined. +.TP +\fIobjectName\fR \fBreference type\fR \fIname\fR +This method returns the type of the reference \fIname\fR. An error is +thrown in the reference is not known to the index. +.TP +\fIobjectName\fR \fBreferences\fR +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. +.TP +\fIobjectName\fR \fBtitle\fR +Returns the currently defined title of the keyword index. +.TP +\fIobjectName\fR \fBtitle\fR \fItext\fR +Sets the title of the keyword index to \fItext\fR, and returns it as +the result of the command. +.TP +\fIobjectName\fR \fBlabel\fR +Returns the currently defined label of the keyword index. +.TP +\fIobjectName\fR \fBlabel\fR \fItext\fR +Sets the label of the keyword index to \fItext\fR, and returns it as +the result of the command. +.TP +\fIobjectName\fR \fBimporter\fR +Returns the import manager object currently attached to the container, +if any. +.TP +\fIobjectName\fR \fBimporter\fR \fIobject\fR +Attaches the \fIobject\fR as import manager to the container, and +returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBimport text\fR 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. +.TP +\fIobjectName\fR \fBexporter\fR +Returns the export manager object currently attached to the container, +if any. +.TP +\fIobjectName\fR \fBexporter\fR \fIobject\fR +Attaches the \fIobject\fR as export manager to the container, and +returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBexport object\fR 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 \fIobject\fR will +use the container's method \fBserialize\fR to obtain the +serialization of the keyword index from which to generate the text. +.TP +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +This method replaces the contents of the index object with the index +contained in the \fIdata\fR. If no \fIformat\fR was specified it is +assumed to be the regular serialization of a keyword index. +.sp +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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +This method behaves like \fBdeserialize =\fR in its essentials, +except that it merges the keyword index in the \fIdata\fR 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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +This method returns the keyword index contained in the object. If no +\fIformat\fR is not specified the returned result is the canonical +serialization of its contents. +.sp +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. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, TMML, conversion, docidx markup, documentation, formatting, generation, index, json, keyword index, latex, manpage, markup, nroff, parsing, plugin, reference, tcler's wiki, text, url, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2idx/export.n Index: embedded/man/files/modules/doctools2idx/export.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export.n @@ -0,0 +1,640 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export \- Exporting keyword indices +.SH SYNOPSIS +package require \fBdoctools::idx::export ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::config \fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBsnit \fR +.sp +package require \fBpluginmgr \fR +.sp +\fB::doctools::idx::export\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBconfig names\fR +.sp +\fIobjectName\fR \fBconfig get\fR +.sp +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +.sp +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH 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 \fIdocidx\fR, \fIHTML\fR, etc. +.PP +This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are +.IP [1] +\fIImporting keyword indices\fR, and +.IP [2] +\fIHolding keyword indices\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBKeyword index serialization format\fR. +.PP +The plugin system of our class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBDOCTOOLS_IDX_EXPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBDOCTOOLS_IDX_PLUGINS\fR, +.IP [3] +the environment variable \fBDOCTOOLS_PLUGINS\fR, +.IP [4] +the path "\fI~/.doctools/idx/export/plugin\fR" +.IP [5] +the path "\fI~/.doctools/idx/plugin\fR" +.IP [6] +the path "\fI~/.doctools/plugin\fR" +.IP [7] +the path "\fI~/.doctools/idx/export/plugins\fR" +.IP [8] +the path "\fI~/.doctools/idx/plugins\fR" +.IP [9] +the path "\fI~/.doctools/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\IDX\\EXPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\IDX\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using Windows(tm) operating system. +.PP +The whole system is delivered with six predefined export plugins, +namely +.TP +docidx +See \fIdocidx export plugin\fR for details. +.TP +html +See \fIhtml export plugin\fR for details. +.TP +json +See \fIjson export plugin\fR for details. +.TP +nroff +See \fInroff export plugin\fR for details. +.TP +text +See \fItext export plugin\fR for details. +.TP +wiki +See \fIwiki export plugin\fR for details. +.PP +.PP +Readers wishing to write their own export plugin for some format, i.e. +\fIplugin writer\fRs reading and understanding the section +containing the \fBExport plugin API v2 reference\fR is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail. +.SH CONCEPTS +.IP [1] +A \fIkeyword index\fR consists of a (possibly empty) set of \fIkeywords\fR. +.IP [2] +Each keyword in the set is identified by its name. +.IP [3] +Each keyword has a (possibly empty) set of \fIreferences\fR. +.IP [4] +A reference can be associated with more than one keyword. +.IP [5] +A reference not associated with at least one keyword is not possible +however. +.IP [6] +Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (\fBurl\fR, +or \fBmanpage\fR). +.IP [7] +The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with. +.IP [8] +In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with. +.PP +A few notes +.IP [1] +Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified. +.IP [2] +Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url. +.IP [3] +While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::idx::export\fR \fIobjectName\fR +This command creates a new export manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::idx::export\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +This method takes the canonical serialization of a keyword index +stored in \fIserial\fR and converts it to the specified \fIformat\fR, +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. +.sp +If no format is specified the method defaults to \fBdocidx\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBKeyword index serialization format\fR. +.sp +The plugin has to conform to the interface specified in section +\fBExport plugin API v2 reference\fR. +.TP +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBexport serial\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBserialize\fR method returning the canonical serialization of a +keyword index. It invokes that method, feeds the result into +\fBexport serial\fR and returns the resulting string as its own +result. +.TP +\fIobjectName\fR \fBconfig names\fR +This method returns a list containing the names of all configuration +variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig get\fR +This method returns a dictionary containing the names and values of +all configuration variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +This method sets the configuration variable \fIname\fR to the +specified \fIvalue\fR and returns the new value of the variable. +.sp +If no value is specified it simply returns the current value, without +changing it. +.sp +Note that while the user can set the predefined configuration +variables \fBuser\fR and \fBformat\fR doing so will have no +effect, these values will be internally overriden when invoking an +import plugin. +.TP +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +This method unsets all configuration variables matching the specified +glob \fIpattern\fRs. If no pattern is specified it will unset all +currently defined configuration variables. +.PP +.SH "EXPORT PLUGIN API V2 REFERENCE" +Plugins are what this package uses to manage the support for any +output format beyond the +\fBKeyword index serialization format\fR. Here we specify the +API the objects created by this package use to interact with their +plugins. +.PP +A plugin for this package has to follow the rules listed below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +doctools::idx::export::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +generate output for. This name is also the argument to provide +to the various \fBexport\fR methods of export manager +objects to get a string encoding a keyword index in that +format. +.IP [3] +The plugin can expect that the package +\fBdoctools::idx::export::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.IP [4] +A plugin has to provide one command, with the signature shown +below. +.RS +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +Whenever an export manager of \fBdoctools::idx\fR has to generate +output for an index it will invoke this command. +.RS +.TP +string \fIserial\fR +This argument will contain the \fIcanonical\fR serialization of the +index for which to generate the output. +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBKeyword index serialization format\fR. +.TP +dictionary \fIconfiguration\fR +This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values. +.sp +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. +.RS +.TP +user +This variable is expected to contain the name of the user +owning the process invoking the plugin. +.TP +format +This variable is expected to contain the name of the +format whose plugin is invoked. +.TP +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. +.TP +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 \fBmanpage\fR 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. +.RE +.RE +.RE +.IP [5] +A single usage cycle of a plugin consists of the invokations of +the command \fBexport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, conversion, docidx, documentation, export, formatting, generation, index, json, keyword index, manpage, markup, nroff, plugin, reference, tcler's wiki, text, url, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2idx/export_docidx.n Index: embedded/man/files/modules/doctools2idx/export_docidx.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_docidx.n @@ -0,0 +1,434 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_docidx.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::docidx" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::docidx \- docidx export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::docidx ?0.1?\fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of docidx markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates docidx markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH "[DOCIDX] NOTATION OF KEYWORD INDICES" +The docidx format for keyword indices, also called the +\fIdocidx markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdocidx language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdocidx language syntax\fR and +.IP [2] +\fIdocidx language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH CONFIGURATION +The docidx export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +boolean \fInewlines\fR +If this flag is set the plugin will break the generated docidx code +across lines, with each markup command on a separate line. +.sp +If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements. +.TP +boolean \fIindented\fR +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 \fBnewlines\fR is set. This effect is independent of the +value for \fBaligned\fR however. +.sp +If this flag is not set (the default), the output is formatted as per +the values of \fBnewlines\fR and \fBaligned\fR, and no indenting is +done. +.TP +boolean \fIaligned\fR +If this flag is set the generator ensures that the arguments for the +\fBmanpage\fR and \fBurl\fR commands in a keyword section are aligned +vertically for a nice table effect. To make this work this also +implies that \fBnewlines\fR is set. This effect is independent of the +value for \fBindented\fR however. +.sp +If this flag is not set (the default), the output is formatted as per +the values of \fBnewlines\fR and \fBindented\fR, and no alignment is +done. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBformat\fR, and \fBmap\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +docidx, doctools, export, index, serialization +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries + +.fi ADDED embedded/man/files/modules/doctools2idx/export_html.n Index: embedded/man/files/modules/doctools2idx/export_html.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_html.n @@ -0,0 +1,519 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_html.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::html" n 0.2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::html \- HTML export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::html ?0.2?\fR +.sp +package require \fBdoctools::text \fR +.sp +package require \fBdoctools::html \fR +.sp +package require \fBdoctools::html::cssdefaults \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of HTML markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates HTML markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +dictionary \fImap\fR +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. +.sp +Url references and symbolic file names without a mapping are used +unchanged. +.TP +boolean \fInewlines\fR +If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line. +.sp +If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements. +.TP +boolean \fIindented\fR +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 \fBnewlines\fR is set. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBnewlines\fR, and no indenting is done. +.TP +string \fImeta\fR +This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output in +the section of the document, just after the tag. +.TP +string \fIheader\fR +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. +.TP +string \fIfooter\fR +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. +.TP +dictionary \fIkwid\fR +The value of this variable (default: empty) maps keywords to the +identifiers to use as their anchor names. Each keyword \fBFOO\fR not +found in the dictionary uses \fBKW-\fR\fBFOO\fR as anchor, +i.e. itself prefixed with the string \fBKW-\fR. +.TP +string \fIsepline\fR +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. +.TP +integer \fIkwidth\fR +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. +.TP +string \fIdot\fR +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. +.TP +string \fIclass.main\fR +This variable contains the class name for the main <div>'ivision of +the generated document. The default is \fBdoctools\fR. +.TP +string \fIclass.header\fR +This variable contains the class name for the header <div>'ision of +the generated document. The default is \fBidx-header\fR. This +division contains the document title, the user specified \fBheader\fR, +if any, a visible separator line, and the navigation bar for quick +access to each keyword section. +.TP +string \fIclass.title\fR +This variable contains the class name for the <h1> tag enclosing the +document title. The default is \fBidx-title\fR. +.TP +string \fIclass.navsep\fR +This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +\fBidx-navsep\fR. +.TP +string \fIclass.navbar\fR +This variable contains the class name for the navigation <div>'ision +enclosing the navigation bar of the generated document. The default is +\fBidx-kwnav\fR. +.TP +string \fIclass.contents\fR +This variable contains the class name for the <table> holding the +keywords and their references in the generated document. The default +is \fBidx-contents\fR. +.TP +string \fIclass.leader\fR +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 \fBidx-leader\fR. +.TP +string \fIclass.row0\fR +This variable contains the class name used to label the even rows +(<tr>) of the keyword table. The default is \fBidx-even\fR. +.TP +string \fIclass.row1\fR +This variable contains the class name used to label the odd rows +(<tr>) of the keyword table. The default is \fBidx-odd\fR. +.TP +string \fIclass.keyword\fR +This variable contains the class name used to label the keyword +cells/column (<td>) in the keyword table of the document. The default +is \fBidx-keyword\fR. +.TP +string \fIclass.refs\fR +This variable contains the class name used to label the reference +cells/column (<td>) in the keyword table of the document. The default +is \fBidx-refs\fR. +.TP +string \fIclass.footer\fR +This variable contains the class name for the footer <div>'ision of +the generated document. The default is \fBidx-footer\fR. This +division contains a browser-visible separator line and the user +specified \fBfooter\fR, if any. +.PP +\fINote\fR that this plugin ignores the standard configuration +variable \fBformat\fR, and its value. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, doctools, export, index, serialization +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/export_json.n Index: embedded/man/files/modules/doctools2idx/export_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_json.n @@ -0,0 +1,451 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::json" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::json \- JSON export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::json ?0.1?\fR +.sp +package require \fBtextutil::adjust \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of JSON markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates JSON markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH "JSON NOTATION OF KEYWORD INDICES" +The JSON format used for keyword indices is a direct translation of +the \fBKeyword index serialization format\fR, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization +.CS + + +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 {} +} + +.CE +is equivalent to the JSON string +.CS + + +{ + "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" : "" + } +} + +.CE +.SH CONFIGURATION +The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +boolean \fIindented\fR +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. +.sp +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. +.TP +boolean \fIaligned\fR +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 \fBindented\fR +is set. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBindented\fR, without trying to align the values for +dictionary keys. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBformat\fR, \fBfile\fR, and \fBmap\fR and +their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +JSON, doctools, export, index, serialization +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/export_nroff.n Index: embedded/man/files/modules/doctools2idx/export_nroff.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_nroff.n @@ -0,0 +1,402 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_nroff.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::nroff" n 0.3 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::nroff \- nroff export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::nroff ?0.3?\fR +.sp +package require \fBdoctools::text \fR +.sp +package require \fBdoctools::nroff::man_macros \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of nroff markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates nroff markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +boolean \fIinline\fR +If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output. +.sp +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. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBformat\fR, and \fBmap\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, index, nroff, serialization +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/export_text.n Index: embedded/man/files/modules/doctools2idx/export_text.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_text.n @@ -0,0 +1,386 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_text.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::text" n 0.2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::text \- plain text export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::text ?0.2?\fR +.sp +package require \fBdoctools::text \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of plain text markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates plain text markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +dictionary \fImap\fR +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. +.sp +Url references and symbolic file names without a mapping are used +unchanged. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBfile\fR, and \fBformat\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, index, plain text, serialization +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/export_wiki.n Index: embedded/man/files/modules/doctools2idx/export_wiki.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/export_wiki.n @@ -0,0 +1,399 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/export_wiki.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::export::wiki" n 0.2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::export::wiki \- wiki export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::export::wiki ?0.2?\fR +.sp +package require \fBdoctools::text \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index export plugin for +the generation of wiki markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::export\fR, the export manager. +.PP +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 +\fBdoctools::idx::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a keyword index, as +specified in section \fBKeyword index serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates wiki markup encoding the index. +The created string is then returned as the result of the command. +.PP +.SH "WIKI MARKUP" +The basic syntax of the wiki markup generated by this plugin are +described at \fIhttp://wiki.tcl.tk/14\fR. +.PP +The plugin goes beyond the classic markup to generate proper headers +and either a table or indented list of the keywords and their +references. +.SH CONFIGURATION +The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +dictionary \fImap\fR +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. +.sp +Url references and symbolic file names without a mapping are used +unchanged. +.TP +enum \fIstyle\fR +This variable recognizes two values as legal, \fBlist\fR (default), +and \fBtable\fR. +Depending on the value the plugin generates either a list- or +table-based wiki page for the index. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBfile\fR and \fBformat\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, index, serialization, wiki +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/import.n Index: embedded/man/files/modules/doctools2idx/import.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/import.n @@ -0,0 +1,719 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/import.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::import" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::import \- Importing keyword indices +.SH SYNOPSIS +package require \fBdoctools::idx::import ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::config \fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBsnit \fR +.sp +package require \fBpluginmgr \fR +.sp +\fB::doctools::idx::import\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBconfig names\fR +.sp +\fIobjectName\fR \fBconfig get\fR +.sp +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +.sp +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +.sp +\fIobjectName\fR \fBincludes\fR +.sp +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude clear\fR +.sp +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +.sp +\fBimport\fR \fItext\fR \fIconfiguration\fR +.sp +.BE +.SH 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 \fIdocidx\fR, \fIjson\fR, etc. +.PP +This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are +.IP [1] +\fIExporting keyword indices\fR, and +.IP [2] +\fIHolding keyword indices\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBKeyword index serialization format\fR. +.PP +The plugin system of our class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBDOCTOOLS_IDX_IMPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBDOCTOOLS_IDX_PLUGINS\fR, +.IP [3] +the environment variable \fBDOCTOOLS_PLUGINS\fR, +.IP [4] +the path "\fI~/.doctools/idx/import/plugin\fR" +.IP [5] +the path "\fI~/.doctools/idx/plugin\fR" +.IP [6] +the path "\fI~/.doctools/plugin\fR" +.IP [7] +the path "\fI~/.doctools/idx/import/plugins\fR" +.IP [8] +the path "\fI~/.doctools/idx/plugins\fR" +.IP [9] +the path "\fI~/.doctools/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\IDX\\IMPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\IDX\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using Windows(tm) operating system. +.PP +The whole system is delivered with two predefined import plugins, +namely +.TP +docidx +See \fIdocidx import plugin\fR for details. +.TP +json +See \fIjson import plugin\fR for details. +.PP +.PP +Readers wishing to write their own import plugin for some format, i.e. +\fIplugin writer\fRs reading and understanding the section +containing the \fBImport plugin API v2 reference\fR is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail. +.SH CONCEPTS +.IP [1] +A \fIkeyword index\fR consists of a (possibly empty) set of \fIkeywords\fR. +.IP [2] +Each keyword in the set is identified by its name. +.IP [3] +Each keyword has a (possibly empty) set of \fIreferences\fR. +.IP [4] +A reference can be associated with more than one keyword. +.IP [5] +A reference not associated with at least one keyword is not possible +however. +.IP [6] +Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (\fBurl\fR, +or \fBmanpage\fR). +.IP [7] +The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with. +.IP [8] +In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with. +.PP +A few notes +.IP [1] +Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified. +.IP [2] +Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url. +.IP [3] +While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::idx::import\fR \fIobjectName\fR +This command creates a new import manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::idx::import\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +This method takes the \fItext\fR and converts it from the specified +\fIformat\fR 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. +.sp +If no format is specified the method defaults to \fBdocidx\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBKeyword index serialization format\fR. +.sp +The plugin has to conform to the interface specified in section +\fBImport plugin API v2 reference\fR. +.TP +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into \fBimport text\fR and returns the resulting +serialization as its own result. +.TP +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBdeserialize\fR method expecting the canonical serialization of a +keyword index. +It imports the text using \fBimport text\fR and then feeds the +resulting serialization into the \fIobject\fR via \fBdeserialize\fR. +This method returns the empty string as it result. +.TP +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +This method behaves like \fBimport object text\fR, except that it +reads the text to convert from the specified file instead of being +given it as argument. +.TP +\fIobjectName\fR \fBconfig names\fR +This method returns a list containing the names of all configuration +variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig get\fR +This method returns a dictionary containing the names and values of +all configuration variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +This method sets the configuration variable \fIname\fR to the +specified \fIvalue\fR and returns the new value of the variable. +.sp +If no value is specified it simply returns the current value, without +changing it. +.sp +Note that while the user can set the predefined configuration +variables \fBuser\fR and \fBformat\fR doing so will have no +effect, these values will be internally overriden when invoking an +import plugin. +.TP +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +This method unsets all configuration variables matching the specified +glob \fIpattern\fRs. If no pattern is specified it will unset all +currently defined configuration variables. +.TP +\fIobjectName\fR \fBincludes\fR +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. +.TP +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +This methods adds the specified \fIpath\fR 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. +.sp +The method does nothing if the path is already known. +.TP +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +This methods removes the specified \fIpath\fR from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string. +.sp +The method does nothing if the path is not known. +.TP +\fIobjectName\fR \fBinclude clear\fR +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. +.PP +.SH "IMPORT PLUGIN API V2 REFERENCE" +Plugins are what this package uses to manage the support for any input +format beyond the \fBKeyword index serialization format\fR. Here +we specify the API the objects created by this package use to interact +with their plugins. +.PP +A plugin for this package has to follow the rules listed below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +doctools::idx::import::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +generate output for. This name is also the argument to provide +to the various \fBimport\fR methods of import manager +objects to get a string encoding a keyword index in that +format. +.IP [3] +The plugin can expect that the package +\fBdoctools::idx::export::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.IP [4] +The plugin can expect that a command named \fBIncludeFile\fR is +present, with the signature +.RS +.TP +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +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 \fIdocidx\fR. +.sp +The plugin has to supply the following arguments +.RS +.TP +string \fIcurrentfile\fR +The path of the file it is currently processing. This may be the empty +string if no such is known. +.TP +string \fIpath\fR +The path of the include file as specified in the include directive +being processed. +.RE +.IP +The result of the command will be a 5-element list containing +.RS +.IP [1] +A boolean flag indicating the success (\fBTrue\fR) or failure +(\fBFalse\fR) of the operation. +.IP [2] +In case of success the contents of the included file, and the +empty string otherwise. +.IP [3] +The resolved, i.e. absolute path of the included file, if +possible, or the unchanged \fIpath\fR argument. This is for +display in an error message, or as the \fIcurrentfile\fR +argument of another call to \fBIncludeFile\fR should this file +contain more files. +.IP [4] +In case of success an empty string, and for failure a code +indicating the reason for it, one of +.RS +.TP +notfound +The specified file could not be found. +.TP +notread +The specified file was found, but not be read into memory. +.RE +.IP [5] +An empty string in case of success of a \fBnotfound\fR +failure, and an additional error message describing the reason +for a \fBnotread\fR error in more detail. +.RE +.RE +.IP [5] +A plugin has to provide one command, with the signature shown +below. +.RS +.TP +\fBimport\fR \fItext\fR \fIconfiguration\fR +Whenever an import manager of \fBdoctools::idx\fR has to parse +input for an index it will invoke this command. +.RS +.TP +string \fItext\fR +This argument will contain the text encoding the index per the format +the plugin is for. +.TP +dictionary \fIconfiguration\fR +This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values. +.sp +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. +.RS +.TP +user +This variable is expected to contain the name of the user +owning the process invoking the plugin. +.TP +format +This variable is expected to contain the name of the +format whose plugin is invoked. +.RE +.RE +.RE +.IP [6] +A single usage cycle of a plugin consists of the invokations of +the command \fBimport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +conversion, docidx, documentation, import, index, json, keyword index, manpage, markup, parsing, plugin, reference, url +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/import_docidx.n Index: embedded/man/files/modules/doctools2idx/import_docidx.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/import_docidx.n @@ -0,0 +1,410 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/import_docidx.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::import::docidx" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::import::docidx \- docidx import plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::import::docidx ?0.1?\fR +.sp +package require \fBdoctools::idx::parse \fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBdoctools::msgcat \fR +.sp +package require \fBdoctools::tcl::parse \fR +.sp +package require \fBfileutil \fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBstruct::stack \fR +.sp +package require \fBstruct::tree \fR +.sp +package require \fBtreeql \fR +.sp +\fBimport\fR \fIstring\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index import plugin for +the parsing of docidx markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::import\fR, the import manager. +.PP +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 +\fBdoctools::idx::import\fR and the import manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx import plugin API version 2. +.TP +\fBimport\fR \fIstring\fR \fIconfiguration\fR +This command takes the \fIstring\fR and parses it as docidx +markup encoding a keyword index, in the context of the specified +\fIconfiguration\fR (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section \fBKeyword index serialization format\fR. +.PP +.SH "[DOCIDX] NOTATION OF KEYWORD INDICES" +The docidx format for keyword indices, also called the +\fIdocidx markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdocidx language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdocidx language syntax\fR and +.IP [2] +\fIdocidx language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +deserialization, docidx, doctools, import, index +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/import_json.n Index: embedded/man/files/modules/doctools2idx/import_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/import_json.n @@ -0,0 +1,428 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/import_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::import::json" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::import::json \- JSON import plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::import::json ?0.1?\fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBjson \fR +.sp +\fBimport\fR \fIstring\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools keyword index import plugin for +the parsing of JSON markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially \fBdoctools::idx::import\fR, the import manager. +.PP +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 +\fBdoctools::idx::import\fR and the import manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +docidx import plugin API version 2. +.TP +\fBimport\fR \fIstring\fR \fIconfiguration\fR +This command takes the \fIstring\fR and parses it as JSON +markup encoding a keyword index, in the context of the specified +\fIconfiguration\fR (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section \fBKeyword index serialization format\fR. +.PP +.SH "JSON NOTATION OF KEYWORD INDICES" +The JSON format used for keyword indices is a direct translation of +the \fBKeyword index serialization format\fR, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization +.CS + + +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 {} +} + +.CE +is equivalent to the JSON string +.CS + + +{ + "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" : "" + } +} + +.CE +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +JSON, deserialization, doctools, import, index +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/introduction.n Index: embedded/man/files/modules/doctools2idx/introduction.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/introduction.n @@ -0,0 +1,389 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/introduction.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools2idx_introduction" n 2.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools2idx_introduction \- DocTools - Keyword indices +.SH DESCRIPTION +\fIdocidx\fR (short for \fIdocumentation indices\fR) stands for a +set of related, yet different, entities which are working together for +the easy creation and transformation of keyword indices for +documentation. +.PP +These are +.IP [1] +A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands. +Beginners should start with the +\fIdocidx language introduction\fR. +The formal specification is split over two documents, one dealing with +the \fIdocidx language syntax\fR, the other a +\fIdocidx language command reference\fR. +.IP [2] +A set of packages for the programmatic manipulation of keyword indices +in memory, and their conversion between various formats, reading and +writing. The aforementioned markup language is one of the formats +which can be both read from and written to. +.IP [3] +The system for the conversion of indices is based on a plugin +mechanism, for this we have two APIs describing the interface between +the packages above and the import/export plugins. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. +.PP +.IP [1] +A \fIwriter\fR of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +\fIdocidx language introduction\fR first. Having digested this +the formal \fIdocidx language syntax\fR specification should +become understandable. A writer experienced with docidx may only +need the \fIdocidx language command reference\fR from time to +time to refresh her memory. +.sp +While a document is written the \fBdtp\fR 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 \fBdtplite\fR application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them. +.IP [2] +A \fIprocessor\fR of documentation written in the \fIdocidx\fR +markup language has to know which tools are available for use. +.sp +The main tool is the aforementioned \fBdtp\fR application provided +by Tcllib. The simpler \fBdtplite\fR 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 +.RS +.TP +\fBdoctools::idx\fR +Programmatic manipulation of keyword indices in memory. +.TP +\fBdoctools::idx::import\fR +Import of keyword indices from various textual formats. The set of +supported formats is extensible through plugin packages. +.TP +\fBdoctools::idx::export\fR +Export of keyword indices to various textual formats. The set of +supported formats is extensible through plugin packages. +.RE +.IP +See also section \fBPackage Overview\fR for an overview of the +dependencies between these and other, supporting packages. +.IP [3] +At last, but not least, \fIplugin writers\fR 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. +.RS +.IP \(bu +\fBdoctools::idx::import\fR +.IP \(bu +\fBdoctools::idx::export\fR +.RE +.PP +.SH "RELATED FORMATS" +The docidx format does not stand alone, it has two companion formats. +These are called \fIdoctoc\fR and \fIdoctools\fR, and they are +intended for the markup of \fItables of contents\fR, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the \fIDocTools - Tables Of Contents\fR and +the \fIDocTools - General\fR, respectively. +.SH "PACKAGE OVERVIEW" +.CS + + + ~~~~~~~~~~~ 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. + + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctools2doc_introduction, doctools2toc_introduction +.SH KEYWORDS +conversion, formatting, index, keyword index, markup, parsing, plugin, semantic markup +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/msgcat_c.n Index: embedded/man/files/modules/doctools2idx/msgcat_c.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/msgcat_c.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/msgcat_c.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::idx::c" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::idx::c \- Message catalog for the docidx parser (C) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::idx::c ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::idx::c\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +C, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/msgcat_de.n Index: embedded/man/files/modules/doctools2idx/msgcat_de.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/msgcat_de.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/msgcat_de.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::idx::de" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::idx::de \- Message catalog for the docidx parser (DE) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::idx::de ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::idx::de\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +DE, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/msgcat_en.n Index: embedded/man/files/modules/doctools2idx/msgcat_en.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/msgcat_en.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/msgcat_en.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::idx::en" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::idx::en \- Message catalog for the docidx parser (EN) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::idx::en ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::idx::en\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EN, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/msgcat_fr.n Index: embedded/man/files/modules/doctools2idx/msgcat_fr.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/msgcat_fr.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/msgcat_fr.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::idx::fr" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::idx::fr \- Message catalog for the docidx parser (FR) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::idx::fr ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::idx::fr\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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +FR, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/parse.n Index: embedded/man/files/modules/doctools2idx/parse.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/parse.n @@ -0,0 +1,507 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/parse.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::parse" n 1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::parse \- Parsing text in docidx format +.SH SYNOPSIS +package require \fBdoctools::idx::parse ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::idx::structure \fR +.sp +package require \fBdoctools::msgcat \fR +.sp +package require \fBdoctools::tcl::parse \fR +.sp +package require \fBfileutil \fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::stack \fR +.sp +\fB::doctools::idx::parse\fR \fBtext\fR \fItext\fR +.sp +\fB::doctools::idx::parse\fR \fBfile\fR \fIpath\fR +.sp +\fB::doctools::idx::parse\fR \fBincludes\fR +.sp +\fB::doctools::idx::parse\fR \fBinclude add\fR \fIpath\fR +.sp +\fB::doctools::idx::parse\fR \fBinclude remove\fR \fIpath\fR +.sp +\fB::doctools::idx::parse\fR \fBinclude clear\fR +.sp +\fB::doctools::idx::parse\fR \fBvars\fR +.sp +\fB::doctools::idx::parse\fR \fBvar set\fR \fIname\fR \fIvalue\fR +.sp +\fB::doctools::idx::parse\fR \fBvar unset\fR \fIname\fR +.sp +\fB::doctools::idx::parse\fR \fBvar clear\fR ?\fIpattern\fR? +.sp +.BE +.SH DESCRIPTION +This package provides commands to parse text written in the +\fIdocidx\fR markup language and convert it into the canonical +serialization of the keyword index encoded in the text. +See the section \fBKeyword index serialization format\fR for +specification of their format. +.PP +This is an internal package of doctools, for use by the higher level +packages handling \fIdocidx\fR documents. +.SH API +.TP +\fB::doctools::idx::parse\fR \fBtext\fR \fItext\fR +The command takes the string contained in \fItext\fR and parses it +under the assumption that it contains a document written using the +\fIdocidx\fR markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section \fBParse errors\fR. +.sp +When successful the command returns the canonical serialization of the +keyword index which was encoded in the text. +See the section \fBKeyword index serialization format\fR for +specification of that format. +.TP +\fB::doctools::idx::parse\fR \fBfile\fR \fIpath\fR +The same as \fBtext\fR, except that the text to parse is read from +the file specified by \fIpath\fR. +.TP +\fB::doctools::idx::parse\fR \fBincludes\fR +This method returns the current list of search paths used when looking +for include files. +.TP +\fB::doctools::idx::parse\fR \fBinclude add\fR \fIpath\fR +This method adds the \fIpath\fR 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. +.TP +\fB::doctools::idx::parse\fR \fBinclude remove\fR \fIpath\fR +This method removes the \fIpath\fR 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. +.TP +\fB::doctools::idx::parse\fR \fBinclude clear\fR +This method clears the list of search paths for include files. +.TP +\fB::doctools::idx::parse\fR \fBvars\fR +This method returns a dictionary containing the current set of +predefined variables known to the \fBvset\fR markup command during +processing. +.TP +\fB::doctools::idx::parse\fR \fBvar set\fR \fIname\fR \fIvalue\fR +This method adds the variable \fIname\fR to the set of predefined +variables known to the \fBvset\fR markup command during processing, +and gives it the specified \fIvalue\fR. The method returns the empty +string as its result. +.TP +\fB::doctools::idx::parse\fR \fBvar unset\fR \fIname\fR +This method removes the variable \fIname\fR from the set of predefined +variables known to the \fBvset\fR markup command during +processing. The method returns the empty string as its result. +.TP +\fB::doctools::idx::parse\fR \fBvar clear\fR ?\fIpattern\fR? +This method removes all variables matching the \fIpattern\fR from the +set of predefined variables known to the \fBvset\fR markup command +during processing. The method returns the empty string as its result. +.sp +The pattern matching is done with \fBstring match\fR, and the +default pattern used when none is specified, is \fB*\fR. +.PP +.SH "PARSE ERRORS" +The format of the parse error messages thrown when encountering +violations of the \fIdocidx\fR markup syntax is human readable and +not intended for processing by machines. As such it is not documented. +.PP +\fIHowever\fR, the errorCode attached to the message is +machine-readable and has the following format: +.IP [1] +The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more. +.IP [2] +Each error element will be a list containing six strings describing an +error in detail. The strings will be +.RS +.IP [1] +The path of the file the error occured in. This may be empty. +.IP [2] +The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero. +.IP [3] +The line the first character after the error is on. +Lines are counted from one. +.IP [4] +The column the first character after the error is at. +Columns are counted from zero. +.IP [5] +The message code of the error. This value can be used as argument to +\fBmsgcat::mc\fR to obtain a localized error message, assuming that +the application had a suitable call of \fBdoctools::msgcat::init\fR to +initialize the necessary message catalogs (See package +\fBdoctools::msgcat\fR). +.IP [6] +A list of details for the error, like the markup command involved. In +the case of message code \fBdocidx/include/syntax\fR this value is +the set of errors found in the included file, using the format +described here. +.RE +.PP +.SH "[DOCIDX] NOTATION OF KEYWORD INDICES" +The docidx format for keyword indices, also called the +\fIdocidx markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdocidx language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdocidx language syntax\fR and +.IP [2] +\fIdocidx language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +docidx, doctools, lexer, parser +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2idx/structure.n Index: embedded/man/files/modules/doctools2idx/structure.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2idx/structure.n @@ -0,0 +1,435 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2idx/structure.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::idx::structure" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::idx::structure \- Docidx serialization utilities +.SH SYNOPSIS +package require \fBdoctools::idx::structure ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +\fB::doctools::idx::structure\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +.sp +\fB::doctools::idx::structure\fR \fBverify-as-canonical\fR \fIserial\fR +.sp +\fB::doctools::idx::structure\fR \fBcanonicalize\fR \fIserial\fR +.sp +\fB::doctools::idx::structure\fR \fBprint\fR \fIserial\fR +.sp +\fB::doctools::idx::structure\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands to work with the serializations of +keyword indices as managed by the doctools system v2, and specified in +section \fBKeyword index serialization format\fR. +.PP +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 \fIdocidx\fR +markup. +.SH API +.TP +\fB::doctools::idx::structure\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +This command verifies that the content of \fIserial\fR is a valid +\fIregular\fR 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. +.sp +If the argument \fIcanonvar\fR 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 \fIserial\fR is a valid regular +serialization. Its value will be a boolean, with \fBTrue\fR +indicating that the serialization is not only valid, but also +\fIcanonical\fR. \fBFalse\fR will be written for a valid, but +non-canonical serialization. +.sp +For the specification of regular and canonical keyword index +serializations see the section +\fBKeyword index serialization format\fR. +.TP +\fB::doctools::idx::structure\fR \fBverify-as-canonical\fR \fIserial\fR +This command verifies that the content of \fIserial\fR is a valid +\fIcanonical\fR 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. +.sp +For the specification of canonical keyword index serializations see +the section \fBKeyword index serialization format\fR. +.TP +\fB::doctools::idx::structure\fR \fBcanonicalize\fR \fIserial\fR +This command assumes that the content of \fIserial\fR is a valid +\fIregular\fR serialization of a keyword index and will throw an +error if that is not the case. +.sp +It will then convert the input into the \fIcanonical\fR serialization +of the contained keyword index and return it as its result. If the +input is already canonical it will be returned unchanged. +.sp +For the specification of regular and canonical keyword index +serializations see the section +\fBKeyword index serialization format\fR. +.TP +\fB::doctools::idx::structure\fR \fBprint\fR \fIserial\fR +This command assumes that the argument \fIserial\fR contains a valid +regular serialization of a keyword index and returns a string +containing that index in a human readable form. +.sp +The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities. +.sp +For the specification of regular keyword index serializations see the +section \fBKeyword index serialization format\fR. +.TP +\fB::doctools::idx::structure\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +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. +.sp +Title and label of the resulting index are taken from the index +contained in \fIserialb\fR. The set of keys, references and their +connections is the union of the set of keys and references of the two +inputs. +.sp +For the specification of regular and canonical keyword index +serializations see the section +\fBKeyword index serialization format\fR. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +An index serialization is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::idx\fR, and its +value. This value holds the contents of the index. +.IP [3] +The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the index. +.TP +\fBlabel\fR +The value is a string containing a label for the index. +.TP +\fBkeywords\fR +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. +.sp +Any reference identifier used in these lists has to exist as a key in +the \fBreferences\fR dictionary, see the next item for its +definition. +.TP +\fBreferences\fR +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. +.sp +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 \fBkeywords\fR dictionary, see previous item for its +definition. +.RE +.IP [4] +The \fItype\fR of a reference can be one of two values, +.RS +.TP +\fBmanpage\fR +The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for. +.TP +\fBurl\fR +The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc. +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their \fIlabels\fR, as +generated by Tcl's builtin command \fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +deserialization, docidx, doctools, serialization +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/container.n Index: embedded/man/files/modules/doctools2toc/container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/container.n @@ -0,0 +1,709 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc" n 2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc \- Holding tables of contents +.SH SYNOPSIS +package require \fBdoctools::toc ?2?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBstruct::tree \fR +.sp +package require \fBsnit \fR +.sp +\fB::doctools::toc\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fB+ reference\fR \fIid\fR \fIlabel\fR \fIdocid\fR \fIdesc\fR +.sp +\fIobjectName\fR \fB+ division\fR \fIid\fR \fIlabel\fR ?\fIdocid\fR? +.sp +\fIobjectName\fR \fBremove\fR \fIid\fR +.sp +\fIobjectName\fR \fBup\fR \fIid\fR +.sp +\fIobjectName\fR \fBnext\fR \fIid\fR +.sp +\fIobjectName\fR \fBprev\fR \fIid\fR +.sp +\fIobjectName\fR \fBchild\fR \fIid\fR \fIlabel\fR ?\fI...\fR? +.sp +\fIobjectName\fR \fBelement\fR ?\fI...\fR? +.sp +\fIobjectName\fR \fBchildren\fR \fIid\fR +.sp +\fIobjectName\fR \fBtype\fR \fIid\fR +.sp +\fIobjectName\fR \fBfull-label\fR \fIid\fR +.sp +\fIobjectName\fR \fBelabel\fR \fIid\fR ?\fInewlabel\fR? +.sp +\fIobjectName\fR \fBdescription\fR \fIid\fR ?\fInewdesc\fR? +.sp +\fIobjectName\fR \fBdocument\fR \fIid\fR ?\fInewdocid\fR? +.sp +\fIobjectName\fR \fBtitle\fR +.sp +\fIobjectName\fR \fBtitle\fR \fItext\fR +.sp +\fIobjectName\fR \fBlabel\fR +.sp +\fIobjectName\fR \fBlabel\fR \fItext\fR +.sp +\fIobjectName\fR \fBimporter\fR +.sp +\fIobjectName\fR \fBimporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fBexporter\fR +.sp +\fIobjectName\fR \fBexporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +.sp +.BE +.SH DESCRIPTION +This package provides a class to contain and programmatically +manipulate tables of contents. +.PP +This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are +.IP [1] +\fIExporting tables of contents\fR, and +.IP [2] +\fIImporting tables of contents\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBToC serialization format\fR. +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. +.SH CONCEPTS +.IP [1] +A \fItable of contents\fR consists of a (possibly empty) list of +\fIelements\fR. +.IP [2] +Each element in the list is identified by its label. +.IP [3] +Each element is either a \fIreference\fR, or a \fIdivision\fR. +.IP [4] +Each reference has an associated document, identified by a symbolic +id, and a textual description. +.IP [5] +Each division may have an associated document, identified by a +symbolic id. +.IP [6] +Each division consists consists of a (possibly empty) list of +\fIelements\fR, with each element following the rules as specified in +item 2 and above. +.PP +A few notes +.IP [1] +The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents. +.IP [2] +The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::toc\fR \fIobjectName\fR +This command creates a new container object with an associated Tcl +command whose name is \fIobjectName\fR. This \fIobject\fR command is +explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::toc\fR command have the +following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fB+ reference\fR \fIid\fR \fIlabel\fR \fIdocid\fR \fIdesc\fR +This method adds a new reference element to the table of contents, +under the element specified via its handle \fIid\fR. 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 \fIlabel\fR, +which has to be be unique within the parent element. An error is +thrown otherwise. +.sp +As a reference element it will refer to a document identified by the +symbolic \fIdocid\fR. 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 \fIdesc\fR. +.sp +The result of the method is the handle (id) of the new element. +.TP +\fIobjectName\fR \fB+ division\fR \fIid\fR \fIlabel\fR ?\fIdocid\fR? +This method adds a new division element to the table of contents, +under the element specified via its handle \fIid\fR. 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 \fIlabel\fR, +which has to be be unique within the parent element. An error is +thrown otherwise. +.sp +As a division element it is can refer to a document, identified by the +symbolic \fIdocid\fR, but may choose not to. +.sp +The result of the method is the handle (id) of the new element. +.TP +\fIobjectName\fR \fBremove\fR \fIid\fR +This method removes the element identified by the handle \fIid\fR 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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBup\fR \fIid\fR +This method returns the handle of the parent for the element +identified by its handle \fIid\fR, or the empty string if \fIid\fR +refered to the root element. +.TP +\fIobjectName\fR \fBnext\fR \fIid\fR +This method returns the handle of the right sibling for the element +identified by its handle \fIid\fR, or the handle of the parent if the +element has no right sibling, or the empty string if \fIid\fR refered +to the root element. +.TP +\fIobjectName\fR \fBprev\fR \fIid\fR +This method returns the handle of the left sibling for the element +identified by its handle \fIid\fR, or the handle of the parent if the +element has no left sibling, or the empty string if \fIid\fR refered +to the root element. +.TP +\fIobjectName\fR \fBchild\fR \fIid\fR \fIlabel\fR ?\fI...\fR? +This method returns the handle of a child of the element identified by +its handle \fIid\fR. The child itself is identified by a series of +labels. +.TP +\fIobjectName\fR \fBelement\fR ?\fI...\fR? +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. +.TP +\fIobjectName\fR \fBchildren\fR \fIid\fR +This method returns a list containing the handles of all children of +the element identified by the handle \fIid\fR, from first to last, in +that order. +.TP +\fIobjectName\fR \fBtype\fR \fIid\fR +This method returns the type of the element, either \fBreference\fR, +or \fBdivision\fR. +.TP +\fIobjectName\fR \fBfull-label\fR \fIid\fR +This method is the complement of the method \fBelement\fR, +converting the handle \fIid\fR of an element into a list of labels +full identifying the element within the whole table of contents. +.TP +\fIobjectName\fR \fBelabel\fR \fIid\fR ?\fInewlabel\fR? +This method queries and/or changes the label of the element identified +by the handle \fIid\fR. If the argument \fInewlabel\fR 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. +.sp +If the label is changed the new label has to be unique within the +containing division, or an error is thrown. +.sp +Further, of the \fIid\fR refers to the root element of the table of +contents, then using this method is equivalent to using the method +\fIlabel\fR, i.e. it is accessing the global label for the whole +table. +.TP +\fIobjectName\fR \fBdescription\fR \fIid\fR ?\fInewdesc\fR? +This method queries and/or changes the description of the element +identified by the handle \fIid\fR. If the argument \fInewdesc\fR 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. +.sp +The element this method operates on has to be a reference element, or +an error will be thrown. +.TP +\fIobjectName\fR \fBdocument\fR \fIid\fR ?\fInewdocid\fR? +This method queries and/or changes the document reference of the +element identified by the handle \fIid\fR. +If the argument \fInewdocid\fR 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. +.sp +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. +.TP +\fIobjectName\fR \fBtitle\fR +Returns the currently defined title of the table of contents. +.TP +\fIobjectName\fR \fBtitle\fR \fItext\fR +Sets the title of the table of contents to \fItext\fR, and returns it as +the result of the command. +.TP +\fIobjectName\fR \fBlabel\fR +Returns the currently defined label of the table of contents. +.TP +\fIobjectName\fR \fBlabel\fR \fItext\fR +Sets the label of the table of contents to \fItext\fR, and returns it as +the result of the command. +.TP +\fIobjectName\fR \fBimporter\fR +Returns the import manager object currently attached to the container, +if any. +.TP +\fIobjectName\fR \fBimporter\fR \fIobject\fR +Attaches the \fIobject\fR as import manager to the container, and +returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBimport text\fR 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. +.TP +\fIobjectName\fR \fBexporter\fR +Returns the export manager object currently attached to the container, +if any. +.TP +\fIobjectName\fR \fBexporter\fR \fIobject\fR +Attaches the \fIobject\fR as export manager to the container, and +returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBexport object\fR 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 \fIobject\fR will +use the container's method \fBserialize\fR to obtain the +serialization of the table of contents from which to generate the text. +.TP +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +This method replaces the contents of the table object with the table +contained in the \fIdata\fR. If no \fIformat\fR was specified it is +assumed to be the regular serialization of a table of contents. +.sp +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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +This method behaves like \fBdeserialize =\fR in its essentials, +except that it merges the table of contents in the \fIdata\fR 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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +This method returns the table of contents contained in the object. If no +\fIformat\fR is not specified the returned result is the canonical +serialization of its contents. +.sp +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. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, TMML, conversion, doctoc markup, documentation, formatting, generation, json, latex, markup, nroff, parsing, plugin, reference, table, table of contents, tcler's wiki, text, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export.n Index: embedded/man/files/modules/doctools2toc/export.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export.n @@ -0,0 +1,657 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export \- Exporting tables of contents +.SH SYNOPSIS +package require \fBdoctools::toc::export ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::config \fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBsnit \fR +.sp +package require \fBpluginmgr \fR +.sp +\fB::doctools::toc::export\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBconfig names\fR +.sp +\fIobjectName\fR \fBconfig get\fR +.sp +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +.sp +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH 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 \fIdoctoc\fR, \fIHTML\fR, etc. +.PP +This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are +.IP [1] +\fIImporting tables of contents\fR, and +.IP [2] +\fIHolding tables of contents\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBToC serialization format\fR. +.PP +The plugin system of our class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBDOCTOOLS_TOC_EXPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBDOCTOOLS_TOC_PLUGINS\fR, +.IP [3] +the environment variable \fBDOCTOOLS_PLUGINS\fR, +.IP [4] +the path "\fI~/.doctools/toc/export/plugin\fR" +.IP [5] +the path "\fI~/.doctools/toc/plugin\fR" +.IP [6] +the path "\fI~/.doctools/plugin\fR" +.IP [7] +the path "\fI~/.doctools/toc/export/plugins\fR" +.IP [8] +the path "\fI~/.doctools/toc/plugins\fR" +.IP [9] +the path "\fI~/.doctools/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\TOC\\EXPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\TOC\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using Windows(tm) operating system. +.PP +The whole system is delivered with six predefined export plugins, +namely +.TP +doctoc +See \fIdoctoc export plugin\fR for details. +.TP +html +See \fIhtml export plugin\fR for details. +.TP +json +See \fIjson export plugin\fR for details. +.TP +nroff +See \fInroff export plugin\fR for details. +.TP +text +See \fItext export plugin\fR for details. +.TP +wiki +See \fIwiki export plugin\fR for details. +.PP +.PP +Readers wishing to write their own export plugin for some format, i.e. +\fIplugin writer\fRs reading and understanding the section +containing the \fBExport plugin API v2 reference\fR is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail. +.SH CONCEPTS +.IP [1] +A \fItable of contents\fR consists of a (possibly empty) list of +\fIelements\fR. +.IP [2] +Each element in the list is identified by its label. +.IP [3] +Each element is either a \fIreference\fR, or a \fIdivision\fR. +.IP [4] +Each reference has an associated document, identified by a symbolic +id, and a textual description. +.IP [5] +Each division may have an associated document, identified by a +symbolic id. +.IP [6] +Each division consists consists of a (possibly empty) list of +\fIelements\fR, with each element following the rules as specified in +item 2 and above. +.PP +A few notes +.IP [1] +The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents. +.IP [2] +The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::toc::export\fR \fIobjectName\fR +This command creates a new export manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::toc::export\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +This method takes the canonical serialization of a table of contents +stored in \fIserial\fR and converts it to the specified \fIformat\fR, +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. +.sp +If no format is specified the method defaults to \fBdoctoc\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBToC serialization format\fR. +.sp +The plugin has to conform to the interface specified in section +\fBExport plugin API v2 reference\fR. +.TP +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBexport serial\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBserialize\fR method returning the canonical serialization of a +table of contents. It invokes that method, feeds the result into +\fBexport serial\fR and returns the resulting string as its own +result. +.TP +\fIobjectName\fR \fBconfig names\fR +This method returns a list containing the names of all configuration +variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig get\fR +This method returns a dictionary containing the names and values of +all configuration variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +This method sets the configuration variable \fIname\fR to the +specified \fIvalue\fR and returns the new value of the variable. +.sp +If no value is specified it simply returns the current value, without +changing it. +.sp +Note that while the user can set the predefined configuration +variables \fBuser\fR and \fBformat\fR doing so will have no +effect, these values will be internally overriden when invoking an +import plugin. +.TP +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +This method unsets all configuration variables matching the specified +glob \fIpattern\fRs. If no pattern is specified it will unset all +currently defined configuration variables. +.PP +.SH "EXPORT PLUGIN API V2 REFERENCE" +Plugins are what this package uses to manage the support for any +output format beyond the \fBToC serialization format\fR. Here we +specify the API the objects created by this package use to interact +with their plugins. +.PP +A plugin for this package has to follow the rules listed below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +doctools::toc::export::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +generate output for. This name is also the argument to provide +to the various \fBexport\fR methods of export manager +objects to get a string encoding a table of contents in that +format. +.IP [3] +The plugin can expect that the package +\fBdoctools::toc::export::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.IP [4] +A plugin has to provide one command, with the signature shown +below. +.RS +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +Whenever an export manager of \fBdoctools::toc\fR has to generate +output for a table of contents it will invoke this command. +.RS +.TP +string \fIserial\fR +This argument will contain the \fIcanonical\fR serialization of the +table of contents for which to generate the output. +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBToC serialization format\fR. +.TP +dictionary \fIconfiguration\fR +This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values. +.sp +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. +.RS +.TP +user +This variable is expected to contain the name of the user +owning the process invoking the plugin. +.TP +format +This variable is expected to contain the name of the +format whose plugin is invoked. +.TP +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. +.TP +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. +.RE +.RE +.RE +.IP [5] +A single usage cycle of a plugin consists of the invokations of +the command \fBexport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, conversion, doctoc, documentation, export, formatting, generation, json, manpage, markup, nroff, plugin, reference, table, table of contents, tcler's wiki, text, url, wiki +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_doctoc.n Index: embedded/man/files/modules/doctools2toc/export_doctoc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_doctoc.n @@ -0,0 +1,461 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_doctoc.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::doctoc" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::doctoc \- doctoc export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::doctoc ?0.1?\fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of doctoc markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates doctoc markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH "[DOCTOC] NOTATION OF TABLES OF CONTENTS" +The doctoc format for tables of contents, also called the +\fIdoctoc markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdoctoc language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdoctoc language syntax\fR and +.IP [2] +\fIdoctoc language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH CONFIGURATION +The doctoc export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +boolean \fInewlines\fR +If this flag is set the plugin will break the generated doctoc code +across lines, with each markup command on a separate line. +.sp +If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements. +.TP +boolean \fIindented\fR +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 \fBnewlines\fR is set. This effect is +independent of the value for \fBaligned\fR however. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBnewlines\fR, and no indenting is done. +.TP +boolean \fIaligned\fR +If this flag is set the generator ensures that the arguments for the +\fBitem\fR commands in a division are aligned vertically for a nice +table effect. To make this work this also implies that \fBnewlines\fR +is set. This effect is independent of the value for \fBindented\fR +however. +.sp +If this flag is not set (the default), the output is formatted as per +the values of \fBnewlines\fR and \fBindented\fR, and no alignment is +done. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBformat\fR, and \fBmap\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctoc, doctools, export, serialization, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_html.n Index: embedded/man/files/modules/doctools2toc/export_html.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_html.n @@ -0,0 +1,511 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_html.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::html" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::html \- HTML export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::html ?0.1?\fR +.sp +package require \fBdoctools::text \fR +.sp +package require \fBdoctools::html \fR +.sp +package require \fBdoctools::html::cssdefaults \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of HTML markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates HTML markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +dictionary \fImap\fR +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. +.sp +Document ids without a mapping are used unchanged. +.TP +boolean \fInewlines\fR +If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line. +.sp +If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements. +.TP +boolean \fIindented\fR +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 \fBnewlines\fR is set. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBnewlines\fR, and no indenting is done. +.TP +string \fImeta\fR +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. +.TP +string \fIheader\fR +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. +.TP +string \fIfooter\fR +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. +.TP +dictionary \fIrid\fR +The value of this variable (default: empty) maps references to the +identifiers to use as their anchor names. Each reference \fBFOO\fR not +found in the dictionary uses \fBREF-\fR\fBFOO\fR as anchor, +i.e. itself prefixed with the string \fBREF-\fR. +.TP +string \fIsepline\fR +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. +.TP +string \fIclass.main\fR +This variable contains the class name for the main <div>'ivision of +the generated document. The default is \fBdoctools\fR. +.TP +string \fIclass.header\fR +This variable contains the class name for the header <div>'ision of +the generated document. The default is \fBtoc-header\fR. This +division contains the document title, the user specified \fBheader\fR, +if any, and a visible separator line. +.TP +string \fIclass.title\fR +This variable contains the class name for the <h1> tag enclosing the +document title. The default is \fBtoc-title\fR. +.TP +string \fIclass.navsep\fR +This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +\fBtoc-navsep\fR. +.TP +string \fIclass.contents\fR +This variable contains the class name for the XXXXX holding the +keywords and their references in the generated document. The default +is \fBtoc-contents\fR. +.TP +string \fIclass.ref\fR +This variable contains the class name for the table elements which are +references to other documents. The default is \fBtoc-ref\fR. +.TP +string \fIclass.div\fR +This variable contains the class name for the table elements which are +divisions. The default is \fBtoc-div\fR. +.TP +string \fIclass.footer\fR +This variable contains the class name for the footer <div>'ision of +the generated document. The default is \fBtoc-footer\fR. This +division contains a browser-visible separator line and the user +specified \fBfooter\fR, if any. +.PP +\fINote\fR that this plugin ignores the standard configuration +variable \fBformat\fR, and its value. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +HTML, doctools, export, serialization, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_json.n Index: embedded/man/files/modules/doctools2toc/export_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_json.n @@ -0,0 +1,499 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::json" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::json \- JSON export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::json ?0.1?\fR +.sp +package require \fBtextutil::adjust \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of JSON markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates JSON markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH "JSON NOTATION OF TABLES OF CONTENTS" +The JSON format used for tables of contents is a direct translation of +the \fBToC serialization format\fR, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization +.CS + + +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 +} + +.CE +is equivalent to the JSON string +.CS + + +{ + "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" + } +} + +.CE +.SH CONFIGURATION +The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +boolean \fIindented\fR +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. +.sp +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. +.TP +boolean \fIaligned\fR +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 \fBindented\fR +is set. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBindented\fR, without trying to align the values for +dictionary keys. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBformat\fR, \fBfile\fR, and \fBmap\fR and +their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +JSON, doctools, export, serialization, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_nroff.n Index: embedded/man/files/modules/doctools2toc/export_nroff.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_nroff.n @@ -0,0 +1,430 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_nroff.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::nroff" n 0.2 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::nroff \- nroff export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::nroff ?0.2?\fR +.sp +package require \fBdoctools::text \fR +.sp +package require \fBdoctools::nroff::man_macros \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of nroff markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates nroff markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fIuser\fR +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. +.TP +string \fIfile\fR +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. +.TP +boolean \fIinline\fR +If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output. +.sp +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. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBformat\fR, and \fBmap\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, nroff, serialization, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_text.n Index: embedded/man/files/modules/doctools2toc/export_text.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_text.n @@ -0,0 +1,413 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_text.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::text" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::text \- plain text export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::text ?0.1?\fR +.sp +package require \fBdoctools::text \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of plain text markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates plain text markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +dictionary \fImap\fR +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. +.sp +Document ids without a mapping are used unchanged. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBfile\fR, and \fBformat\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, plain text, serialization, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/export_wiki.n Index: embedded/man/files/modules/doctools2toc/export_wiki.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/export_wiki.n @@ -0,0 +1,419 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/export_wiki.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::export::wiki" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::export::wiki \- wiki export plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::export::wiki ?0.1?\fR +.sp +package require \fBdoctools::text \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents export plugin +for the generation of wiki markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::export\fR, the export manager. +.PP +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 +\fBdoctools::toc::export\fR and the export manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc export plugin API version 2. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a table of contents, +as specified in section \fBToC serialization format\fR, and +contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, and +generates wiki markup encoding the table. +The created string is then returned as the result of the command. +.PP +.SH "WIKI MARKUP" +The basic syntax of the wiki markup generated by this plugin are +described at \fIhttp://wiki.tcl.tk/14\fR. +.PP +The plugin goes beyond the classic markup to generate proper headers +and indenting. +.SH CONFIGURATION +The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +dictionary \fImap\fR +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. +.sp +Document ids without a mapping are used unchanged. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBfile\fR and \fBformat\fR, and their values. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctools, export, serialization, table of contents, toc, wiki +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/import.n Index: embedded/man/files/modules/doctools2toc/import.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/import.n @@ -0,0 +1,738 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/import.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::import" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::import \- Importing keyword indices +.SH SYNOPSIS +package require \fBdoctools::toc::import ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::config \fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBsnit \fR +.sp +package require \fBpluginmgr \fR +.sp +\fB::doctools::toc::import\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBconfig names\fR +.sp +\fIobjectName\fR \fBconfig get\fR +.sp +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +.sp +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +.sp +\fIobjectName\fR \fBincludes\fR +.sp +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude clear\fR +.sp +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +.sp +\fBimport\fR \fItext\fR \fIconfiguration\fR +.sp +.BE +.SH 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 \fIdoctoc\fR, \fIjson\fR, etc. +.PP +This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are +.IP [1] +\fIExporting tables of contents\fR, and +.IP [2] +\fIHolding tables of contents\fR +.PP +.PP +For information about the \fBConcepts\fR 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 +\fBToC serialization format\fR. +.PP +The plugin system of our class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBDOCTOOLS_TOC_IMPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBDOCTOOLS_TOC_PLUGINS\fR, +.IP [3] +the environment variable \fBDOCTOOLS_PLUGINS\fR, +.IP [4] +the path "\fI~/.doctools/toc/import/plugin\fR" +.IP [5] +the path "\fI~/.doctools/toc/plugin\fR" +.IP [6] +the path "\fI~/.doctools/plugin\fR" +.IP [7] +the path "\fI~/.doctools/toc/import/plugins\fR" +.IP [8] +the path "\fI~/.doctools/toc/plugins\fR" +.IP [9] +the path "\fI~/.doctools/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\TOC\\IMPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\TOC\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using Windows(tm) operating system. +.PP +The whole system is delivered with two predefined import plugins, +namely +.TP +doctoc +See \fIdoctoc import plugin\fR for details. +.TP +json +See \fIjson import plugin\fR for details. +.PP +.PP +Readers wishing to write their own import plugin for some format, i.e. +\fIplugin writer\fRs reading and understanding the section +containing the \fBImport plugin API v2 reference\fR is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail. +.SH CONCEPTS +.IP [1] +A \fItable of contents\fR consists of a (possibly empty) list of +\fIelements\fR. +.IP [2] +Each element in the list is identified by its label. +.IP [3] +Each element is either a \fIreference\fR, or a \fIdivision\fR. +.IP [4] +Each reference has an associated document, identified by a symbolic +id, and a textual description. +.IP [5] +Each division may have an associated document, identified by a +symbolic id. +.IP [6] +Each division consists consists of a (possibly empty) list of +\fIelements\fR, with each element following the rules as specified in +item 2 and above. +.PP +A few notes +.IP [1] +The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents. +.IP [2] +The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E. +.PP +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::doctools::toc::import\fR \fIobjectName\fR +This command creates a new import manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::doctools::toc::import\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +This method takes the \fItext\fR and converts it from the specified +\fIformat\fR 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. +.sp +If no format is specified the method defaults to \fBdoctoc\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBToC serialization format\fR. +.sp +The plugin has to conform to the interface specified in section +\fBImport plugin API v2 reference\fR. +.TP +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into \fBimport text\fR and returns the resulting +serialization as its own result. +.TP +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBdeserialize\fR method expecting the canonical serialization of a +table of contents. +It imports the text using \fBimport text\fR and then feeds the +resulting serialization into the \fIobject\fR via \fBdeserialize\fR. +This method returns the empty string as it result. +.TP +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +This method behaves like \fBimport object text\fR, except that it +reads the text to convert from the specified file instead of being +given it as argument. +.TP +\fIobjectName\fR \fBconfig names\fR +This method returns a list containing the names of all configuration +variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig get\fR +This method returns a dictionary containing the names and values of +all configuration variables currently known to the object. +.TP +\fIobjectName\fR \fBconfig set\fR \fIname\fR ?\fIvalue\fR? +This method sets the configuration variable \fIname\fR to the +specified \fIvalue\fR and returns the new value of the variable. +.sp +If no value is specified it simply returns the current value, without +changing it. +.sp +Note that while the user can set the predefined configuration +variables \fBuser\fR and \fBformat\fR doing so will have no +effect, these values will be internally overriden when invoking an +import plugin. +.TP +\fIobjectName\fR \fBconfig unset\fR \fIpattern\fR... +This method unsets all configuration variables matching the specified +glob \fIpattern\fRs. If no pattern is specified it will unset all +currently defined configuration variables. +.TP +\fIobjectName\fR \fBincludes\fR +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. +.TP +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +This methods adds the specified \fIpath\fR 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. +.sp +The method does nothing if the path is already known. +.TP +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +This methods removes the specified \fIpath\fR from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string. +.sp +The method does nothing if the path is not known. +.TP +\fIobjectName\fR \fBinclude clear\fR +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. +.PP +.SH "IMPORT PLUGIN API V2 REFERENCE" +Plugins are what this package uses to manage the support for any input +format beyond the \fBToC serialization format\fR. Here we +specify the API the objects created by this package use to interact +with their plugins. +.PP +A plugin for this package has to follow the rules listed below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +doctools::toc::import::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +generate output for. This name is also the argument to provide +to the various \fBimport\fR methods of import manager +objects to get a string encoding a table of contents in that +format. +.IP [3] +The plugin can expect that the package +\fBdoctools::toc::export::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.IP [4] +The plugin can expect that a command named \fBIncludeFile\fR is +present, with the signature +.RS +.TP +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +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 \fIdoctoc\fR. +.sp +The plugin has to supply the following arguments +.RS +.TP +string \fIcurrentfile\fR +The path of the file it is currently processing. This may be the empty +string if no such is known. +.TP +string \fIpath\fR +The path of the include file as specified in the include directive +being processed. +.RE +.IP +The result of the command will be a 5-element list containing +.RS +.IP [1] +A boolean flag indicating the success (\fBTrue\fR) or failure +(\fBFalse\fR) of the operation. +.IP [2] +In case of success the contents of the included file, and the +empty string otherwise. +.IP [3] +The resolved, i.e. absolute path of the included file, if +possible, or the unchanged \fIpath\fR argument. This is for +display in an error message, or as the \fIcurrentfile\fR +argument of another call to \fBIncludeFile\fR should this file +contain more files. +.IP [4] +In case of success an empty string, and for failure a code +indicating the reason for it, one of +.RS +.TP +notfound +The specified file could not be found. +.TP +notread +The specified file was found, but not be read into memory. +.RE +.IP [5] +An empty string in case of success of a \fBnotfound\fR +failure, and an additional error message describing the reason +for a \fBnotread\fR error in more detail. +.RE +.RE +.IP [5] +A plugin has to provide one command, with the signature shown +below. +.RS +.TP +\fBimport\fR \fItext\fR \fIconfiguration\fR +Whenever an import manager of \fBdoctools::toc\fR has to parse +input for a table of contents it will invoke this command. +.RS +.TP +string \fItext\fR +This argument will contain the text encoding the table of contents per +the format the plugin is for. +.TP +dictionary \fIconfiguration\fR +This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values. +.sp +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. +.RS +.TP +user +This variable is expected to contain the name of the user +owning the process invoking the plugin. +.TP +format +This variable is expected to contain the name of the +format whose plugin is invoked. +.RE +.RE +.RE +.IP [6] +A single usage cycle of a plugin consists of the invokations of +the command \fBimport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +conversion, doctoc, documentation, import, json, manpage, markup, parsing, plugin, reference, table, table of contents, url +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/import_doctoc.n Index: embedded/man/files/modules/doctools2toc/import_doctoc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/import_doctoc.n @@ -0,0 +1,438 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/import_doctoc.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::import::doctoc" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::import::doctoc \- doctoc import plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::import::doctoc ?0.1?\fR +.sp +package require \fBdoctools::toc::parse \fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBdoctools::msgcat \fR +.sp +package require \fBdoctools::tcl::parse \fR +.sp +package require \fBfileutil \fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBstruct::stack \fR +.sp +package require \fBstruct::tree \fR +.sp +package require \fBtreeql \fR +.sp +\fBimport\fR \fIstring\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents import plugin +for the parsing of doctoc markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::import\fR, the import manager. +.PP +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 +\fBdoctools::toc::import\fR and the import manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc import plugin API version 2. +.TP +\fBimport\fR \fIstring\fR \fIconfiguration\fR +This command takes the \fIstring\fR and parses it as doctoc +markup encoding a table of contents, in the context of the specified +\fIconfiguration\fR (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section \fBToC serialization format\fR. +.PP +.SH "[DOCTOC] NOTATION OF TABLES OF CONTENTS" +The doctoc format for tables of contents, also called the +\fIdoctoc markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdoctoc language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdoctoc language syntax\fR and +.IP [2] +\fIdoctoc language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +deserialization, doctoc, doctools, import, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/import_json.n Index: embedded/man/files/modules/doctools2toc/import_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/import_json.n @@ -0,0 +1,476 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/import_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::import::json" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::import::json \- JSON import plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::import::json ?0.1?\fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBjson \fR +.sp +\fBimport\fR \fIstring\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +This package implements the doctools table of contents import plugin +for the parsing of JSON markup. +.PP +This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially \fBdoctools::toc::import\fR, the import manager. +.PP +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 +\fBdoctools::toc::import\fR and the import manager objects it +provides. +.SH API +The API provided by this package satisfies the specification of the +doctoc import plugin API version 2. +.TP +\fBimport\fR \fIstring\fR \fIconfiguration\fR +This command takes the \fIstring\fR and parses it as JSON +markup encoding a table of contents, in the context of the specified +\fIconfiguration\fR (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section \fBToC serialization format\fR. +.PP +.SH "JSON NOTATION OF TABLES OF CONTENTS" +The JSON format used for tables of contents is a direct translation of +the \fBToC serialization format\fR, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization +.CS + + +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 +} + +.CE +is equivalent to the JSON string +.CS + + +{ + "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" + } +} + +.CE +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +JSON, deserialization, doctools, import, table of contents, toc +.SH CATEGORY +Text formatter plugin +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/introduction.n Index: embedded/man/files/modules/doctools2toc/introduction.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/introduction.n @@ -0,0 +1,389 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/introduction.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools2toc_introduction" n 2.0 tcllib "Documentation tools" +.BS +.SH NAME +doctools2toc_introduction \- DocTools - Tables of Contents +.SH DESCRIPTION +\fIdoctoc\fR (short for \fIdocumentation tables of contents\fR) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables and +contents for documentation. +.PP +These are +.IP [1] +A tcl based language for the semantic markup of a table of contents. +Markup is represented by Tcl commands. +Beginners should start with the +\fIdoctoc language introduction\fR. +The formal specification is split over two documents, one dealing with +the \fIdoctoc language syntax\fR, the other a +\fIdoctoc language command reference\fR. +.IP [2] +A set of packages for the programmatic manipulation of tables of +contents in memory, and their conversion between various formats, +reading and writing. The aforementioned markup language is one of the +formats which can be both read from and written to. +.IP [3] +The system for the conversion of tables of contents is based on a +plugin mechanism, for this we have two APIs describing the interface +between the packages above and the import/export plugins. +.PP +.PP +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. +.PP +.IP [1] +A \fIwriter\fR of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +\fIdoctoc language introduction\fR first. Having digested this +the formal \fIdoctoc language syntax\fR specification should +become understandable. A writer experienced with doctoc may only +need the \fIdoctoc language command reference\fR from time to +time to refresh her memory. +.sp +While a document is written the \fBdtp\fR 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 \fBdtplite\fR application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them. +.IP [2] +A \fIprocessor\fR of documentation written in the \fIdoctoc\fR +markup language has to know which tools are available for use. +.sp +The main tool is the aforementioned \fBdtp\fR application provided +by Tcllib. The simpler \fBdtplite\fR 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 +.RS +.TP +\fBdoctoools::toc\fR +Programmatic manipulation of tables of contents in memory. +.TP +\fBdoctoools::toc::import\fR +Import of tables of contents from various textual formats. The set of +supported formats is extensible through plugin packages. +.TP +\fBdoctoools::toc::export\fR +Export of tables of contents to various textual formats. The set of +supported formats is extensible through plugin packages. +.RE +.IP +See also section \fBPackage Overview\fR for an overview of the +dependencies between these and other, supporting packages. +.IP [3] +At last, but not least, \fIplugin writers\fR 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. +.RS +.IP \(bu +\fBdoctoools::toc::import\fR +.IP \(bu +\fBdoctoools::toc::export\fR +.RE +.PP +.SH "RELATED FORMATS" +The doctoc format does not stand alone, it has two companion formats. +These are called \fIdocidx\fR and \fIdoctools\fR, and they are +intended for the markup of \fIkeyword indices\fR, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the \fIDocTools - Keyword Indices\fR and +the \fIDocTools - General\fR, respectively. +.SH "PACKAGE OVERVIEW" +.CS + + + ~~~~~~~~~~~ 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. + + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +doctools2doc_introduction, doctools2idx_introduction +.SH KEYWORDS +contents, conversion, formatting, markup, parsing, plugin, semantic markup, table of contents +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/msgcat_c.n Index: embedded/man/files/modules/doctools2toc/msgcat_c.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/msgcat_c.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/msgcat_c.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::toc::c" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::toc::c \- Message catalog for the doctoc parser (C) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::toc::c ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::toc::c\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +C, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/msgcat_de.n Index: embedded/man/files/modules/doctools2toc/msgcat_de.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/msgcat_de.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/msgcat_de.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::toc::de" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::toc::de \- Message catalog for the doctoc parser (DE) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::toc::de ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::toc::de\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +DE, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/msgcat_en.n Index: embedded/man/files/modules/doctools2toc/msgcat_en.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/msgcat_en.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/msgcat_en.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::toc::en" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::toc::en \- Message catalog for the doctoc parser (EN) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::toc::en ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::toc::en\fR 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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EN, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/msgcat_fr.n Index: embedded/man/files/modules/doctools2toc/msgcat_fr.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/msgcat_fr.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/msgcat_fr.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::msgcat::toc::fr" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::msgcat::toc::fr \- Message catalog for the doctoc parser (FR) +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmsgcat \fR +.sp +package require \fBdoctools::msgcat::toc::fr ?0.1?\fR +.sp +.BE +.SH DESCRIPTION +The package \fBdoctools::msgcat::toc::fr\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. +.PP +If you are such please go the documentation of either +.IP [1] +\fBdoctools::doc\fR, +.IP [2] +\fBdoctools::toc\fR, or +.IP [3] +\fBdoctools::idx\fR +.PP +.PP +Within the system architecture this package resides under the package +\fBdoctools::msgcat\fR providing the general message catalog +management within the system. \fINote\fR that there is \fIno\fR +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically. +.SH API +This package has no exported API. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +FR, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/parse.n Index: embedded/man/files/modules/doctools2toc/parse.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/parse.n @@ -0,0 +1,535 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/parse.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::parse" n 1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::parse \- Parsing text in doctoc format +.SH SYNOPSIS +package require \fBdoctools::toc::parse ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBdoctools::toc::structure \fR +.sp +package require \fBdoctools::msgcat \fR +.sp +package require \fBdoctools::tcl::parse \fR +.sp +package require \fBfileutil \fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::stack \fR +.sp +\fB::doctools::toc::parse\fR \fBtext\fR \fItext\fR +.sp +\fB::doctools::toc::parse\fR \fBfile\fR \fIpath\fR +.sp +\fB::doctools::toc::parse\fR \fBincludes\fR +.sp +\fB::doctools::toc::parse\fR \fBinclude add\fR \fIpath\fR +.sp +\fB::doctools::toc::parse\fR \fBinclude remove\fR \fIpath\fR +.sp +\fB::doctools::toc::parse\fR \fBinclude clear\fR +.sp +\fB::doctools::toc::parse\fR \fBvars\fR +.sp +\fB::doctools::toc::parse\fR \fBvar set\fR \fIname\fR \fIvalue\fR +.sp +\fB::doctools::toc::parse\fR \fBvar unset\fR \fIname\fR +.sp +\fB::doctools::toc::parse\fR \fBvar clear\fR ?\fIpattern\fR? +.sp +.BE +.SH DESCRIPTION +This package provides commands to parse text written in the +\fIdoctoc\fR markup language and convert it into the canonical +serialization of the table of contents encoded in the text. +See the section \fBToC serialization format\fR for specification +of their format. +.PP +This is an internal package of doctools, for use by the higher level +packages handling \fIdoctoc\fR documents. +.SH API +.TP +\fB::doctools::toc::parse\fR \fBtext\fR \fItext\fR +The command takes the string contained in \fItext\fR and parses it +under the assumption that it contains a document written using the +\fIdoctoc\fR markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section \fBParse errors\fR. +.sp +When successful the command returns the canonical serialization of the +table of contents which was encoded in the text. +See the section \fBToC serialization format\fR for specification +of that format. +.TP +\fB::doctools::toc::parse\fR \fBfile\fR \fIpath\fR +The same as \fBtext\fR, except that the text to parse is read from +the file specified by \fIpath\fR. +.TP +\fB::doctools::toc::parse\fR \fBincludes\fR +This method returns the current list of search paths used when looking +for include files. +.TP +\fB::doctools::toc::parse\fR \fBinclude add\fR \fIpath\fR +This method adds the \fIpath\fR 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. +.TP +\fB::doctools::toc::parse\fR \fBinclude remove\fR \fIpath\fR +This method removes the \fIpath\fR 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. +.TP +\fB::doctools::toc::parse\fR \fBinclude clear\fR +This method clears the list of search paths for include files. +.TP +\fB::doctools::toc::parse\fR \fBvars\fR +This method returns a dictionary containing the current set of +predefined variables known to the \fBvset\fR markup command during +processing. +.TP +\fB::doctools::toc::parse\fR \fBvar set\fR \fIname\fR \fIvalue\fR +This method adds the variable \fIname\fR to the set of predefined +variables known to the \fBvset\fR markup command during processing, +and gives it the specified \fIvalue\fR. The method returns the empty +string as its result. +.TP +\fB::doctools::toc::parse\fR \fBvar unset\fR \fIname\fR +This method removes the variable \fIname\fR from the set of predefined +variables known to the \fBvset\fR markup command during +processing. The method returns the empty string as its result. +.TP +\fB::doctools::toc::parse\fR \fBvar clear\fR ?\fIpattern\fR? +This method removes all variables matching the \fIpattern\fR from the +set of predefined variables known to the \fBvset\fR markup command +during processing. The method returns the empty string as its result. +.sp +The pattern matching is done with \fBstring match\fR, and the +default pattern used when none is specified, is \fB*\fR. +.PP +.SH "PARSE ERRORS" +The format of the parse error messages thrown when encountering +violations of the \fIdoctoc\fR markup syntax is human readable and +not intended for processing by machines. As such it is not documented. +.PP +\fIHowever\fR, the errorCode attached to the message is +machine-readable and has the following format: +.IP [1] +The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more. +.IP [2] +Each error element will be a list containing six strings describing an +error in detail. The strings will be +.RS +.IP [1] +The path of the file the error occured in. This may be empty. +.IP [2] +The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero. +.IP [3] +The line the first character after the error is on. +Lines are counted from one. +.IP [4] +The column the first character after the error is at. +Columns are counted from zero. +.IP [5] +The message code of the error. This value can be used as argument to +\fBmsgcat::mc\fR to obtain a localized error message, assuming that +the application had a suitable call of \fBdoctools::msgcat::init\fR to +initialize the necessary message catalogs (See package +\fBdoctools::msgcat\fR). +.IP [6] +A list of details for the error, like the markup command involved. In +the case of message code \fBdoctoc/include/syntax\fR this value is +the set of errors found in the included file, using the format +described here. +.RE +.PP +.SH "[DOCTOC] NOTATION OF TABLES OF CONTENTS" +The doctoc format for tables of contents, also called the +\fIdoctoc markup language\fR, is too large to be covered in single +section. +The interested reader should start with the document +.IP [1] +\fIdoctoc language introduction\fR +.PP +and then proceed from there to the formal specifications, i.e. the +documents +.IP [1] +\fIdoctoc language syntax\fR and +.IP [2] +\fIdoctoc language command reference\fR. +.PP +to get a thorough understanding of the language. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +doctoc, doctools, lexer, parser +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/doctools2toc/structure.n Index: embedded/man/files/modules/doctools2toc/structure.n ================================================================== --- /dev/null +++ embedded/man/files/modules/doctools2toc/structure.n @@ -0,0 +1,480 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/doctools2toc/structure.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "doctools::toc::structure" n 0.1 tcllib "Documentation tools" +.BS +.SH NAME +doctools::toc::structure \- Doctoc serialization utilities +.SH SYNOPSIS +package require \fBdoctools::toc::structure ?0.1?\fR +.sp +package require \fBTcl 8.4\fR +.sp +package require \fBlogger \fR +.sp +package require \fBsnit \fR +.sp +\fB::doctools::toc::structure\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +.sp +\fB::doctools::toc::structure\fR \fBverify-as-canonical\fR \fIserial\fR +.sp +\fB::doctools::toc::structure\fR \fBcanonicalize\fR \fIserial\fR +.sp +\fB::doctools::toc::structure\fR \fBprint\fR \fIserial\fR +.sp +\fB::doctools::toc::structure\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +.sp +.BE +.SH 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 \fBToC serialization format\fR. +.PP +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 \fIdoctoc\fR +markup. +.SH API +.TP +\fB::doctools::toc::structure\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +This command verifies that the content of \fIserial\fR is a valid +\fIregular\fR 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. +.sp +If the argument \fIcanonvar\fR 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 \fIserial\fR is a valid regular +serialization. Its value will be a boolean, with \fBTrue\fR +indicating that the serialization is not only valid, but also +\fIcanonical\fR. \fBFalse\fR will be written for a valid, but +non-canonical serialization. +.sp +For the specification of regular and canonical serializations see the +section \fBToC serialization format\fR. +.TP +\fB::doctools::toc::structure\fR \fBverify-as-canonical\fR \fIserial\fR +This command verifies that the content of \fIserial\fR is a valid +\fIcanonical\fR 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. +.sp +For the specification of canonical serializations see the section +\fBToC serialization format\fR. +.TP +\fB::doctools::toc::structure\fR \fBcanonicalize\fR \fIserial\fR +This command assumes that the content of \fIserial\fR is a valid +\fIregular\fR serialization of a table of contents and will throw an +error if that is not the case. +.sp +It will then convert the input into the \fIcanonical\fR serialization +of the contained table of contents and return it as its result. If the +input is already canonical it will be returned unchanged. +.sp +For the specification of regular and canonical serializations see the +section \fBToC serialization format\fR. +.TP +\fB::doctools::toc::structure\fR \fBprint\fR \fIserial\fR +This command assumes that the argument \fIserial\fR contains a valid +regular serialization of a table of contents and returns a string +containing that table in a human readable form. +.sp +The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities. +.sp +For the specification of regular serializations see the section +\fBToC serialization format\fR. +.TP +\fB::doctools::toc::structure\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +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. +.sp +Title and label of the resulting table are taken from the table +contained in \fIserialb\fR. +.sp +The whole table and its divisions are merged recursively in the same +manner: +.RS +.IP [1] +All reference elements which occur in both divisions (identified by +their label) are unified with document id's and descriptions taken +from the second table. +.IP [2] +All division elements which occur in both divisions (identified by +their label) are unified with the optional document id taken from the +second table, if any, or from the first if none is in the second. The +elements in the division are merged recursively using the same +algorithm as described in this list. +.IP [3] +Type conflicts between elements, i.e. finding two elements with the +same label but different types result in a merge error. +.IP [4] +All elements found in the second division but not in the first are +added to the end of the list of elements in the merge result. +.RE +.sp +For the specification of regular and canonical serializations see the +section \fBToC serialization format\fR. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be \fIcanonical\fR. +.PP +.TP +regular serialization +.RS +.IP [1] +The serialization of any table of contents is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBdoctools::toc\fR, and its +value. This value holds the contents of the table of contents. +.IP [3] +The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are +.RS +.TP +\fBtitle\fR +The value is a string containing the title of the table of contents. +.TP +\fBlabel\fR +The value is a string containing a label for the table of contents. +.TP +\fBitems\fR +The value is a Tcl list holding the elements of the table, in the +order they are to be shown. +.sp +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. +.sp +The two legal item types and their descriptions are +.RS +.TP +\fBreference\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the entry. +.TP +\fBlabel\fR +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. +.TP +\fBdesc\fR +The value is a string containing a longer description for this entry. +.RE +.TP +\fBdivision\fR +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 +.RS +.TP +\fBid\fR +The value is a string containing the id of the document associated +with the whole group. This key is optional. +.TP +\fBlabel\fR +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. +.TP +\fBitems\fR +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 +\fBitems\fR 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. +.RE +.RE +.RE +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIdoctools\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +deserialization, doctoc, doctools, serialization +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/exif/exif.n Index: embedded/man/files/modules/exif/exif.n ================================================================== --- /dev/null +++ embedded/man/files/modules/exif/exif.n @@ -0,0 +1,313 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/exif/exif.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "exif" n 1.1.2 tcllib "EXIF parsing" +.BS +.SH NAME +exif \- Tcl EXIF extracts and parses EXIF fields from digital images +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBexif ?1.1.2?\fR +.sp +\fBexif::analyze\fR \fIchannel\fR ?\fIthumbnail\fR? +.sp +\fBexif::analyzeFile\fR \fIfilename\fR ?\fIthumbnail\fR? +.sp +\fBexif::fieldnames\fR +.sp +.BE +.SH DESCRIPTION +.PP +The EXIF package is a recoding of Chris Breeze's Perl package to do +the same thing. This version accepts a channel as input and returns a +serialized array with all the recognised fields parsed out. +.PP +There is also a function to obtain a list of all possible field names +that might be present, which is useful in building GUIs that present +such information. +.SH COMMANDS +.TP +\fBexif::analyze\fR \fIchannel\fR ?\fIthumbnail\fR? +\fIchannel\fR should be an open file handle rewound to the start. It +does not need to be seekable. \fIchannel\fR will be set to binary +mode and is left wherever it happens to stop being parsed, usually at +the end of the file or the start of the image data. You must open and +close the stream yourself. If no error is thrown, the return value is +a serialized array with informative English text about what was found +in the EXIF block. Failure during parsing or I/O throw errors. +.sp +If \fIthumbnail\fR is present and not the empty string it will be +interpreted as the name of a file, and the thumbnail image contained +in the exif data will be written into it. +.TP +\fBexif::analyzeFile\fR \fIfilename\fR ?\fIthumbnail\fR? +This is a file-based wrapper around \fBexif::analyze\fR. Instead of +taking a stream it takes a \fIfilename\fR and analyzes the contents of +the specified file. +.TP +\fBexif::fieldnames\fR +This returns a list of all possible field names. That is, the array +returned by \fBexif::analyze\fR will not contain keys that are not +listed in the return from \fBexif::fieldnames\fR. Of course, if +information is missing in the image file, \fBexif::analyze\fR may not +return all the fields listed in the return from exif::fieldnames. +This function is expected to be primarily useful for building GUIs to +display results. +.sp +N.B.: Read the implementation of \fBexif::fieldnames\fR before +modifying the implementation of \fBexif::analyze\fR. +.PP +.SH COPYRIGHTS +(c) 2002 Darren New +Hold harmless the author, and any lawful use is allowed. +.SH ACKNOWLEDGEMENTS +This code is a direct translation of version 1.3 of exif.pl by Chris +Breeze. See the source for full headers, references, etc. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIexif\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +exif, jpeg, maker note, tiff +.SH CATEGORY +File formats ADDED embedded/man/files/modules/fileutil/fileutil.n Index: embedded/man/files/modules/fileutil/fileutil.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fileutil/fileutil.n @@ -0,0 +1,680 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fileutil/fileutil.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil" n 1.14.5 tcllib "file utilities" +.BS +.SH NAME +fileutil \- Procedures implementing some file utilities +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBfileutil ?1.14.5?\fR +.sp +\fB::fileutil::lexnormalize\fR \fIpath\fR +.sp +\fB::fileutil::fullnormalize\fR \fIpath\fR +.sp +\fB::fileutil::test\fR \fIpath\fR \fIcodes\fR ?\fImsgvar\fR? ?\fIlabel\fR? +.sp +\fB::fileutil::cat\fR (?\fIoptions\fR? \fIfile\fR)... +.sp +\fB::fileutil::writeFile\fR ?\fIoptions\fR? \fIfile\fR \fIdata\fR +.sp +\fB::fileutil::appendToFile\fR ?\fIoptions\fR? \fIfile\fR \fIdata\fR +.sp +\fB::fileutil::insertIntoFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIdata\fR +.sp +\fB::fileutil::removeFromFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIn\fR +.sp +\fB::fileutil::replaceInFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIn\fR \fIdata\fR +.sp +\fB::fileutil::updateInPlace\fR ?\fIoptions\fR? \fIfile\fR \fIcmd\fR +.sp +\fB::fileutil::fileType\fR \fIfilename\fR +.sp +\fB::fileutil::find\fR ?\fIbasedir\fR ?\fIfiltercmd\fR?? +.sp +\fB::fileutil::findByPattern\fR \fIbasedir\fR ?\fB-regexp\fR|\fB-glob\fR? ?\fB--\fR? \fIpatterns\fR +.sp +\fB::fileutil::foreachLine\fR \fIvar filename cmd\fR +.sp +\fB::fileutil::grep\fR \fIpattern\fR ?\fIfiles\fR? +.sp +\fB::fileutil::install\fR ?\fB-m\fR \fImode\fR? \fIsource\fR \fIdestination\fR +.sp +\fB::fileutil::stripN\fR \fIpath\fR \fIn\fR +.sp +\fB::fileutil::stripPwd\fR \fIpath\fR +.sp +\fB::fileutil::stripPath\fR \fIprefix\fR \fIpath\fR +.sp +\fB::fileutil::jail\fR \fIjail\fR \fIpath\fR +.sp +\fB::fileutil::touch\fR ?\fB-a\fR? ?\fB-c\fR? ?\fB-m\fR? ?\fB-r\fR \fIref_file\fR? ?\fB-t\fR \fItime\fR? \fIfilename\fR ?\fI...\fR? +.sp +\fB::fileutil::tempdir\fR +.sp +\fB::fileutil::tempdir\fR \fIpath\fR +.sp +\fB::fileutil::tempdirReset\fR +.sp +\fB::fileutil::tempfile\fR ?\fIprefix\fR? +.sp +\fB::fileutil::relative\fR \fIbase\fR \fIdst\fR +.sp +\fB::fileutil::relativeUrl\fR \fIbase\fR \fIdst\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides implementations of standard unix utilities. +.TP +\fB::fileutil::lexnormalize\fR \fIpath\fR +This command performs purely lexical normalization on the \fIpath\fR and returns +the changed path as its result. Symbolic links in the path are \fInot\fR resolved. +.sp +Examples: +.CS + + + fileutil::lexnormalize /foo/./bar + => /foo/bar + + fileutil::lexnormalize /foo/../bar + => /bar + +.CE +.TP +\fB::fileutil::fullnormalize\fR \fIpath\fR +This command resolves all symbolic links in the \fIpath\fR and returns +the changed path as its result. +In contrast to the builtin \fBfile normalize\fR this command +resolves a symbolic link in the last element of the path as well. +.TP +\fB::fileutil::test\fR \fIpath\fR \fIcodes\fR ?\fImsgvar\fR? ?\fIlabel\fR? +A command for the testing of several properties of a \fIpath\fR. The +properties to test for are specified in \fIcodes\fR, 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. +.sp +The result of the command is a boolean value. It will be true if and +only if the \fIpath\fR passes all the specified tests. +In the case of the \fIpath\fR not passing one or more test the first +failing test will leave a message in the variable referenced by +\fImsgvar\fR, if such is specified. The message will be prefixed with +\fIlabel\fR, if it is specified. +\fINote\fR that the variabled referenced by \fImsgvar\fR is not touched at +all if all the tests pass. +.sp +.RS +.TP +\fIr\fRead +\fBfile readable\fR +.TP +\fIw\fRrite +\fBfile writable\fR +.TP +\fIe\fRxists +\fBfile exists\fR +.TP +e\fIx\fRec +\fBfile executable\fR +.TP +\fIf\fRile +\fBfile isfile\fR +.TP +\fId\fRir +\fBfile isdirectory\fR +.RE +.TP +\fB::fileutil::cat\fR (?\fIoptions\fR? \fIfile\fR)... +A tcl implementation of the UNIX \fBcat\fR 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. +.sp +The options accepted are \fB-encoding\fR, \fB-translation\fR, +\fB-eofchar\fR, and \fB--\fR. With the exception of the last all +options take a single value as argument, as specified by the tcl +builtin command \fBfconfigure\fR. The \fB--\fR has to be used to +terminate option processing before a file if that file's name begins +with a dash. +.sp +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. +.TP +\fB::fileutil::writeFile\fR ?\fIoptions\fR? \fIfile\fR \fIdata\fR +The command replaces the current contents of the specified \fIfile\fR +with \fIdata\fR, with the process configured by the options. The +command accepts the same options as \fB::fileutil::cat\fR. The +specification of a non-existent file is legal and causes the command +to create the file (and all required but missing directories). +.TP +\fB::fileutil::appendToFile\fR ?\fIoptions\fR? \fIfile\fR \fIdata\fR +This command is like \fB::fileutil::writeFile\fR, except that the +previous contents of \fIfile\fR are not replaced, but appended to. The +command accepts the same options as \fB::fileutil::cat\fR +.TP +\fB::fileutil::insertIntoFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIdata\fR +This comment is similar to \fB::fileutil::appendToFile\fR, 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. +.sp +The specified location \fIat\fR has to be an integer number in the +range \fB0\fR ... [file size \fIfile\fR]. \fB0\fR will cause +insertion of the new data before the first character of the existing +content, whereas [file size \fIfile\fR] causes insertion after +the last character of the existing content, i.e. appending. +.sp +The command accepts the same options as \fB::fileutil::cat\fR. +.TP +\fB::fileutil::removeFromFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIn\fR +This command is the complement to \fB::fileutil::insertIntoFile\fR, removing \fIn\fR characters from the \fIfile\fR, starting at location \fIat\fR. +The specified location \fIat\fR has to be an integer number in the +range \fB0\fR ... [file size \fIfile\fR] - \fIn\fR. \fB0\fR +will cause the removal of the new data to start with the first +character of the existing content, +whereas [file size \fIfile\fR] - \fIn\fR causes the removal of +the tail of the existing content, i.e. the truncation of the file. +.sp +The command accepts the same options as \fB::fileutil::cat\fR. +.TP +\fB::fileutil::replaceInFile\fR ?\fIoptions\fR? \fIfile\fR \fIat\fR \fIn\fR \fIdata\fR +This command is a combination of \fB::fileutil::removeFromFile\fR and +\fB::fileutil::insertIntoFile\fR. It first removes the part of the +contents specified by the arguments \fIat\fR and \fIn\fR, and then +inserts \fIdata\fR at the given location, effectively replacing the +removed by content with \fIdata\fR. +All constraints imposed on \fIat\fR and \fIn\fR by +\fB::fileutil::removeFromFile\fR and \fB::fileutil::insertIntoFile\fR +are obeyed. +.sp +The command accepts the same options as \fB::fileutil::cat\fR. +.TP +\fB::fileutil::updateInPlace\fR ?\fIoptions\fR? \fIfile\fR \fIcmd\fR +This command can be seen as the generic core functionality of +\fB::fileutil::replaceInFile\fR. +It first reads the contents of the specified \fIfile\fR, then runs the +command prefix \fIcmd\fR with that data appended to it, and at last +writes the result of that invokation back as the new contents of the +file. +.sp +If the executed command throws an error the \fIfile\fR is not changed. +.sp +The command accepts the same options as \fB::fileutil::cat\fR. +.TP +\fB::fileutil::fileType\fR \fIfilename\fR +An implementation of the UNIX \fBfile\fR 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. +.TP +\fB::fileutil::find\fR ?\fIbasedir\fR ?\fIfiltercmd\fR?? +An implementation of the unix command \fBfind\fR. 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 "\fI.\fR", i.e. the current +directory. The command defaults to the empty string, which means that +all files are of interest. The command takes care \fInot\fR 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. +.sp +The \fIfiltercmd\fR, 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 \fInot\fR fully +qualified. It has to be joined it with the result of \fBpwd\fR to get +an absolute filename. +.sp +The result of \fIfiltercmd\fR is a boolean value that indicates if the +current file should be included in the list of interesting files. +.sp +Example: +.sp +.CS + + + # find .tcl files + package require fileutil + proc is_tcl {name} {return [string match *.tcl $name]} + set tcl_files [fileutil::find . is_tcl] + +.CE +.TP +\fB::fileutil::findByPattern\fR \fIbasedir\fR ?\fB-regexp\fR|\fB-glob\fR? ?\fB--\fR? \fIpatterns\fR +This command is based upon the \fBTclX\fR command +\fBrecursive_glob\fR, except that it doesn't allow recursion over more +than one directory at a time. It uses \fB::fileutil::find\fR +internally and is thus able to and does follow symbolic links, +something the \fBTclX\fR command does not do. First argument is +the directory to start the search in, second argument is a list of +\fIpatterns\fR. The command returns a list of all files reachable +through \fIbasedir\fR 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 \fB--\fR stops option +processing. This allows the use of a leading '-' in the patterns. +.TP +\fB::fileutil::foreachLine\fR \fIvar filename cmd\fR +The command reads the file \fIfilename\fR and executes the script +\fIcmd\fR for every line in the file. During the execution of the +script the variable \fIvar\fR 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 \fIcmd\fR or the empty string if the file was +empty. +.TP +\fB::fileutil::grep\fR \fIpattern\fR ?\fIfiles\fR? +Implementation of \fBgrep\fR. Adapted from the Tcler's Wiki. The +first argument defines the \fIpattern\fR to search for. This is +followed by a list of \fIfiles\fR to search through. The list is +optional and \fBstdin\fR 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. +.TP +\fB::fileutil::install\fR ?\fB-m\fR \fImode\fR? \fIsource\fR \fIdestination\fR +The \fBinstall\fR command is similar in functionality to the \fBinstall\fR +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 \fIsource\fR, which can be either a +file or directory to \fIdestination\fR, which should be a directory, +unless \fIsource\fR is also a single file. The ?-m? option lets +the user specify a unix-style mode (either octal or symbolic - see +\fBfile attributes\fR. +.TP +\fB::fileutil::stripN\fR \fIpath\fR \fIn\fR +Removes the first \fIn\fR elements from the specified \fIpath\fR and +returns the modified path. If \fIn\fR is greater than the number of +components in \fIpath\fR an empty string is returned. The number of +components in a given path may be determined by performing +\fBllength\fR on the list returned by \fBfile split\fR. +.TP +\fB::fileutil::stripPwd\fR \fIpath\fR +If, and only if the \fIpath\fR is inside of the directory returned by +[\fBpwd\fR] (or the current working directory itself) it is made +relative to that directory. In other words, the current working +directory is stripped from the \fIpath\fR. The possibly modified path +is returned as the result of the command. If the current working +directory itself was specified for \fIpath\fR the result is the string +"\fB.\fR". +.TP +\fB::fileutil::stripPath\fR \fIprefix\fR \fIpath\fR +If, and only of the \fIpath\fR is inside of the directory +"\fIprefix\fR" (or the prefix directory itself) it is made relative to +that directory. In other words, the prefix directory is stripped from +the \fIpath\fR. The possibly modified path is returned as the result +of the command. +If the prefix directory itself was specified for \fIpath\fR the result +is the string "\fB.\fR". +.TP +\fB::fileutil::jail\fR \fIjail\fR \fIpath\fR +This command ensures that the \fIpath\fR is not escaping the directory +\fIjail\fR. It always returns an absolute path derived from \fIpath\fR +which is within \fIjail\fR. +.sp +If \fIpath\fR is an absolute path and already within \fIjail\fR it is +returned unmodified. +.sp +An absolute path outside of \fIjail\fR is stripped of its root element +and then put into the \fIjail\fR by prefixing it with it. The same +happens if \fIpath\fR is relative, except that nothing is stripped of +it. Before adding the \fIjail\fR prefix the \fIpath\fR is lexically +normalized to prevent the caller from using \fB..\fR segments in +\fIpath\fR to escape the jail. +.TP +\fB::fileutil::touch\fR ?\fB-a\fR? ?\fB-c\fR? ?\fB-m\fR? ?\fB-r\fR \fIref_file\fR? ?\fB-t\fR \fItime\fR? \fIfilename\fR ?\fI...\fR? +Implementation of \fBtouch\fR. Alter the atime and mtime of the +specified files. If \fB-c\fR, do not create files if they do not +already exist. If \fB-r\fR, use the atime and mtime from +\fIref_file\fR. If \fB-t\fR, use the integer clock value +\fItime\fR. It is illegal to specify both \fB-r\fR and +\fB-t\fR. If \fB-a\fR, only change the atime. If \fB-m\fR, +only change the mtime. +.sp +\fIThis command is not available for Tcl versions less than 8.3.\fR +.TP +\fB::fileutil::tempdir\fR +The command returns the path of a directory where the caller can +place temporary files, such as "\fI/tmp\fR" on Unix systems. The +algorithm we use to find the correct directory is as follows: +.RS +.IP [1] +The directory set by an invokation of \fB::fileutil::tempdir\fR with +an argument. If this is present it is tried exclusively and none of +the following item are tried. +.IP [2] +The directory named in the TMPDIR environment variable. +.IP [3] +The directory named in the TEMP environment variable. +.IP [4] +The directory named in the TMP environment variable. +.IP [5] +A platform specific location: +.RS +.TP +Windows +"\fIC:\\TEMP\fR", "\fIC:\\TMP\fR", "\fI\\TEMP\fR", +and "\fI\\TMP\fR" are tried in that order. +.TP +(classic) Macintosh +The TRASH_FOLDER environment variable is used. This is most likely +not correct. +.TP +Unix +The directories "\fI/tmp\fR", "\fI/var/tmp\fR", and "\fI/usr/tmp\fR" are +tried in that order. +.RE +.RE +.sp +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. +.TP +\fB::fileutil::tempdir\fR \fIpath\fR +In this mode the command sets the \fIpath\fR 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. +.TP +\fB::fileutil::tempdirReset\fR +Invoking this command clears the information set by the +last call of [\fB::fileutil::tempdir\fR \fIpath\fR]. +See the last item too. +.TP +\fB::fileutil::tempfile\fR ?\fIprefix\fR? +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. +.sp +The code was taken from \fIhttp://wiki.tcl.tk/772\fR, attributed to +Igor Volobouev and anon. +.TP +\fB::fileutil::relative\fR \fIbase\fR \fIdst\fR +This command takes two directory paths, both either absolute or relative +and computes the path of \fIdst\fR relative to \fIbase\fR. 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. +.sp +\fINote:\fR The processing done by this command is purely lexical. +Symbolic links are \fInot\fR taken into account. +.TP +\fB::fileutil::relativeUrl\fR \fIbase\fR \fIdst\fR +This command takes two file paths, both either absolute or relative +and computes the path of \fIdst\fR relative to \fIbase\fR, as seen +from inside of the \fIbase\fR. This is the algorithm how a browser +resolves a relative link found in the currently shown file. +.sp +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. +.sp +\fINote:\fR The processing done by this command is purely lexical. +Symbolic links are \fInot\fR taken into account. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +cat, file utilities, grep, temp file, test, touch, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fileutil/multi.n Index: embedded/man/files/modules/fileutil/multi.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fileutil/multi.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fileutil/multi.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::multi" n 0.1 tcllib "file utilities" +.BS +.SH NAME +fileutil::multi \- Multi-file operation, scatter/gather, standard object +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::multi ?0.1?\fR +.sp +package require \fBfileutil::multi::op ?0.1?\fR +.sp +package require \fBwip ?1.0?\fR +.sp +\fB::fileutil::multi\fR ?\fIword\fR...? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a single command to perform actions on multiple +files selected by glob patterns. It is a thin layer over the package +\fBfileutil::multi::op\fR which provides objects for the +same. This package simply creates a single such object and directs all +file commands to it. +.PP +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 \fBfileutil::multi::op\fR. +.SH "PUBLIC API" +The main command of the package is: +.TP +\fB::fileutil::multi\fR ?\fIword\fR...? +This command interprets the specified words as file commands to +execute. See the section \fBFILE API\fR of the +documentation for the package \fBfileutil::multi::op\fR for +the set of acceptable commands, their syntax, and semantics. +.sp +The result of the command is the result generated by the last file +command it executed. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +copy, file utilities, move, multi-file, remove +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fileutil/multiop.n Index: embedded/man/files/modules/fileutil/multiop.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fileutil/multiop.n @@ -0,0 +1,693 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fileutil/multiop.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::multi::op" n 0.5.3 tcllib "file utilities" +.BS +.SH NAME +fileutil::multi::op \- Multi-file operation, scatter/gather +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::multi::op ?0.5.3?\fR +.sp +package require \fBwip ?1.0?\fR +.sp +\fB::fileutil::multi::op\fR ?\fIopName\fR? ?\fIword\fR...? +.sp +\fBopName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fB$opName\fR \fBdo\fR ?\fIword\fR...? +.sp +\fBinto\fR \fIdirectory\fR +.sp +\fBin\fR \fIdirectory\fR +.sp +\fBto\fR \fIdirectory\fR +.sp +\fBfrom\fR \fIdirectory\fR +.sp +\fBnot\fR \fIpattern\fR +.sp +\fBfor\fR \fIpattern\fR +.sp +\fBexclude\fR \fIpattern\fR +.sp +\fBbut\fR +.sp +\fBexcept\fR +.sp +\fBas\fR \fIname\fR +.sp +\fBrecursive\fR +.sp +\fBrecursively\fR +.sp +\fBcopy\fR +.sp +\fBmove\fR +.sp +\fBremove\fR +.sp +\fBexpand\fR +.sp +\fBinvoke\fR \fIcmdprefix\fR +.sp +\fBreset\fR +.sp +\fB(\fR +.sp +\fB)\fR +.sp +\fBcd\fR \fIdirectory\fR +.sp +\fBup\fR +.sp +\fBfor-windows\fR +.sp +\fBfor-win\fR +.sp +\fBfor-unix\fR +.sp +\fBthe\fR \fIpattern\fR +.sp +\fBthe-set\fR \fIvarname\fR +.sp +\fB->\fR \fIvarname\fR +.sp +\fBstrict\fR +.sp +\fB!strict\fR +.sp +\fBfiles\fR +.sp +\fBlinks\fR +.sp +\fBdirectories\fR +.sp +\fBdirs\fR +.sp +\fBall\fR +.sp +\fBstate?\fR +.sp +\fBas?\fR +.sp +\fBexcluded?\fR +.sp +\fBfrom?\fR +.sp +\fBinto?\fR +.sp +\fBoperation?\fR +.sp +\fBrecursive?\fR +.sp +\fBstrict?\fR +.sp +\fBtype?\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides objects which are able to perform actions on +multiple files selected by glob patterns. +.PP +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. +.SH "CLASS API" +The main command of the package is: +.TP +\fB::fileutil::multi::op\fR ?\fIopName\fR? ?\fIword\fR...? +The command creates a new multi-file operation object with an +associated global Tcl command whose name is \fIopName\fR. This +command can be used to invoke the various possible file operations. +It has the following general form: +.RS +.TP +\fBopName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.sp +If the string \fB%AUTO%\fR is used as the \fIopName\fR then the +package will generate a unique name on its own. +.sp +If one or more \fIword\fRs are specified they are interpreted as an +initial set of file commands to execute. I.e. the method \fBdo\fR +of the newly constructed object is implicitly invoked using the words +as its arguments. +.PP +.PP +.SH "OBJECT API" +The following methods are possible for multi-file operation objects: +.TP +\fB$opName\fR \fBdo\fR ?\fIword\fR...? +This method interprets the specified words as file commands to +execute. See the section \fBFILE API\fR for the set of +acceptable commands, their syntax, and semantics. +.sp +The result of the method is the result generated by the last file +command it executed. +.PP +.SH "FILE API" +Both object constructor and method \fBdo\fR 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. +.TP +\fBinto\fR \fIdirectory\fR +Specifies the destination directory for operations. +.TP +\fBin\fR \fIdirectory\fR +Alias for \fBinto\fR. +.TP +\fBto\fR \fIdirectory\fR +Alias for \fBinto\fR. +.TP +\fBfrom\fR \fIdirectory\fR +Specifies the source directory for operations. +.TP +\fBnot\fR \fIpattern\fR +Specifies a glob pattern for paths to be excluded from the operation. +.TP +\fBfor\fR \fIpattern\fR +Alias for \fBnot\fR. +.TP +\fBexclude\fR \fIpattern\fR +Alias for \fBnot\fR. +.TP +\fBbut\fR +Has no arguments of its own, but looks ahead in the list of words and +executes all \fBnot\fR commands immediately following it. This allows the +construction of "but not" and "but exclude" clauses for a more natural +sounding specification of excluded paths. +.TP +\fBexcept\fR +A semi-alias for \fBbut\fR. Has no arguments of its own, but looks +ahead in the list of words and executes all \fBfor\fR commands +immediately following it. This allows the construction of "except for" +clauses for a more natural sounding specification of excluded paths. +.TP +\fBas\fR \fIname\fR +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. +.TP +\fBrecursive\fR +Signals that file expansion should happen in the whole directory +hierarchy and not just the directory itself. +.TP +\fBrecursively\fR +An alias for \fBrecursive\fR. +.TP +\fBcopy\fR +Signals that the operation is the copying of files from source to +destination directory per the specified inclusion and exclusion +patterns. +.TP +\fBmove\fR +Signals that the operation is the moving of files from source to +destination directory per the specified inclusion and exclusion +patterns. +.TP +\fBremove\fR +Signals that the operation is the removal of files in the destination +directory per the specified inclusion and exclusion patterns. +.TP +\fBexpand\fR +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 \fBthe-set\fR is used. +.TP +\fBinvoke\fR \fIcmdprefix\fR +Signals that the user-specified command prefix \fIcmdprefix\fR 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. +.TP +\fBreset\fR +Forces the object into the ground state where all parts of the +configuration have default values. +.TP +\fB(\fR +Saves a copy of the current object state on a stack. +.TP +\fB)\fR +Takes the state at the top of the state stack and restores it, +i.e. makes it the new current object state. +.TP +\fBcd\fR \fIdirectory\fR +Changes the destination directory to the sub-directory \fIdirectory\fR +of the current destination. +.TP +\fBup\fR +Changes the destination directory to the parent directory of the +current destination. +.TP +\fBfor-windows\fR +Checks that Windows is the current platform. Aborts processing if not. +.TP +\fBfor-win\fR +An alias for \fBfor-windows\fR. +.TP +\fBfor-unix\fR +Checks that Unix is the current platform. Aborts processing if not. +.TP +\fBthe\fR \fIpattern\fR +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. +.sp +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 \fBas\fR, \fBbut\fR, \fBexclude\fR, \fBexcept\fR, +\fBfrom\fR, and \fBinto\fR (and aliases). That way these commands act +like qualifiers, and still take effect as if they had been written +before this command. +.sp +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. +.TP +\fBthe-set\fR \fIvarname\fR +Like \fBthe\fR, 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 \fBexpand\fR is not available +if this command is used. +.TP +\fB->\fR \fIvarname\fR +Saves the set of files from the last expansion into the specified +variable. +.TP +\fBstrict\fR +Make file expansion and definition of destination directory (\fBin\fR +and aliases) strict, i.e. report errors for missing directories, and +empty expansion. +.TP +\fB!strict\fR +Complement of \fBstrict\fR. A missing destination directory or empty +expansion are not reported as errors. +.TP +\fBfiles\fR +Limit the search to files. Default is to accept every type of path. +.TP +\fBlinks\fR +Limit the search to symbolic links. Default is to accept every type of path. +.TP +\fBdirectories\fR +Limit the search to directories. Default is to accept every type of path. +.TP +\fBdirs\fR +An alias for \fBdirectories\fR. +.TP +\fBall\fR +Accept all types of paths (default). +.TP +\fBstate?\fR +Returns the current state of the object as dictionary. The dictionary keys and their meanings are: +.RS +.TP +\fBas\fR +Last setting made by \fBas\fR. +.TP +\fBexcluded\fR +List of currently known exclusion patterns. +.TP +\fBfrom\fR +Current source directory, set by \fBfrom\fR. +.TP +\fBinto\fR +Current destination directory, set by \fBinto\fR (and aliases). +.TP +\fBoperation\fR +Current operation to perform, set by \fBcopy\fR, \fBmove\fR, \fBremove\fR, \fBexpand\fR, or \fBinvoke\fR. +.TP +\fBrecursive\fR +Current recursion status. Set/unset by \fBrecursive\fR and \fB!recursive\fR. +.TP +\fBstrict\fR +Current strictness. Set/unset by \fBstrict\fR and \fB!strict\fR. +.TP +\fBtype\fR +Current path type limiter. Set by either \fBfiles\fR, \fBdirectories\fR, \fBlinks\fR, or \fBall\fR. +.RE +.TP +\fBas?\fR +Returns the current alias name. +.TP +\fBexcluded?\fR +Returns the current set of exclusion patterns. +.TP +\fBfrom?\fR +Returns the current source directory. +.TP +\fBinto?\fR +Returns the current destination directory. +.TP +\fBoperation?\fR +Returns the current operation to perform. +.TP +\fBrecursive?\fR +Returns the current recursion status. +.TP +\fBstrict?\fR +Returns the current strictness. +.TP +\fBtype?\fR +Returns the current path type limiter. +.PP +.SH EXAMPLES +The following examples assume that the variable \fBF\fR contains a +reference to a multi-file operation object. +.CS + + + $F do copy \\\\ + the *.dll \\\\ + from c:/TDK/PrivateOpenSSL/bin \\\\ + to [installdir_of tls] + +.CE +.CS + + + $F do move \\\\ + the * \\\\ + from /sources \\\\ + into /scratch \\\\ + but not *.html + + # Alternatively use 'except for *.html'. + +.CE +.CS + + + $F do \\\\ + move \\\\ + the index \\\\ + from /sources \\\\ + into /scratch \\\\ + as pkgIndex.tcl + +.CE +.CS + + + $F do \\\\ + remove \\\\ + the *.txt \\\\ + in /scratch + +.CE +Note that the fact that most commands just modify the object state +allows us to use more off forms as specifications instead of just +nearly-natural language sentences. +For example the second example in this section can re-arranged into: +.CS + + + $F do \\\\ + from /sources \\\\ + into /scratch \\\\ + but not *.html \\\\ + move \\\\ + the * + +.CE +and the result is not only still a valid specification, but even stays +relatively readable. +.PP +Further note that the information collected by the commands \fBbut\fR, +\fBexcept\fR, and \fBas\fR is automatically reset after the associated +\fBthe\fR 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: +.CS + + +$F do \\\\ + move \\\\ + the * \\\\ + from /sources \\\\ + into /scratch \\\\ + but not *.html not index \\\\ + the index \\\\ + as pkgIndex.tcl + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +copy, file utilities, move, multi-file, remove +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fileutil/traverse.n Index: embedded/man/files/modules/fileutil/traverse.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fileutil/traverse.n @@ -0,0 +1,359 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fileutil/traverse.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil_traverse" n 0.4.3 tcllib "file utilities" +.BS +.SH NAME +fileutil_traverse \- Iterative directory traversal +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBfileutil::traverse ?0.4.3?\fR +.sp +package require \fBfileutil \fR +.sp +package require \fBcontrol \fR +.sp +\fB::fileutil::traverse\fR ?\fIobjectName\fR? \fIpath\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fB$traverser\fR \fBcommand\fR ?\fIarg arg ...\fR? +.sp +\fB$traverser\fR \fBfiles\fR +.sp +\fB$traverser\fR \fBforeach\fR \fIfilevar\fR \fIscript\fR +.sp +\fB$traverser\fR \fBnext\fR \fIfilevar\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides objects for the programmable traversal of +directory hierarchies. +The main command exported by the package is: +.TP +\fB::fileutil::traverse\fR ?\fIobjectName\fR? \fIpath\fR ?\fIoption\fR \fIvalue\fR...? +The command creates a new traversal object with an associated global +Tcl command whose name is \fIobjectName\fR. This command may be used +to invoke various operations on the traverser. +If the string \fB%AUTO%\fR is used as the \fIobjectName\fR then a +unique name will be generated by the package itself. +.sp +Regarding the recognized options see section \fBOPTIONS\fR. 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. +.sp +The object command has the following general form: +.RS +.TP +\fB$traverser\fR \fBcommand\fR ?\fIarg arg ...\fR? +\fICommand\fR and its \fIarg\fRuments determine the exact behavior of +the object. +.RE +.PP +The following commands are possible for traversal objects: +.TP +\fB$traverser\fR \fBfiles\fR +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. +.TP +\fB$traverser\fR \fBforeach\fR \fIfilevar\fR \fIscript\fR +The highlevel \fBfiles\fR 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 \fIscript\fR +for each path. The current path under consideration is stored in the +variable named by \fIfilevar\fR. Both variable and script live / are +executed in the context of the caller of the method. In the method +\fBfiles\fR the script simply saves the found paths into the list +to return. +.TP +\fB$traverser\fR \fBnext\fR \fIfilevar\fR +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 +(\fBTrue\fR), or not (\fBFalse\fR). If a path was found it is +stored into the variable named by \fIfilevar\fR, in the context of the +caller. +The \fBforeach\fR method simply calls this method in a loop until +it returned \fBFalse\fR. This method is exposed so that we are also +able to incrementally traverse a directory hierarchy in an event-based +manner. +.PP +.SH OPTIONS +.TP +\fB-prefilter\fR 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 \fIabsolute\fR path of the directory, and has to +return a boolean value, \fBTrue\fR when the directory passes the +filter, and \fBFalse\fR if not. +.TP +\fB-filter\fR command_prefix +This callback is executed for all paths. Its result determines if the +current path is a valid result, and returned by \fBnext\fR. The +default is to accept all paths as valid. The callback is invoked with +a single argument, the \fIabsolute\fR path to check, and has to +return a boolean value, \fBTrue\fR when the path passes the filter, +and \fBFalse\fR if not. +.TP +\fB-errorcmd\fR 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 \fIabsolute\fR 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 \fBnext\fR. Any other +results from the callback are ignored. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +directory traversal, traversal +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/ftp/ftp.n Index: embedded/man/files/modules/ftp/ftp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ftp/ftp.n @@ -0,0 +1,625 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ftp/ftp.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ftp" n 2.4.11 tcllib "ftp client" +.BS +.SH NAME +ftp \- Client-side tcl implementation of the ftp protocol +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBftp ?2.4.11?\fR +.sp +\fB::ftp::Open\fR \fIserver\fR \fIuser\fR \fIpasswd\fR ?\fIoptions\fR? +.sp +\fB::ftp::Close\fR \fIhandle\fR +.sp +\fB::ftp::Cd\fR \fIhandle\fR \fIdirectory\fR +.sp +\fB::ftp::Pwd\fR \fIhandle\fR +.sp +\fB::ftp::Type\fR \fIhandle\fR ?\fBascii|binary|tenex\fR? +.sp +\fB::ftp::List\fR \fIhandle\fR ?\fIpattern\fR? +.sp +\fB::ftp::NList\fR \fIhandle\fR ?\fIdirectory\fR? +.sp +\fB::ftp::FileSize\fR \fIhandle\fR \fIfile\fR +.sp +\fB::ftp::ModTime\fR \fIhandle\fR \fIfile\fR +.sp +\fB::ftp::Delete\fR \fIhandle\fR \fIfile\fR +.sp +\fB::ftp::Rename\fR \fIhandle\fR \fIfrom\fR \fIto\fR +.sp +\fB::ftp::Put\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR | -channel \fIchan\fR) ?\fIremote\fR? +.sp +\fB::ftp::Append\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR | -channel \fIchan\fR) ?\fIremote\fR? +.sp +\fB::ftp::Get\fR \fIhandle\fR \fIremote\fR ?(\fIlocal\fR | -variable \fIvarname\fR | -channel \fIchan\fR)? +.sp +\fB::ftp::Reget\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR? ?\fIfrom\fR? ?\fIto\fR? +.sp +\fB::ftp::Newer\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR? +.sp +\fB::ftp::MkDir\fR \fIhandle\fR \fIdirectory\fR +.sp +\fB::ftp::RmDir\fR \fIhandle\fR \fIdirectory\fR +.sp +\fB::ftp::Quote\fR \fIhandle\fR \fIarg1\fR \fIarg2\fR \fI...\fR +.sp +\fB::ftp::DisplayMsg\fR \fIhandle\fR \fImsg\fR ?\fIstate\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The ftp package provides the client side of the ftp protocol as +specified in RFC 959 (\fIhttp://www.rfc-editor.org/rfc/rfc959.txt\fR). +The package implements both active (default) and passive ftp sessions. +.PP +A new ftp session is started with the \fB::ftp::Open\fR command. To +shutdown an existing ftp session use \fB::ftp::Close\fR. 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 \fBcd\fR or \fBfile\fR. +.PP +The output of the package is controlled by two state variables, +\fB::ftp::VERBOSE\fR and \fB::ftp::DEBUG\fR. Setting +\fB::ftp::VERBOSE\fR to "1" forces the package to show all responses +from a remote server. The default value is "0". Setting +\fB::ftp::DEBUG\fR 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". +.PP +The command \fB::ftp::DisplayMsg\fR is used to show the different +messages from the ftp session. The setting of \fB::ftp::VERBOSE\fR +determines if this command is called or not. The current +implementation of the command uses the \fBlog\fR package of tcllib +to write the messages to their final destination. This means that the +behaviour of \fB::ftp::DisplayMsg\fR 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 \fB-output\fR to +\fB::ftp::Open\fR for a session specific log command. +.PP +\fICaution\fR: 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. +.SH API +.TP +\fB::ftp::Open\fR \fIserver\fR \fIuser\fR \fIpasswd\fR ?\fIoptions\fR? +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. +.sp +The command takes a host name \fIserver\fR, a user name \fIuser\fR and +a password \fIpassword\fR 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 \fIserver\fR parameter must be the name or internet address (in +dotted decimal notation) of the ftp server to connect to. The +\fIuser\fR and \fIpasswd\fR parameters must contain a valid user name +and password to complete the login process. +.sp +The options overwrite some default values or set special abilities: +.RS +.TP +\fB-blocksize\fR \fIsize\fR +The blocksize is used during data transfer. At most \fIsize\fR bytes +are transfered at once. The default value for this option is 4096. +The package will evaluate the \fB-progress callback\fR for the +session after the transfer of each block. +.TP +\fB-timeout\fR \fIseconds\fR +If \fIseconds\fR is non-zero, then \fB::ftp::Open\fR sets up a timeout +which will occur after the specified number of seconds. The default +value is 600. +.TP +\fB-port\fR \fInumber\fR +The port \fInumber\fR 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. +.TP +\fB-mode\fR \fImode\fR +The transfer \fImode\fR option determines if a file transfer occurs in +\fBactive\fR or \fBpassive\fR 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 \fBactive\fR. +.TP +\fB-progress\fR \fIcallback\fR +This \fIcallback\fR is evaluated whenever a block of data was +transfered. See the option \fB-blocksize\fR for how to specify the +size of the transfered blocks. +.sp +When evaluating the \fIcallback\fR one argument is appended to the +callback script, the current accumulated number of bytes transferred +so far. +.TP +\fB-command\fR \fIcallback\fR +Specifying this option places the connection into asynchronous +mode. The \fIcallback\fR 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. +.sp +When evaluating the \fIcallback\fR 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 \fBerror\fR. +.TP +\fB-output\fR \fIcallback\fR +This option has no default. If it is set the default implementation of +\fB::ftp::DisplayMsg\fR 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. +.RE +.TP +\fB::ftp::Close\fR \fIhandle\fR +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. +.TP +\fB::ftp::Cd\fR \fIhandle\fR \fIdirectory\fR +This command changes the current working directory on the ftp server +to a specified target \fIdirectory\fR. 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 +.RS +.IP \(bu +a subdirectory of the current directory, +.IP \(bu +Two dots, \fB..\fR (as an indicator for the parent directory of +the current directory) +.IP \(bu +or a fully qualified path to a new working directory. +.RE +.TP +\fB::ftp::Pwd\fR \fIhandle\fR +This command returns the complete path of the current working +directory on the ftp server, or an empty string in case of an error. +.TP +\fB::ftp::Type\fR \fIhandle\fR ?\fBascii|binary|tenex\fR? +This command sets the ftp file transfer type to either \fBascii\fR, +\fBbinary\fR, or \fBtenex\fR. The command always returns the +currently set type. If called without type no change is made. +.sp +Currently only \fBascii\fR and \fBbinary\fR types are +supported. There is some early (alpha) support for Tenex mode. The +type \fBascii\fR 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 +\fBbinary\fR on the other hand allows the undisturbed transfer of +non-text files, such as compressed files, images and executables. +.TP +\fB::ftp::List\fR \fIhandle\fR ?\fIpattern\fR? +This command returns a human-readable list of files. Wildcard +expressions such as "\fI*.tcl\fR" are allowed. If \fIpattern\fR +refers to a specific directory, then the contents of that directory +are returned. If the \fIpattern\fR is not a fully-qualified path +name, the command lists entries relative to the current remote +directory. If no \fIpattern\fR is specified, the contents of the +current remote directory is returned. +.sp +The listing includes any system-dependent information that the server +chooses to include. For example most UNIX systems produce output from +the command \fBls -l\fR. 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. +.sp +If the command fails an empty list is returned. +.TP +\fB::ftp::NList\fR \fIhandle\fR ?\fIdirectory\fR? +This command has the same behavior as the \fB::ftp::List\fR command, +except that it only retrieves an abbreviated listing. This means only +file names are returned in a sorted list. +.TP +\fB::ftp::FileSize\fR \fIhandle\fR \fIfile\fR +This command returns the size of the specified \fIfile\fR on the ftp +server. If the command fails an empty string is returned. +.sp +\fIATTENTION!\fR It will not work properly when in ascii mode and +is not supported by all ftp server implementations. +.TP +\fB::ftp::ModTime\fR \fIhandle\fR \fIfile\fR +This command retrieves the time of the last modification of the +\fIfile\fR 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 \fBclock\fR to convert the retrieves value into other formats. +.TP +\fB::ftp::Delete\fR \fIhandle\fR \fIfile\fR +This command deletes the specified \fIfile\fR on the ftp server. The +command returns 1 if the specified file was successfully deleted or 0 +if it failed. +.TP +\fB::ftp::Rename\fR \fIhandle\fR \fIfrom\fR \fIto\fR +This command renames the file \fIfrom\fR in the current directory of +the ftp server to the specified new file name \fIto\fR. 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. +.TP +\fB::ftp::Put\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR | -channel \fIchan\fR) ?\fIremote\fR? +This command transfers a local file \fIlocal\fR to a remote file +\fIremote\fR 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. +.sp +If \fB-data\fR \fIdata\fR is specified instead of a local file, the +system will not transfer a file, but the \fIdata\fR passed into it. In +this case the name of the remote file has to be specified. +.sp +If \fB-channel\fR \fIchan\fR is specified instead of a local file, +the system will not transfer a file, but read the contents of the +channel \fIchan\fR and write this to the remote file. In this case the +name of the remote file has to be specified. After the transfer +\fIchan\fR will be closed. +.TP +\fB::ftp::Append\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR | -channel \fIchan\fR) ?\fIremote\fR? +This command behaves like \fB::ftp::Puts\fR, but appends the +transfered information to the remote file. If the file did not exist +on the server it will be created. +.TP +\fB::ftp::Get\fR \fIhandle\fR \fIremote\fR ?(\fIlocal\fR | -variable \fIvarname\fR | -channel \fIchan\fR)? +This command retrieves a remote file \fIremote\fR on the ftp server +and stores its contents into the local file \fIlocal\fR. 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 +\fIlocal\fR is to be placed in does not exist. +.sp +If \fB-variable\fR \fIvarname\fR is specified, the system will +store the retrieved data into the variable \fIvarname\fR instead of a +file. +.sp +If \fB-channel\fR \fIchan\fR is specified, the system will write +the retrieved data into the channel \fIchan\fR instead of a file. The +system will \fInot\fR close \fIchan\fR after the transfer, this is +the responsibility of the caller to \fB::ftp::Get\fR. +.TP +\fB::ftp::Reget\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR? ?\fIfrom\fR? ?\fIto\fR? +This command behaves like \fB::ftp::Get\fR, except that if local file +\fIlocal\fR exists and is smaller than remote file \fIremote\fR, 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 +\fIlocal\fR is to be placed in does not exist. This command is useful +when transferring very large files over networks that tend to drop +connections. +.sp +Specifying the additional byte offsets \fIfrom\fR and \fIto\fR 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 \fIto\fR leads +to downloading till the end of the file. +.TP +\fB::ftp::Newer\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR? +This command behaves like \fB::ftp::Get\fR, 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 \fIlocal\fR is +to be placed in does not exist. +.TP +\fB::ftp::MkDir\fR \fIhandle\fR \fIdirectory\fR +This command creates the specified \fIdirectory\fR 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. +.TP +\fB::ftp::RmDir\fR \fIhandle\fR \fIdirectory\fR +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. +.TP +\fB::ftp::Quote\fR \fIhandle\fR \fIarg1\fR \fIarg2\fR \fI...\fR +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. +.sp +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. +.TP +\fB::ftp::DisplayMsg\fR \fIhandle\fR \fImsg\fR ?\fIstate\fR? +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 \fBstdout\fR (if +\fB::ftp::VERBOSE\fR 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 +\fBlog\fR is useful for this. +.TP +\fB::ftp::VERBOSE\fR +A state variable controlling the output of the package. Setting +\fB::ftp::VERBOSE\fR to "1" forces the package to show all responses +from a remote server. The default value is "0". +.TP +\fB::ftp::DEBUG\fR +A state variable controlling the output of ftp. Setting +\fB::ftp::DEBUG\fR 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". +.PP +.SH BUGS +.PP +The correct execution of many commands depends upon the proper +behavior by the remote server, network and router configuration. +.PP +An update command placed in the procedure \fB::ftp::DisplayMsg\fR may +run into persistent errors or infinite loops. The solution to this +problem is to use \fBupdate idletasks\fR instead of \fBupdate\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIftp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ftpd, mime, pop3, smtp +.SH KEYWORDS +ftp, internet, net, rfc 959 +.SH CATEGORY +Networking ADDED embedded/man/files/modules/ftp/ftp_geturl.n Index: embedded/man/files/modules/ftp/ftp_geturl.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ftp/ftp_geturl.n @@ -0,0 +1,290 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ftp/ftp_geturl.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ftp::geturl" n 0.2.1 tcllib "ftp client" +.BS +.SH NAME +ftp::geturl \- Uri handler for ftp urls +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBftp::geturl ?0.2.1?\fR +.sp +\fB::ftp::geturl\fR \fIurl\fR +.sp +.BE +.SH DESCRIPTION +This package provides a command which wraps around the client side of +the \fIftp\fR protocol provided by package \fBftp\fR to allow the +retrieval of urls using the \fIftp\fR schema. +.SH API +.TP +\fB::ftp::geturl\fR \fIurl\fR +This command can be used by the generic command \fB::uri::geturl\fR +(See package \fBuri\fR) to retrieve the contents of ftp +urls. Internally it uses the commands of the package \fBftp\fR to +fulfill the request. +.sp +The contents of a \fIftp\fR url are defined as follows: +.RS +.TP +\fIfile\fR +The contents of the specified file itself. +.TP +\fIdirectory\fR +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. +.TP +\fIlink\fR +The attributes of the link, including the path it refers to. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIftp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ftpd, mime, pop3, smtp +.SH KEYWORDS +ftp, internet, net, rfc 959 +.SH CATEGORY +Networking ADDED embedded/man/files/modules/ftpd/ftpd.n Index: embedded/man/files/modules/ftpd/ftpd.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ftpd/ftpd.n @@ -0,0 +1,496 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ftpd/ftpd.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ftpd" n 1.2.6 tcllib "Tcl FTP Server Package" +.BS +.SH NAME +ftpd \- Tcl FTP server implementation +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBftpd ?1.2.6?\fR +.sp +\fB::ftpd::server\fR ?\fImyaddr\fR? +.sp +\fB::ftpd::config\fR ?\fIoption value\fR? ?\fIoption value ...\fR? +.sp +\fIfsCmd\fR \fBappend\fR \fIpath\fR +.sp +\fIfsCmd\fR \fBdelete\fR \fIpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBdlist\fR \fIpath\fR \fIstyle\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBexists\fR \fIpath\fR +.sp +\fIfsCmd\fR \fBmkdir\fR \fIpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBmtime\fR \fIpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBpermissions\fR \fIpath\fR +.sp +\fIfsCmd\fR \fBrename\fR \fIpath\fR \fInewpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBretr\fR \fIpath\fR +.sp +\fIfsCmd\fR \fBrmdir\fR \fIpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBsize\fR \fIpath\fR \fIchannel\fR +.sp +\fIfsCmd\fR \fBstore\fR \fIpath\fR +.sp +.BE +.SH DESCRIPTION +The \fBftpd\fR package provides a simple Tcl-only server library +for the FTP protocol as specified in +RFC 959 (\fIhttp://www.rfc-editor.org/rfc/rfc959.txt\fR). +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 +\fBbgerror\fR will be thrown on the server if there are problems with +the code in the module. +.SH COMMANDS +.TP +\fB::ftpd::server\fR ?\fImyaddr\fR? +Open a listening socket to listen to and accept ftp connections. +myaddr is an optional argument. \fImyaddr\fR is the domain-style name +or numerical IP address of the client-side network interface to use +for the connection. +.TP +\fB::ftpd::config\fR ?\fIoption value\fR? ?\fIoption value ...\fR? +The value is always the name of the command to call as the +callback. The option specifies which callback should be configured. +See section \fBCALLBACKS\fR for descriptions of the arguments and +return values for each of the callbacks. +.RS +.TP +-authIpCmd \fIproc\fR +Callback to authenticate new connections based on the ip-address of +the peer. +.TP +-authUsrCmd \fIproc\fR +Callback to authenticate new connections based on the user logging in +(and the users password). +.TP +-authFileCmd \fIproc\fR +Callback to accept or deny a users access to read and write to a +specific path or file. +.TP +-logCmd \fIproc\fR +Callback for log information generated by the FTP engine. +.TP +-fsCmd \fIproc\fR +Callback to connect the engine to the filesystem it operates on. +.TP +-closeCmd \fIproc\fR +Callback to be called when a connection is closed. This allows the +embedding application to perform its own cleanup operations. +.TP +-xferDoneCmd \fIproc\fR +Callback for transfer completion notification. In other words, it is +called whenever a transfer of data to or from the client has +completed. +.RE +.PP +.SH CALLBACKS +.TP +\fBauthIpCmd\fR 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. +.TP +\fBauthUsrCmd\fR 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. +.TP +\fBauthFileCmd\fR callback +The authFileCmd receives the user (that is currently logged in), the +path or filename that is about to be read or written, and +\fBread\fR or \fBwrite\fR 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. +.TP +\fBlogCmd\fR callback +The logCmd receives a severity and a message as its two arguments. +The severities used within the ftpd package are \fBnote\fR, +\fBdebug\fR, and \fBerror\fR. The logCmd doesn't return +anything. +.TP +\fBfsCmd\fR callback +The fsCmd receives a subcommand, a filename or path, and optional +additional arguments (depending on the subcommand). +.sp +The subcommands supported by the fsCmd are: +.RS +.TP +\fIfsCmd\fR \fBappend\fR \fIpath\fR +The append subcommand receives the filename to append to as its +argument. It returns a writable tcl channel as its return value. +.TP +\fIfsCmd\fR \fBdelete\fR \fIpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBdlist\fR \fIpath\fR \fIstyle\fR \fIchannel\fR +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 \fBnlst\fR or \fBlist\fR, 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 \fBnlst\fR +only the name of the file is printed to the channel. If the style is +\fBlist\fR 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 \fBdlist\fR subcommand returns +nothing. +.TP +\fIfsCmd\fR \fBexists\fR \fIpath\fR +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. +.TP +\fIfsCmd\fR \fBmkdir\fR \fIpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBmtime\fR \fIpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBpermissions\fR \fIpath\fR +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. +.TP +\fIfsCmd\fR \fBrename\fR \fIpath\fR \fInewpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBretr\fR \fIpath\fR +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. +.TP +\fIfsCmd\fR \fBrmdir\fR \fIpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBsize\fR \fIpath\fR \fIchannel\fR +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. +.TP +\fIfsCmd\fR \fBstore\fR \fIpath\fR +The store subcommand receives the path of a file to write as its only +argument. The store subcommand returns a writable channel. +.RE +.TP +\fBcloseCmd\fR +The \fBcloseCmd\fR receives no arguments when it is invoked, and any +return value it may generate is discarded. +.TP +\fBxferDoneCmd\fR sock sock2 file bytes filename err +The \fBxferDoneCmd\fR 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. +.PP +.SH VARIABLES +.TP +\fB::ftpd::cwd\fR +The current working directory for a session when someone first +connects to the FTPD or when the \fBREIN\fR ftp command is received. +.TP +\fB::ftpd::contact\fR +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 +\fBFTP HELP\fR command. +.TP +\fB::ftpd::port\fR +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. +.TP +\fB::ftpd::welcome\fR +The message that is printed out when the user first connects to the +ftp server. +.TP +\fB::ftpd::CurrentSocket\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIftpd\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ftp, ftpd, ftpserver, rfc 959, services +.SH CATEGORY +Networking ADDED embedded/man/files/modules/fumagic/cfront.n Index: embedded/man/files/modules/fumagic/cfront.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fumagic/cfront.n @@ -0,0 +1,310 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fumagic/cfront.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::magic::cfront" n 1.0 tcllib "file utilities" +.BS +.SH NAME +fileutil::magic::cfront \- Generator core for compiler of magic(5) files +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::magic::cfront ?1.0?\fR +.sp +package require \fBfileutil::magic::cgen ?1.0?\fR +.sp +package require \fBfileutil::magic::rt ?1.0?\fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBfileutil \fR +.sp +\fB::fileutil::magic::cfront::compile\fR \fIpath\fR... +.sp +\fB::fileutil::magic::cfront::procdef\fR \fIprocname\fR \fIpath\fR... +.sp +\fB::fileutil::magic::cfront::install\fR \fIpath\fR... +.sp +.BE +.SH DESCRIPTION +.PP +This package provides the frontend of a compiler of magic(5) files +into recognizers based on the \fBfileutil::magic::rt\fR recognizer +runtime package. For the generator backed used by this compiler see +the package \fBfileutil::magic::cgen\fR. +.SH COMMANDS +.TP +\fB::fileutil::magic::cfront::compile\fR \fIpath\fR... +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. +.sp +All the files have to be in the format specified by magic(5). +.sp +The result of the command is a Tcl script containing the generated +recognizer. +.TP +\fB::fileutil::magic::cfront::procdef\fR \fIprocname\fR \fIpath\fR... +This command behaves like \fB::fileutil::magic::cfront::compile\fR +with regard to the specified path arguments, then wraps the resulting +recognizer script into a procedure named \fIprocname\fR, puts code +setting up the namespace of \fIprocname\fR in front, and returns the +resulting script. +.TP +\fB::fileutil::magic::cfront::install\fR \fIpath\fR... +This command uses \fB::fileutil::magic::cfront::procdef\fR to compile +each of the paths into a recognizer procedure and installs the result +in the current interpreter. +.sp +The name of each new procedure is derived from the name of the +file/directory used in its creation, with file/directory "\fIFOO\fR" +causing the creation of procedure \fB::fileutil::magic::/FOO::run\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil :: magic\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +file(1), fileutil, magic(5) +.SH KEYWORDS +file recognition, file type, file utilities, mime, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fumagic/cgen.n Index: embedded/man/files/modules/fumagic/cgen.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fumagic/cgen.n @@ -0,0 +1,303 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fumagic/cgen.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::magic::cgen" n 1.0 tcllib "file utilities" +.BS +.SH NAME +fileutil::magic::cgen \- Generator core for compiler of magic(5) files +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::magic::cgen ?1.0?\fR +.sp +package require \fBfileutil::magic::rt ?1.0?\fR +.sp +package require \fBstruct::tree \fR +.sp +package require \fBstruct::list \fR +.sp +\fB::fileutil::magic::cgen::2tree\fR \fIscript\fR +.sp +\fB::fileutil::magic::cgen::treedump\fR \fItree\fR +.sp +\fB::fileutil::magic::cgen::treegen\fR \fItree\fR \fInode\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides the generator backend for a compiler of magic(5) +files into recognizers based on the \fBfileutil::magic::rt\fR +recognizer runtime package. For the compiler frontend using this +generator see the package \fBfileutil::magic::cfront\fR. +.SH COMMANDS +.TP +\fB::fileutil::magic::cgen::2tree\fR \fIscript\fR +This command converts the recognizer specified by the \fIscript\fR +into a tree and returns the object command of that tree as its +result. It uses the package \fBstruct::tree\fR for the tree. +.sp +The \fIscript\fR is in the format specified by magic(5). +.TP +\fB::fileutil::magic::cgen::treedump\fR \fItree\fR +This command takes a \fItree\fR as generated by +\fB::fileutil::magic::cgen::2tree\fR and returns a string encoding the +tree for human consumption, to aid in debugging. +.TP +\fB::fileutil::magic::cgen::treegen\fR \fItree\fR \fInode\fR +This command takes a \fItree\fR as generated by +\fB::fileutil::magic::cgen::2tree\fR and returns a Tcl script, the +recognizer for the file types represented by the sub-tree rooted at +the \fInode\fR. +The generated script makes extensive use of the commands provided by +the recognizer runtime package \fBfileutil::magic::rt\fR to +perform its duties. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil :: magic\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +file(1), fileutil, magic(5) +.SH KEYWORDS +file recognition, file type, file utilities, mime, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fumagic/filetypes.n Index: embedded/man/files/modules/fumagic/filetypes.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fumagic/filetypes.n @@ -0,0 +1,291 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fumagic/filetypes.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::magic::filetype" n 1.0.2 tcllib "file utilities" +.BS +.SH NAME +fileutil::magic::filetype \- Procedures implementing file-type recognition +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::magic::filetype ?1.0.2?\fR +.sp +\fB::fileutil::magic::filetype\fR \fIfilename\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a command for the recognition of file types in +pure Tcl. +.PP +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. +.PP +\fIBeware!\fR This recognizer is large, about 276 Kilobyte of +generated Tcl code. +.TP +\fB::fileutil::magic::filetype\fR \fIfilename\fR +This command is similar to the command \fBfileutil::fileType\fR. +.sp +The output of the command for the specified file is a string +describing the type of the file. +.sp +This list will be empty if the type of the file is not recognized. +.PP +.SH REFERENCES +.IP [1] +\fIFile(1) sources\fR [ftp://ftp.astron.com/pub/file/] +This site contains the current sources for the file command, including +the magic definitions used by it. The latter were used by us to +generate this recognizer. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil :: magic\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +file(1), fileutil, magic(5) +.SH KEYWORDS +file recognition, file type, file utilities, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fumagic/mimetypes.n Index: embedded/man/files/modules/fumagic/mimetypes.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fumagic/mimetypes.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fumagic/mimetypes.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::magic::mimetype" n 1.0.2 tcllib "file utilities" +.BS +.SH NAME +fileutil::magic::mimetype \- Procedures implementing mime-type recognition +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::magic::mimetype ?1.0.2?\fR +.sp +\fB::fileutil::magic::mimetype\fR \fIfilename\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a command for the recognition of file types in +pure Tcl. The output is standardized to mime-types. +.PP +The core part of the recognizer was generated from a "magic(5)" file +containing the checks to perform to recognize files, and associated +mime-types. +.TP +\fB::fileutil::magic::mimetype\fR \fIfilename\fR +This command is similar to the command \fBfileutil::fileType\fR. +.sp +The output of the command for the specified file is not a list of +attributes describing the type of the file, but a list of standard +mime-types the file may have. +.sp +This list will be empty if the type of the file is not recognized. +.PP +.SH REFERENCES +.IP [1] +\fIFile(1) sources\fR [ftp://ftp.astron.com/pub/file/] +This site contains the current sources for the file command, including +the magic definitions used by it. The latter were used by us to +generate this recognizer. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil :: magic\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +file(1), fileutil, magic(5) +.SH KEYWORDS +file recognition, file type, file utilities, mime, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/fumagic/rtcore.n Index: embedded/man/files/modules/fumagic/rtcore.n ================================================================== --- /dev/null +++ embedded/man/files/modules/fumagic/rtcore.n @@ -0,0 +1,497 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/fumagic/rtcore.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "fileutil::magic::rt" n 1.0 tcllib "file utilities" +.BS +.SH NAME +fileutil::magic::rt \- Runtime core for file type recognition engines written in pure Tcl +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBfileutil::magic::rt ?1.0?\fR +.sp +\fB::fileutil::magic::rt::open\fR \fIfilename\fR +.sp +\fB::fileutil::magic::rt::close\fR +.sp +\fB::fileutil::magic::rt::file_start\fR \fIname\fR +.sp +\fB::fileutil::magic::rt::result\fR ?\fImsg\fR? +.sp +\fB::fileutil::magic::rt::resultv\fR ?\fImsg\fR? +.sp +\fB::fileutil::magic::rt::emit\fR \fImsg\fR +.sp +\fB::fileutil::magic::rt::offset\fR \fIwhere\fR +.sp +\fB::fileutil::magic::rt::Nv\fR \fItype\fR \fIoffset\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::N\fR \fItype\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::Nvx\fR \fIatlevel\fR \fItype\fR \fIoffset\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::Nx\fR \fIatlevel\fR \fItype\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::S\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::Sx\fR \fIatlevel\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +.sp +\fB::fileutil::magic::rt::L\fR \fInewlevel\fR +.sp +\fB::fileutil::magic::rt::I\fR \fIbase\fR \fItype\fR \fIdelta\fR +.sp +\fB::fileutil::magic::rt::R\fR \fIoffset\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fBfileutil::magic::mimetypes\fR and +\fBfileutil::magic::filetypes\fR, and the two engine compiler +packages \fBfileutil::magic::cgen\fR and +\fBfileutil::magic::cfront\fR. +.SH COMMANDS +.TP +\fB::fileutil::magic::rt::open\fR \fIfilename\fR +This command initializes the runtime and prepares the file +\fIfilename\fR for use by the system. +This command has to be invoked first, before any other command of this +package. +.sp +The command returns the channel handle of the opened file as its +result. +.TP +\fB::fileutil::magic::rt::close\fR +This command closes the last file opened via +\fB::fileutil::magic::rt::open\fR and shuts the runtime down. +This command has to be invoked last, after the file has been dealt +with completely. +Afterward another invokation of \fB::fileutil::magic::rt::open\fR is +required to process another file. +.sp +This command returns the empty string as its result. +.TP +\fB::fileutil::magic::rt::file_start\fR \fIname\fR +This command marks the start of a magic file when debugging. It +returns the empty string as its result. +.TP +\fB::fileutil::magic::rt::result\fR ?\fImsg\fR? +This command returns the current result and stops processing. +.sp +If \fImsg\fR is specified its text is added to the result before it is +returned. See \fB::fileutil::magic::rt::emit\fR for the allowed +special character sequences. +.TP +\fB::fileutil::magic::rt::resultv\fR ?\fImsg\fR? +This command returns the current result. +In contrast to \fB::fileutil::magic::rt::result\fR processing +continues. +.sp +If \fImsg\fR is specified its text is added to the result before it is +returned. See \fB::fileutil::magic::rt::emit\fR for the allowed +special character sequences. +.TP +\fB::fileutil::magic::rt::emit\fR \fImsg\fR +This command adds the text \fImsg\fR 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. +.RS +.TP +\fB\\b\fR +This sequence is removed +.TP +\fB%s\fR +Replaced with the last buffered string value. +.TP +\fB%ld\fR +Replaced with the last buffered numeric value. +.TP +\fB%d\fR +See above. +.RE +.TP +\fB::fileutil::magic::rt::Nv\fR \fItype\fR \fIoffset\fR ?\fIqual\fR? +This command fetches the numeric value with \fItype\fR from the +absolute location \fIoffset\fR and returns it as its result. The +fetched value is further stored in the numeric buffer. +.sp +If \fIqual\fR 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. +.CS + + + & number + +.CE +.IP +For example: +.CS + + + Nv lelong 0 &0x8080ffff + +.CE +.IP +For the possible types see section \fBNUMERIC TYPES\fR. +.TP +\fB::fileutil::magic::rt::N\fR \fItype\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +This command behaves mostly like \fB::fileutil::magic::rt::Nv\fR, +except that it compares the fetched and masked value against \fIval\fR +as specified with \fIcomp\fR and returns the result of that +comparison. +.sp +The argument \fIcomp\fR has to contain one of Tcl's comparison +operators, and the comparison made will be +.CS + + + <val> <comp> <fetched-and-masked-value> + +.CE +.sp +The special comparison operator \fBx\fR signals that no comparison +should be done, or, in other words, that the fetched value will always +match \fIval\fR. +.TP +\fB::fileutil::magic::rt::Nvx\fR \fIatlevel\fR \fItype\fR \fIoffset\fR ?\fIqual\fR? +This command behaves like \fB::fileutil::magic::rt::Nv\fR, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the level \fIatlevel\fR, for later use by +\fB::fileutil::magic::rt::R\fR. +.TP +\fB::fileutil::magic::rt::Nx\fR \fIatlevel\fR \fItype\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +This command behaves like \fB::fileutil::magic::rt::N\fR, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the level \fIatlevel\fR, for later use by +\fB::fileutil::magic::rt::R\fR. +.TP +\fB::fileutil::magic::rt::S\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +This command behaves like \fB::fileutil::magic::rt::N\fR, 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. +.TP +\fB::fileutil::magic::rt::Sx\fR \fIatlevel\fR \fIoffset\fR \fIcomp\fR \fIval\fR ?\fIqual\fR? +This command behaves like \fB::fileutil::magic::rt::S\fR, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the level \fIatlevel\fR, for later use by +\fB::fileutil::magic::rt::R\fR. +.TP +\fB::fileutil::magic::rt::L\fR \fInewlevel\fR +This command sets the current level in the calling context to +\fInewlevel\fR. The command returns the empty string as its result. +.TP +\fB::fileutil::magic::rt::I\fR \fIbase\fR \fItype\fR \fIdelta\fR +This command handles base locations specified indirectly through the +contents of the inspected file. It returns the sum of \fIdelta\fR and +the value of numeric \fItype\fR fetched from the absolute location +\fIbase\fR. +.sp +For the possible types see section \fBNUMERIC TYPES\fR. +.TP +\fB::fileutil::magic::rt::R\fR \fIoffset\fR +This command handles base locations specified relative to the end of +the last field one level above. +.sp +In other words, the command computes an absolute location in the file +based on the relative \fIoffset\fR 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. +.PP +.SH "NUMERIC TYPES" +.TP +\fBbyte\fR +8-bit integer +.TP +\fBshort\fR +16-bit integer, stored in native endianess +.TP +\fBbeshort\fR +see above, stored in big endian +.TP +\fBleshort\fR +see above, stored in small/little endian +.TP +\fBlong\fR +32-bit integer, stored in native endianess +.TP +\fBbelong\fR +see above, stored in big endian +.TP +\fBlelong\fR +see above, stored in small/little endian +.PP +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. +.TP +\fBdate\fR +32-bit integer timestamp, stored in native endianess +.TP +\fBbedate\fR +see above, stored in big endian +.TP +\fBledate\fR +see above, stored in small/little endian +.TP +\fBldate\fR +32-bit integer timestamp, stored in native endianess +.TP +\fBbeldate\fR +see above, stored in big endian +.TP +\fBleldate\fR +see above, stored in small/little endian +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIfileutil :: magic\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +file(1), fileutil, magic(5) +.SH KEYWORDS +file recognition, file type, file utilities, mime, type +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/generator/generator.n Index: embedded/man/files/modules/generator/generator.n ================================================================== --- /dev/null +++ embedded/man/files/modules/generator/generator.n @@ -0,0 +1,755 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/generator/generator.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "generator" n 0.1 tcllib "Tcl Generator Commands" +.BS +.SH NAME +generator \- Procedures for creating and using generators. +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBgenerator ?0.1?\fR +.sp +\fBgenerator\fR \fBdefine\fR \fIname\fR \fIparams\fR \fIbody\fR +.sp +\fBgenerator\fR \fByield\fR \fIarg\fR ?\fIargs..\fR? +.sp +\fBgenerator\fR \fBforeach\fR \fIvarList\fR \fIgenerator\fR \fIvarList\fR \fIgenerator\fR ?...? \fIbody\fR +.sp +\fBgenerator\fR \fBnext\fR \fIgenerator\fR ?\fIvarName..\fR? +.sp +\fBgenerator\fR \fBexists\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBnames\fR +.sp +\fBgenerator\fR \fBdestroy\fR ?\fIgenerator..\fR? +.sp +\fBgenerator\fR \fBfinally\fR \fIcmd\fR ?\fIarg..\fR? +.sp +\fBgenerator\fR \fBfrom\fR \fIformat\fR \fIvalue\fR +.sp +\fBgenerator\fR \fBto\fR \fIformat\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBmap\fR \fIfunction\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfilter\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBreduce\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfoldl\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfoldr\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBall\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBand\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBany\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBconcat\fR \fIgenerator\fR ?\fIgenerator..\fR? +.sp +\fBgenerator\fR \fBconcatMap\fR \fIfunction\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBdrop\fR \fIn\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBdropWhile\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBcontains\fR \fIelement\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfoldl1\fR \fIfunction\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfoldli\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBfoldri\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBhead\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBtail\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBinit\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBtakeList\fR \fIn\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBtake\fR \fIn\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBiterate\fR \fIfunction\fR \fIinit\fR +.sp +\fBgenerator\fR \fBlast\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBlength\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBor\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBproduct\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBrepeat\fR \fIn\fR \fIvalue..\fR +.sp +\fBgenerator\fR \fBsum\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBtakeWhile\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBsplitWhen\fR \fIpredicate\fR \fIgenerator\fR +.sp +\fBgenerator\fR \fBscanl\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBgenerator\fR package provides commands to define and iterate over +generator expressions. A \fIgenerator\fR is a command that returns a sequence +of values. However, unlike an ordinary command that returns a list, a +generator \fIyields\fR 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. +.PP +The package exports a single ensemble command, \fBgenerator\fR. All +functionality is provided as subcommands of this command. The core subcommands +of the package are \fBdefine\fR, \fByield\fR, and \fBforeach\fR. The +\fBdefine\fR command works like Tcl's \fBproc\fR 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 \fBforeach\fR command that loops through the values of +one or more generators. This loop construct mimicks the functionality of the +built-in Tcl \fBforeach\fR 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 \fBdefine\fR +command to define the generator, and then call \fByield\fR instead of \fBreturn\fR. +For example, we can define a generator for looping through the integers +in a particular range: +.PP +.CS + + + 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" + } + +.CE +.PP +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: +.PP +.CS + + + generator define nats {} { + while 1 { generator yield [incr nat] } + } + generator foreach n [nats] { + if {$n > 100} { break } + } + +.CE +.SH COMMANDS +.TP +\fBgenerator\fR \fBdefine\fR \fIname\fR \fIparams\fR \fIbody\fR +Creates a new generator procedure. The arguments to the command are identical to +those for \fBproc\fR: a \fIname\fR, 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. +.TP +\fBgenerator\fR \fByield\fR \fIarg\fR ?\fIargs..\fR? +Used in the definition of a generator, this command returns the next set of +values to the consumer. Once the \fByield\fR 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 +\fByield\fR command must be called with at least one argument, but can be called with +multiple arguments, in which case this is equivalent to calling \fByield\fR +once for each argument. +.TP +\fBgenerator\fR \fBforeach\fR \fIvarList\fR \fIgenerator\fR \fIvarList\fR \fIgenerator\fR ?...? \fIbody\fR +Loops through one or more generators, assigning the next values to variables and +then executing the loop body. Works much like the built-in \fBforeach\fR +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 \fBforeach\fR, 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. +.sp +The \fBforeach\fR 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. +.sp +The \fBforeach\fR 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). +.TP +\fBgenerator\fR \fBnext\fR \fIgenerator\fR ?\fIvarName..\fR? +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. +.TP +\fBgenerator\fR \fBexists\fR \fIgenerator\fR +Returns 1 if the generator (still) exists, or 0 otherwise. +.TP +\fBgenerator\fR \fBnames\fR +Returns a list of all currently existing generator commands. +.TP +\fBgenerator\fR \fBdestroy\fR ?\fIgenerator..\fR? +Destroys one or more generators, freeing any associated resources. +.TP +\fBgenerator\fR \fBfinally\fR \fIcmd\fR ?\fIarg..\fR? +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 +\fBfinally\fR block in the \fBtry\fR 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 +\fBfinally\fR to ensure that the file is closed whenever the generator is +destroyed: +.sp +.CS + + + 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 + +.CE +.sp +If you create a generator that consumes another generator (such as the standard +\fBmap\fR and \fBfilter\fR generators defined later), then you should use +a \fBfinally\fR command to ensure that this generator is destroyed when its +parent is. For example, the \fBmap\fR generator is defined as follows: +.sp +.CS + + + generator define map {f xs} { + generator finally generator destroy $xs + generator foreach x $xs { generator yield [{*}$f $x] } + } + +.CE +.TP +\fBgenerator\fR \fBfrom\fR \fIformat\fR \fIvalue\fR +Creates a generator from a data structure. Currently, supported formats are +\fBlist\fR, \fBdict\fR, or \fBstring\fR. 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. +.TP +\fBgenerator\fR \fBto\fR \fIformat\fR \fIgenerator\fR +Converts a generator into a data structure. This is the reverse operation of the +\fBfrom\fR command, and supports the same data structures. The two operations +obey the following identity laws (where \fB=\fR is interpreted +appropriately): +.sp +.CS + + + [generator to $fmt [generator from $fmt $value]] = $value + [generator from $fmt [generator to $fmt $gen]] = $gen + + +.CE +.PP +.SH PRELUDE +.PP +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. \fIWarning:\fR 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. +.TP +\fBgenerator\fR \fBmap\fR \fIfunction\fR \fIgenerator\fR +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 \fBnats\fR is defined as earlier): +.sp +.CS + + + proc square x { expr {$x * $x} } + generator foreach n [generator map square [nats]] { + puts "n = $n" + if {$n > 1000} { break } + } + +.CE +.TP +\fBgenerator\fR \fBfilter\fR \fIpredicate\fR \fIgenerator\fR +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 \fBemployees\fR +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: +.sp +.CS + + + proc salary> {amount person} { expr {[dict get $person salary] > $amount} } + set fat-cats [generator filter {salary> 100000} $employees] + +.CE +.TP +\fBgenerator\fR \fBreduce\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +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 \fIzero\fR 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 \fBreduce\fR command as \fIfolding\fR +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 \fB+\fR operator between them, with 0 as the identity: +.sp +.CS + + + # 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]] + +.CE +.sp +The \fBreduce\fR 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): +.sp +.CS + + + proc * {x y} { expr {$x * $y} } + proc prod gen { generator reduce * 0 $gen } + proc fac n { prod [range 1 $n] } + +.CE +.sp +However, while the \fBreduce\fR 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: +.sp +.CS + + + sum [nats]; # Never returns + +.CE +.TP +\fBgenerator\fR \fBfoldl\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +This is an alias for the \fBreduce\fR command. +.TP +\fBgenerator\fR \fBfoldr\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +This is the right-associative version of \fBreduce\fR. 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. +.TP +\fBgenerator\fR \fBall\fR \fIpredicate\fR \fIgenerator\fR +Returns true if all elements of the generator satisfy the given predicate. +.TP +\fBgenerator\fR \fBand\fR \fIgenerator\fR +Returns true if all elements of the generator are true (i.e., takes the logical +conjunction of the elements). +.TP +\fBgenerator\fR \fBany\fR \fIgenerator\fR +Returns true if any of the elements of the generator are true (i.e., logical +disjunction). +.TP +\fBgenerator\fR \fBconcat\fR \fIgenerator\fR ?\fIgenerator..\fR? +Returns a generator which is the concatenation of each of the argument +generators. +.TP +\fBgenerator\fR \fBconcatMap\fR \fIfunction\fR \fIgenerator\fR +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 \fBconcat\fR applied to the result of \fBmap\fR. +.TP +\fBgenerator\fR \fBdrop\fR \fIn\fR \fIgenerator\fR +Removes the given number of elements from the front of the generator and returns +the resulting generator with those elements removed. +.TP +\fBgenerator\fR \fBdropWhile\fR \fIpredicate\fR \fIgenerator\fR +Removes all elements from the front of the generator that satisfy the predicate. +.TP +\fBgenerator\fR \fBcontains\fR \fIelement\fR \fIgenerator\fR +Returns true if the generator contains the given element. Note that this will +destroy the generator! +.TP +\fBgenerator\fR \fBfoldl1\fR \fIfunction\fR \fIgenerator\fR +A version of \fBfoldl\fR that takes the \fIzero\fR argument from the first +element of the generator. Therefore this function is only valid on non-empty +generators. +.TP +\fBgenerator\fR \fBfoldli\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +A version of \fBfoldl\fR 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. +.TP +\fBgenerator\fR \fBfoldri\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +Right-associative version of \fBfoldli\fR. +.TP +\fBgenerator\fR \fBhead\fR \fIgenerator\fR +Returns the first element of the generator. +.TP +\fBgenerator\fR \fBtail\fR \fIgenerator\fR +Removes the first element of the generator, returning the rest. +.TP +\fBgenerator\fR \fBinit\fR \fIgenerator\fR +Returns a new generator consisting of all elements except the last of the +argument generator. +.TP +\fBgenerator\fR \fBtakeList\fR \fIn\fR \fIgenerator\fR +Returns the next \fIn\fR elements of the generator as a list. If not enough +elements are left in the generator, then just the remaining elements are +returned. +.TP +\fBgenerator\fR \fBtake\fR \fIn\fR \fIgenerator\fR +Returns the next \fIn\fR elements of the generator as a new generator. The old +generator is destroyed. +.TP +\fBgenerator\fR \fBiterate\fR \fIfunction\fR \fIinit\fR +Returns an infinite generator formed by repeatedly applying the function to the +initial argument. For example, the Fibonacci numbers can be defined as follows: +.sp +.CS + + + 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}] } + +.CE +.TP +\fBgenerator\fR \fBlast\fR \fIgenerator\fR +Returns the last element of the generator (if it exists). +.TP +\fBgenerator\fR \fBlength\fR \fIgenerator\fR +Returns the length of the generator, destroying it in the process. +.TP +\fBgenerator\fR \fBor\fR \fIpredicate\fR \fIgenerator\fR +Returns 1 if any of the elements of the generator satisfy the predicate. +.TP +\fBgenerator\fR \fBproduct\fR \fIgenerator\fR +Returns the product of the numbers in a generator. +.TP +\fBgenerator\fR \fBrepeat\fR \fIn\fR \fIvalue..\fR +Returns a generator that consists of \fIn\fR copies of the given elements. The +special value \fIInf\fR can be used to generate an infinite sequence. +.TP +\fBgenerator\fR \fBsum\fR \fIgenerator\fR +Returns the sum of the values in the generator. +.TP +\fBgenerator\fR \fBtakeWhile\fR \fIpredicate\fR \fIgenerator\fR +Returns a generator of the first elements in the argument generator that satisfy +the predicate. +.TP +\fBgenerator\fR \fBsplitWhen\fR \fIpredicate\fR \fIgenerator\fR +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: +.sp +.CS + + + set xs [generator from list {a | b | c}] + generator split {string equal "|"} $xs ;# returns a then b then c + +.CE +.TP +\fBgenerator\fR \fBscanl\fR \fIfunction\fR \fIzero\fR \fIgenerator\fR +Similar to \fBfoldl\fR, but returns a generator of all of the intermediate +values for the accumulator argument. The final element of this generator is +equivalent to \fBfoldl\fR called on the same arguments. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +Please report any errors in this document, or in the package it describes, to +\fINeil Madden\fR [mailto:nem@cs.nott.ac.uk]. +.SH KEYWORDS +control structure, coroutine, filter, foldl, foldr, foreach, generator, iterator, map, reduce, scanl ADDED embedded/man/files/modules/gpx/gpx.n Index: embedded/man/files/modules/gpx/gpx.n ================================================================== --- /dev/null +++ embedded/man/files/modules/gpx/gpx.n @@ -0,0 +1,404 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/gpx/gpx.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010, Keith Vetter <kvetter@gmail.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "gpx" n 0.9 tcllib "GPS eXchange Format (GPX)" +.BS +.SH NAME +gpx \- Extracts waypoints, tracks and routes from GPX files +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBgpx ?0.9?\fR +.sp +\fB::gpx::Create\fR \fIgpxFilename\fR ?\fIrawXML\fR? +.sp +\fB::gpx::Cleanup\fR \fItoken\fR +.sp +\fB::gpx::GetGPXMetadata\fR \fItoken\fR +.sp +\fB::gpx::GetWaypointCount\fR \fItoken\fR +.sp +\fB::gpx::GetAllWaypoints\fR \fItoken\fR +.sp +\fB::gpx::GetTrackCount\fR \fItoken\fR +.sp +\fB::gpx::GetTrackMetadata\fR \fItoken\fR \fIwhichTrack\fR +.sp +\fB::gpx::GetTrackPoints\fR \fItoken\fR \fIwhichTrack\fR +.sp +\fB::gpx::GetRouteCount\fR \fItoken\fR +.sp +\fB::gpx::GetRouteMetadata\fR \fItoken\fR \fIwhichRoute\fR +.sp +\fB::gpx::GetRoutePoints\fR \fItoken\fR \fIwhichRoute\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::gpx::Create\fR \fIgpxFilename\fR ?\fIrawXML\fR? +The \fB::gpx::Create\fR is the first command called to process GPX +data. It takes the GPX data from either the \fIrawXML\fR +parameter if present or from the contents of \fIgpxFilename\fR, +and parses it using \fItdom\fR. It returns a token value that is used +by all the other commands. +.TP +\fB::gpx::Cleanup\fR \fItoken\fR +This procedure cleans up resources associated with \fItoken\fR. +It is \fIstrongly\fR 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 \fB::gpx::Create\fR enough times, the +memory leak could cause a performance hit...or worse. +.TP +\fB::gpx::GetGPXMetadata\fR \fItoken\fR +This procedure returns a dictionary of the metadata +associated with the GPX data identified by \fItoken\fR. +The format of the metadata dictionary is described +below, but keys \fIversion\fR and \fIcreator\fR +will always be present. +.TP +\fB::gpx::GetWaypointCount\fR \fItoken\fR +This procedure returns the number of waypoints defined in the GPX +data identified by \fItoken\fR. +.TP +\fB::gpx::GetAllWaypoints\fR \fItoken\fR +This procedure returns the a list of waypoints defined in the GPX +data identified by \fItoken\fR. The format of each waypoint item +is described below. +.TP +\fB::gpx::GetTrackCount\fR \fItoken\fR +This procedure returns the number of tracks defined in the GPX +data identified by \fItoken\fR. +.TP +\fB::gpx::GetTrackMetadata\fR \fItoken\fR \fIwhichTrack\fR +This procedure returns a dictionary of the metadata +associated track number \fIwhichTrack\fR (1 based) in +the GPX data identified by \fItoken\fR. +The format of the metadata dictionary is described below. +.TP +\fB::gpx::GetTrackPoints\fR \fItoken\fR \fIwhichTrack\fR +The procedure returns a list of track points comprising track +number \fIwhichTrack\fR (1 based) in the GPX data identified by +\fItoken\fR. The format of the metadata dictionary is described below. +.TP +\fB::gpx::GetRouteCount\fR \fItoken\fR +This procedure returns the number of routes defined in the GPX +data identified by \fItoken\fR. +.TP +\fB::gpx::GetRouteMetadata\fR \fItoken\fR \fIwhichRoute\fR +This procedure returns a dictionary of the metadata +associated route number \fIwhichRoute\fR (1 based) in +the GPX data identified by \fItoken\fR. +The format of the metadata dictionary is described below. +.TP +\fB::gpx::GetRoutePoints\fR \fItoken\fR \fIwhichRoute\fR +The procedure returns a list of route points comprising route +number \fIwhichRoute\fR (1 based) in the GPX data identified by +\fItoken\fR. The format of the metadata dictionary is described below. +.PP +.SH "DATA STRUCTURES" +.TP +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 \fIhref\fR and optionally +\fItext\fR and \fItype\fR. +.TP +point item +Each item in a track or route list of points consists of +a list of three elements: \fIlatitude\fR, \fIlongitude\fR and +\fImetadata dictionary\fR. \fILatitude\fR and \fIlongitude\fR +are decimal numbers. The \fImetadata dictionary\fR format is +described above. For points in a track, typically there will +always be ele (elevation) and time metadata keys. +.PP +.SH EXAMPLE +.CS + + +% 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 + +.CE +.SH REFERENCES +.IP [1] +GPX: the GPS Exchange Format +(\fIhttp://www.topografix.com/gpx.asp\fR) +.IP [2] +GPX 1.1 Schema Documentation (\fIhttp://www.topografix.com/GPX/1/1/\fR) +.IP [3] +GPX 1.0 Developer's Manual (\fIhttp://www.topografix.com/gpx_manual.asp\fR) +.PP +.SH AUTHOR +Keith Vetter +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgpx\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +gps, gpx +.SH CATEGORY +File formats +.SH COPYRIGHT +.nf +Copyright (c) 2010, Keith Vetter <kvetter@gmail.com> + +.fi ADDED embedded/man/files/modules/grammar_aycock/aycock.n Index: embedded/man/files/modules/grammar_aycock/aycock.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_aycock/aycock.n @@ -0,0 +1,371 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_aycock/aycock.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 by Kevin B. Kenny <kennykb@acm.org> +'\" Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::aycock" n 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl" +.BS +.SH NAME +grammar::aycock \- Aycock-Horspool-Earley parser generator for Tcl +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBgrammar::aycock ?1.0?\fR +.sp +\fB::aycock::parser\fR \fIgrammar\fR ?\fB-verbose\fR? +.sp +\fIparserName\fR \fBparse\fR \fIsymList\fR \fIvalList\fR ?\fIclientData\fR? +.sp +\fIparserName\fR \fBdestroy\fR +.sp +\fIparserName\fR \fBterminals\fR +.sp +\fIparserName\fR \fBnonterminals\fR +.sp +\fIparserName\fR \fBsave\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBgrammar::aycock\fR package +implements a parser generator for the class of parsers described +in John Aycock and R. Nigel Horspool. Practical Earley Parsing. +\fIThe Computer Journal,\fR \fI45\fR(6):620-630, 2002. +\fIhttp://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254\fR +.SH PROCEDURES +The \fBgrammar::aycock\fR package exports the single procedure: +.TP +\fB::aycock::parser\fR \fIgrammar\fR ?\fB-verbose\fR? +Generates a parser for the given \fIgrammar\fR, and returns its +name. If the optional \fB-verbose\fR 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 +\fBOBJECT COMMAND\fR below. +.PP +.SH "OBJECT COMMAND" +.TP +\fIparserName\fR \fBparse\fR \fIsymList\fR \fIvalList\fR ?\fIclientData\fR? +Invokes a parser returned from \fB::aycock::parser\fR. \fIsymList\fR is +a list of grammar symbols representing the terminals in an input +string, and \fIvalList\fR is a list of their semantic values. The +result is the semantic value of the entire string when parsed. +.TP +\fIparserName\fR \fBdestroy\fR +Destroys a parser constructed by \fB::aycock::parser\fR. +.TP +\fIparserName\fR \fBterminals\fR +Returns a list of terminal symbols that may be presented in the +\fIsymList\fR argument to the \fBparse\fR object command. +.TP +\fIparserName\fR \fBnonterminals\fR +Returns a list of nonterminal symbols that were defined in the +parser's grammar. +.TP +\fIparserName\fR \fBsave\fR +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 \fBgrammar::aycock::runtime\fR, +which is also automatically loaded +when the \fBgrammar::aycock\fR package is loaded. +.PP +.SH DESCRIPTION +The \fBgrammar::aycock::parser\fR command accepts a grammar expressed as +a Tcl list. The list must be structured as the concatenation of a set +of \fIrule\fRs. Each \fIrule\fR comprises a variable number of +elements in the list: +.IP \(bu +The name of the nonterminal symbol that the rule reduces. +.IP \(bu +The literal string, \fB::=\fR +.IP \(bu +Zero or more names of terminal or nonterminal symbols that +comprise the right-hand-side of the rule. +.IP \(bu +Finally, a Tcl script to execute when the rule is reduced. +Within the given script, a variable called \fB_\fR 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 \fIclientData\fR parameter was passed to the +\fBparse\fR method, it is available in a variable called +\fBclientData\fR. 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. +.PP +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 \fBgrammar::aycock\fR package is +perhaps best adapted to natural-language processing or the parsing of +extraordinarily complex languages in which ambiguity can be tolerated. +.SH EXAMPLE +The following code demonstrates a trivial desk calculator, admitting +only \fB+\fR, \fB*\fR and parentheses as its operators. It also +shows the format in which the lexical analyzer is expected to present +terminal symbols to the parser. +.CS + + +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 + +.CE +The example, when run, prints \fB40\fR. +.SH KEYWORDS +Aycock, Earley, Horspool, parser, compiler +.SH KEYWORDS +ambiguous, aycock, earley, grammar, horspool, parser, parsing, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2006 by Kevin B. Kenny <kennykb@acm.org> +Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> + +.fi ADDED embedded/man/files/modules/grammar_fa/dacceptor.n Index: embedded/man/files/modules/grammar_fa/dacceptor.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_fa/dacceptor.n @@ -0,0 +1,332 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_fa/dacceptor.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::fa::dacceptor" n 0.1.1 tcllib "Finite automaton operations and usage" +.BS +.SH NAME +grammar::fa::dacceptor \- Create and use deterministic acceptors +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBgrammar::fa::dacceptor ?0.1.1?\fR +.sp +\fB::grammar::fa::dacceptor\fR \fIdaName\fR \fIfa\fR ?\fB-any\fR \fIany\fR? +.sp +\fBdaName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIdaName\fR \fBdestroy\fR +.sp +\fIdaName\fR \fBaccept?\fR \fIsymbols\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a class for acceptors constructed from +deterministic \fIfinite automatons\fR (DFA). Acceptors are objects +which can be given a string of symbols and tell if the DFA they are +constructed from would \fIaccept\fR that string. +For the actual creation of the DFAs the acceptors are based on we have +the packages \fBgrammar::fa\fR and \fBgrammar::fa::op\fR. +.PP +.SH API +The package exports the API described here. +.TP +\fB::grammar::fa::dacceptor\fR \fIdaName\fR \fIfa\fR ?\fB-any\fR \fIany\fR? +Creates a new deterministic acceptor with an associated global Tcl command +whose name is \fIdaName\fR. This command may be used to invoke various +operations on the acceptor. It has the following general form: +.RS +.TP +\fBdaName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. See section \fBACCEPTOR METHODS\fR for more explanations. +.sp +The acceptor will be based on the deterministic finite automaton +stored in the object \fIfa\fR. 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 \fIfa\fR after the +construction of the acceptor \fIwill not\fR influence the acceptor. +.sp +If \fIany\fR 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. +.RE +.PP +.SH "ACCEPTOR METHODS" +.PP +All acceptors provide the following methods for their manipulation: +.TP +\fIdaName\fR \fBdestroy\fR +Destroys the automaton, including its storage space and associated +command. +.TP +\fIdaName\fR \fBaccept?\fR \fIsymbols\fR +Takes the list of \fIsymbols\fR and checks if the FA the acceptor is +based on would accept it. The result is a boolean value. \fBTrue\fR +is returned if the symbols are accepted, and \fBFalse\fR +otherwise. Note that bogus symbols in the input are either translated +to the \fIany\fR 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. +.PP +.PP +.SH EXAMPLES +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_fa\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +acceptance, acceptor, automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_fa/dexec.n Index: embedded/man/files/modules/grammar_fa/dexec.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_fa/dexec.n @@ -0,0 +1,403 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_fa/dexec.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2007 Bogdan <rftghost@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::fa::dexec" n 0.2 tcllib "Finite automaton operations and usage" +.BS +.SH NAME +grammar::fa::dexec \- Execute deterministic finite automatons +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit \fR +.sp +package require \fBgrammar::fa::dexec ?0.2?\fR +.sp +\fB::grammar::fa::dexec\fR \fIdaName\fR \fIfa\fR ?\fB-any\fR \fIany\fR? ?\fB-command\fR \fIcmdprefix\fR? +.sp +\fBdaName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIdaName\fR \fBdestroy\fR +.sp +\fIdaName\fR \fBput\fR \fIsymbol\fR +.sp +\fIdaName\fR \fBreset\fR +.sp +\fIdaName\fR \fBstate\fR +.sp +\fIcmdprefix\fR \fBerror\fR \fIcode\fR \fImessage\fR +.sp +\fIcmdprefix\fR \fBfinal\fR \fIstateid\fR +.sp +\fIcmdprefix\fR \fBreset\fR +.sp +\fIcmdprefix\fR \fBstate\fR \fIstateid\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a class for executors constructed from +deterministic \fIfinite automatons\fR (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 \fBgrammar::fa\fR and \fBgrammar::fa::op\fR. +.PP +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 \fB-command\fR. 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. +.PP +\fISide note\fR: +The acceptor objects provided by \fBgrammar::fa::dacceptor\fR +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). +.PP +.SH API +The package exports the API described here. +.TP +\fB::grammar::fa::dexec\fR \fIdaName\fR \fIfa\fR ?\fB-any\fR \fIany\fR? ?\fB-command\fR \fIcmdprefix\fR? +Creates a new deterministic executor with an associated global Tcl +command whose name is \fIdaName\fR. This command may be used to invoke +various operations on the executor. It has the following general form: +.RS +.TP +\fBdaName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. See section \fBEXECUTOR METHODS\fR for more +explanations. +.sp +The executor will be based on the deterministic finite automaton +stored in the object \fIfa\fR. 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 \fIfa\fR after the +construction of the executor \fIwill not\fR influence the executor. +.sp +If \fIany\fR 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. +.RE +.PP +.SH "EXECUTOR METHODS" +.PP +All executors provide the following methods for their manipulation: +.TP +\fIdaName\fR \fBdestroy\fR +Destroys the automaton, including its storage space and associated +command. +.TP +\fIdaName\fR \fBput\fR \fIsymbol\fR +Takes the current state of the executor and the \fIsymbol\fR 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. +.sp +When an error is reported all further invokations of \fBput\fR will +do nothing, until the error condition has been cleared via an +invokation of method \fBreset\fR. +.TP +\fIdaName\fR \fBreset\fR +Unconditionally sets the executor into the start state of the +underlying FA. This also clears any error condition \fBput\fR may +have encountered. +.TP +\fIdaName\fR \fBstate\fR +Returns the current state of the underlying FA. This allow for +introspection without the need to pass data from the callback command. +.PP +.SH "EXECUTOR CALLBACK" +The callback command \fIcmdprefix\fR given to an executor via the +option \fB-command\fR will be executed by the object at the global +level, using the syntax described below. Note that \fIcmdprefix\fR 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. +.TP +\fIcmdprefix\fR \fBerror\fR \fIcode\fR \fImessage\fR +The executor has encountered an error, and \fImessage\fR contains a +human-readable text explaining the nature of the problem. +The \fIcode\fR on the other hand is a fixed machine-readable text. +The following error codes can be generated by executor objects. +.RS +.TP +\fBBADSYM\fR +An unknown symbol was found in the input. This can happen if and only +if no \fB-any\fR symbol was specified. +.TP +\fBBADTRANS\fR +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. +.RE +.TP +\fIcmdprefix\fR \fBfinal\fR \fIstateid\fR +The executor has entered the final state \fIstateid\fR. +.TP +\fIcmdprefix\fR \fBreset\fR +The executor was reset. +.TP +\fIcmdprefix\fR \fBstate\fR \fIstateid\fR +The FA changed state due to a transition. \fIstateid\fR is the new state. +.PP +.PP +.SH EXAMPLES +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_fa\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +automaton, execution, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, running, state, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2007 Bogdan <rftghost@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_fa/fa.n Index: embedded/man/files/modules/grammar_fa/fa.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_fa/fa.n @@ -0,0 +1,897 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_fa/fa.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::fa" n 0.4 tcllib "Finite automaton operations and usage" +.BS +.SH NAME +grammar::fa \- Create and manipulate finite automatons +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit 1.3\fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBgrammar::fa::op ?0.2?\fR +.sp +package require \fBgrammar::fa ?0.4?\fR +.sp +\fB::grammar::fa\fR \fIfaName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR|\fBfromRegex\fR \fIre\fR ?\fIover\fR?? +.sp +\fBfaName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIfaName\fR \fBdestroy\fR +.sp +\fIfaName\fR \fBclear\fR +.sp +\fIfaName\fR \fB=\fR \fIsrcFA\fR +.sp +\fIfaName\fR \fB-->\fR \fIdstFA\fR +.sp +\fIfaName\fR \fBserialize\fR +.sp +\fIfaName\fR \fBdeserialize\fR \fIserialization\fR +.sp +\fIfaName\fR \fBstates\fR +.sp +\fIfaName\fR \fBstate\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBstate\fR \fBdelete\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBstate\fR \fBexists\fR \fIs\fR +.sp +\fIfaName\fR \fBstate\fR \fBrename\fR \fIs\fR \fIsnew\fR +.sp +\fIfaName\fR \fBstartstates\fR +.sp +\fIfaName\fR \fBstart\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBstart\fR \fBremove\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBstart?\fR \fIs\fR +.sp +\fIfaName\fR \fBstart?set\fR \fIstateset\fR +.sp +\fIfaName\fR \fBfinalstates\fR +.sp +\fIfaName\fR \fBfinal\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBfinal\fR \fBremove\fR \fIs1\fR ?\fIs2\fR ...? +.sp +\fIfaName\fR \fBfinal?\fR \fIs\fR +.sp +\fIfaName\fR \fBfinal?set\fR \fIstateset\fR +.sp +\fIfaName\fR \fBsymbols\fR +.sp +\fIfaName\fR \fBsymbols@\fR \fIs\fR ?\fId\fR? +.sp +\fIfaName\fR \fBsymbols@set\fR \fIstateset\fR +.sp +\fIfaName\fR \fBsymbol\fR \fBadd\fR \fIsym1\fR ?\fIsym2\fR ...? +.sp +\fIfaName\fR \fBsymbol\fR \fBdelete\fR \fIsym1\fR ?\fIsym2\fR ...? +.sp +\fIfaName\fR \fBsymbol\fR \fBrename\fR \fIsym\fR \fInewsym\fR +.sp +\fIfaName\fR \fBsymbol\fR \fBexists\fR \fIsym\fR +.sp +\fIfaName\fR \fBnext\fR \fIs\fR \fIsym\fR ?\fB-->\fR \fInext\fR? +.sp +\fIfaName\fR \fB!next\fR \fIs\fR \fIsym\fR ?\fB-->\fR \fInext\fR? +.sp +\fIfaName\fR \fBnextset\fR \fIstateset\fR \fIsym\fR +.sp +\fIfaName\fR \fBis\fR \fBdeterministic\fR +.sp +\fIfaName\fR \fBis\fR \fBcomplete\fR +.sp +\fIfaName\fR \fBis\fR \fBuseful\fR +.sp +\fIfaName\fR \fBis\fR \fBepsilon-free\fR +.sp +\fIfaName\fR \fBreachable_states\fR +.sp +\fIfaName\fR \fBunreachable_states\fR +.sp +\fIfaName\fR \fBreachable\fR \fIs\fR +.sp +\fIfaName\fR \fBuseful_states\fR +.sp +\fIfaName\fR \fBunuseful_states\fR +.sp +\fIfaName\fR \fBuseful\fR \fIs\fR +.sp +\fIfaName\fR \fBepsilon_closure\fR \fIs\fR +.sp +\fIfaName\fR \fBreverse\fR +.sp +\fIfaName\fR \fBcomplete\fR +.sp +\fIfaName\fR \fBremove_eps\fR +.sp +\fIfaName\fR \fBtrim\fR ?\fIwhat\fR? +.sp +\fIfaName\fR \fBdeterminize\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBminimize\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBcomplement\fR +.sp +\fIfaName\fR \fBkleene\fR +.sp +\fIfaName\fR \fBoptional\fR +.sp +\fIfaName\fR \fBunion\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBintersect\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBdifference\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBconcatenate\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fIfaName\fR \fBfromRegex\fR \fIregex\fR ?\fIover\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a container class for +\fIfinite automatons\fR (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 \fBgrammar::fa::op\fR), it does not have the +ability to execute a definition for a stream of symbols. +Use the packages +\fBgrammar::fa::dacceptor\fR and +\fBgrammar::fa::dexec\fR for that. +Another package related to this is \fBgrammar::fa::compiler\fR. 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. +.PP +For more information about what a finite automaton is see section +\fBFINITE AUTOMATONS\fR. +.SH API +The package exports the API described here. +.TP +\fB::grammar::fa\fR \fIfaName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR|\fBfromRegex\fR \fIre\fR ?\fIover\fR?? +Creates a new finite automaton with an associated global Tcl command +whose name is \fIfaName\fR. This command may be used to invoke various +operations on the automaton. It has the following general form: +.RS +.TP +\fBfaName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. See section \fBFA METHODS\fR for more explanations. The +new automaton will be empty if no \fIsrc\fR is specified. Otherwise +it will contain a copy of the definition contained in the \fIsrc\fR. +The \fIsrc\fR has to be a FA object reference for all operators except +\fBdeserialize\fR and \fBfromRegex\fR. The \fBdeserialize\fR +operator requires \fIsrc\fR to be the serialization of a FA instead, +and \fBfromRegex\fR takes a regular expression in the form a of a +syntax tree. See \fB::grammar::fa::op::fromRegex\fR for more detail on +that. +.RE +.PP +.SH "FA METHODS" +.PP +All automatons provide the following methods for their manipulation: +.TP +\fIfaName\fR \fBdestroy\fR +Destroys the automaton, including its storage space and associated +command. +.TP +\fIfaName\fR \fBclear\fR +Clears out the definition of the automaton contained in \fIfaName\fR, +but does \fInot\fR destroy the object. +.TP +\fIfaName\fR \fB=\fR \fIsrcFA\fR +Assigns the contents of the automaton contained +in \fIsrcFA\fR to \fIfaName\fR, overwriting any +existing definition. +This is the assignment operator for automatons. It copies the +automaton contained in the FA object \fIsrcFA\fR over the automaton +definition in \fIfaName\fR. The old contents of \fIfaName\fR are +deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIfaName\fR \fBdeserialize\fR [\fIsrcFA\fR \fBserialize\fR] + +.CE +.TP +\fIfaName\fR \fB-->\fR \fIdstFA\fR +This is the reverse assignment operator for automatons. It copies the +automation contained in the object \fIfaName\fR over the automaton +definition in the object \fIdstFA\fR. +The old contents of \fIdstFA\fR are deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdstFA\fR \fBdeserialize\fR [\fIfaName\fR \fBserialize\fR] + +.CE +.TP +\fIfaName\fR \fBserialize\fR +This method serializes the automaton stored in \fIfaName\fR. In other +words it returns a tcl \fIvalue\fR 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. +.sp +The result of this method has to be semantically identical over all +implementations of the \fBgrammar::fa\fR interface. This is what +will enable us to copy automatons between different implementations of +the same interface. +.sp +The result is a list of three elements with the following structure: +.RS +.IP [1] +The constant string \fBgrammar::fa\fR. +.IP [2] +A list containing the names of all known input symbols. The order of +elements in this list is not relevant. +.IP [3] +The last item in the list is a dictionary, however the order of the +keys is important as well. The keys are the states of the serialized +FA, and their order is the order in which to create the states when +deserializing. This is relevant to preserve the order relationship +between states. +.sp +The value of each dictionary entry is a list of three elements +describing the state in more detail. +.RS +.IP [1] +A boolean flag. If its value is \fBtrue\fR then the state is a +start state, otherwise it is not. +.IP [2] +A boolean flag. If its value is \fBtrue\fR then the state is a +final state, otherwise it is not. +.IP [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. +.RE +.RE +.sp +Assuming the following FA (which describes the life of a truck driver +in a very simple way :) +.sp +.CS + + + Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive + (...) is the start state. + +.CE +.sp +a possible serialization is +.sp +.CS + + + grammar::fa \\\\ + {yellow red green red/yellow} \\\\ + {Drive {0 0 {yellow Brake}} \\\\ + Brake {0 0 {red Stop}} \\\\ + Stop {1 0 {red/yellow Attention}} \\\\ + Attention {0 0 {green Drive}}} + +.CE +.sp +A possible one, because I did not care about creation order here +.TP +\fIfaName\fR \fBdeserialize\fR \fIserialization\fR +This is the complement to \fBserialize\fR. It replaces the +automaton definition in \fIfaName\fR with the automaton described by +the \fIserialization\fR value. The old contents of \fIfaName\fR are +deleted by this operation. +.TP +\fIfaName\fR \fBstates\fR +Returns the set of all states known to \fIfaName\fR. +.TP +\fIfaName\fR \fBstate\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +Adds the states \fIs1\fR, \fIs2\fR, et cetera to the FA definition in +\fIfaName\fR. The operation will fail any of the new states is already +declared. +.TP +\fIfaName\fR \fBstate\fR \fBdelete\fR \fIs1\fR ?\fIs2\fR ...? +Deletes the state \fIs1\fR, \fIs2\fR, et cetera, and all associated +information from the FA definition in \fIfaName\fR. 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 \fIs\fR is not known to the FA. +.TP +\fIfaName\fR \fBstate\fR \fBexists\fR \fIs\fR +A predicate. It tests whether the state \fIs\fR is known to the FA in +\fIfaName\fR. +The result is a boolean value. It will be set to \fBtrue\fR if the +state \fIs\fR is known, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBstate\fR \fBrename\fR \fIs\fR \fIsnew\fR +Renames the state \fIs\fR to \fIsnew\fR. Fails if \fIs\fR is not a +known state. Also fails if \fIsnew\fR is already known as a state. +.TP +\fIfaName\fR \fBstartstates\fR +Returns the set of states which are marked as \fIstart\fR states, +also known as \fIinitial\fR states. +See \fBFINITE AUTOMATONS\fR for explanations what this means. +.TP +\fIfaName\fR \fBstart\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +Mark the states \fIs1\fR, \fIs2\fR, et cetera in the FA \fIfaName\fR +as \fIstart\fR (aka \fIinitial\fR). +.TP +\fIfaName\fR \fBstart\fR \fBremove\fR \fIs1\fR ?\fIs2\fR ...? +Mark the states \fIs1\fR, \fIs2\fR, et cetera in the FA \fIfaName\fR +as \fInot start\fR (aka \fInot accepting\fR). +.TP +\fIfaName\fR \fBstart?\fR \fIs\fR +A predicate. It tests if the state \fIs\fR in the FA \fIfaName\fR is +\fIstart\fR or not. +The result is a boolean value. It will be set to \fBtrue\fR if the +state \fIs\fR is \fIstart\fR, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBstart?set\fR \fIstateset\fR +A predicate. It tests if the set of states \fIstateset\fR 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 \fBtrue\fR if a +start state is present in \fIstateset\fR, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBfinalstates\fR +Returns the set of states which are marked as \fIfinal\fR states, +also known as \fIaccepting\fR states. +See \fBFINITE AUTOMATONS\fR for explanations what this means. +.TP +\fIfaName\fR \fBfinal\fR \fBadd\fR \fIs1\fR ?\fIs2\fR ...? +Mark the states \fIs1\fR, \fIs2\fR, et cetera in the FA \fIfaName\fR +as \fIfinal\fR (aka \fIaccepting\fR). +.TP +\fIfaName\fR \fBfinal\fR \fBremove\fR \fIs1\fR ?\fIs2\fR ...? +Mark the states \fIs1\fR, \fIs2\fR, et cetera in the FA \fIfaName\fR +as \fInot final\fR (aka \fInot accepting\fR). +.TP +\fIfaName\fR \fBfinal?\fR \fIs\fR +A predicate. It tests if the state \fIs\fR in the FA \fIfaName\fR is +\fIfinal\fR or not. +The result is a boolean value. It will be set to \fBtrue\fR if the +state \fIs\fR is \fIfinal\fR, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBfinal?set\fR \fIstateset\fR +A predicate. It tests if the set of states \fIstateset\fR 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 \fBtrue\fR if a +final state is present in \fIstateset\fR, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBsymbols\fR +Returns the set of all symbols known to the FA \fIfaName\fR. +.TP +\fIfaName\fR \fBsymbols@\fR \fIs\fR ?\fId\fR? +Returns the set of all symbols for which the state \fIs\fR has transitions. +If the empty symbol is present then \fIs\fR has epsilon transitions. If two +states are specified the result is the set of symbols which have transitions +from \fIs\fR to \fIt\fR. This set may be empty if there are no transitions +between the two specified states. +.TP +\fIfaName\fR \fBsymbols@set\fR \fIstateset\fR +Returns the set of all symbols for which at least one state in the set +of states \fIstateset\fR has transitions. +In other words, the union of [\fIfaName\fR \fBsymbols@\fR \fBs\fR] +for all states \fBs\fR in \fIstateset\fR. +If the empty symbol is present then at least one state contained in +\fIstateset\fR has epsilon transitions. +.TP +\fIfaName\fR \fBsymbol\fR \fBadd\fR \fIsym1\fR ?\fIsym2\fR ...? +Adds the symbols \fIsym1\fR, \fIsym2\fR, et cetera to the FA +definition in \fIfaName\fR. The operation will fail any of the symbols +is already declared. The empty string is not allowed as a value for the symbols. +.TP +\fIfaName\fR \fBsymbol\fR \fBdelete\fR \fIsym1\fR ?\fIsym2\fR ...? +Deletes the symbols \fIsym1\fR, \fIsym2\fR et cetera, and all +associated information from the FA definition in \fIfaName\fR. 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. +.TP +\fIfaName\fR \fBsymbol\fR \fBrename\fR \fIsym\fR \fInewsym\fR +Renames the symbol \fIsym\fR to \fInewsym\fR. Fails if \fIsym\fR is +not a known symbol. Also fails if \fInewsym\fR is already known as a +symbol. +.TP +\fIfaName\fR \fBsymbol\fR \fBexists\fR \fIsym\fR +A predicate. It tests whether the symbol \fIsym\fR is known to the FA +in \fIfaName\fR. +The result is a boolean value. It will be set to \fBtrue\fR if the +symbol \fIsym\fR is known, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBnext\fR \fIs\fR \fIsym\fR ?\fB-->\fR \fInext\fR? +Define or query transition information. +.sp +If \fInext\fR is specified, then the method will add a transition from +the state \fIs\fR to the \fIsuccessor\fR state \fInext\fR labeled with +the symbol \fIsym\fR to the FA contained in \fIfaName\fR. The +operation will fail if \fIs\fR, or \fInext\fR are not known states, or +if \fIsym\fR is not a known symbol. An exception to the latter is that +\fIsym\fR is allowed to be the empty string. In that case the new +transition is an \fIepsilon transition\fR which will not consume +input when traversed. The operation will also fail if the combination +of (\fIs\fR, \fIsym\fR, and \fInext\fR) is already present in the FA. +.sp +If \fInext\fR was not specified, then the method will return +the set of states which can be reached from \fIs\fR through +a single transition labeled with symbol \fIsym\fR. +.TP +\fIfaName\fR \fB!next\fR \fIs\fR \fIsym\fR ?\fB-->\fR \fInext\fR? +Remove one or more transitions from the Fa in \fIfaName\fR. +.sp +If \fInext\fR was specified then the single transition from the state +\fIs\fR to the state \fInext\fR labeled with the symbol \fIsym\fR is +removed from the FA. Otherwise \fIall\fR transitions originating in +state \fIs\fR and labeled with the symbol \fIsym\fR will be removed. +.sp +The operation will fail if \fIs\fR and/or \fInext\fR are not known as +states. It will also fail if a non-empty \fIsym\fR is not known as +symbol. The empty string is acceptable, and allows the removal of +epsilon transitions. +.TP +\fIfaName\fR \fBnextset\fR \fIstateset\fR \fIsym\fR +Returns the set of states which can be reached by a single transition +originating in a state in the set \fIstateset\fR and labeled with the +symbol \fIsym\fR. +.sp +In other words, this is the union of +[\fIfaName\fR next \fBs\fR \fIsymbol\fR] +for all states \fBs\fR in \fIstateset\fR. +.TP +\fIfaName\fR \fBis\fR \fBdeterministic\fR +A predicate. It tests whether the FA in \fIfaName\fR is a +deterministic FA or not. +The result is a boolean value. It will be set to \fBtrue\fR if the +FA is deterministic, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBis\fR \fBcomplete\fR +A predicate. It tests whether the FA in \fIfaName\fR 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 \fBtrue\fR if the +FA is deterministic, and \fBfalse\fR otherwise. +.sp +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. +.TP +\fIfaName\fR \fBis\fR \fBuseful\fR +A predicate. It tests whether the FA in \fIfaName\fR is an useful FA +or not. A FA is useful if all states are \fIreachable\fR +and \fIuseful\fR. +The result is a boolean value. It will be set to \fBtrue\fR if the +FA is deterministic, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBis\fR \fBepsilon-free\fR +A predicate. It tests whether the FA in \fIfaName\fR 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 \fBtrue\fR if the +FA is deterministic, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBreachable_states\fR +Returns the set of states which are reachable from a start state by +one or more transitions. +.TP +\fIfaName\fR \fBunreachable_states\fR +Returns the set of states which are not reachable from any start state +by any number of transitions. This is +.sp +.CS + + + [faName states] - [faName reachable_states] + +.CE +.TP +\fIfaName\fR \fBreachable\fR \fIs\fR +A predicate. It tests whether the state \fIs\fR in the FA \fIfaName\fR +can be reached from a start state by one or more transitions. +The result is a boolean value. It will be set to \fBtrue\fR if the +state can be reached, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBuseful_states\fR +Returns the set of states which are able to reach a final state by +one or more transitions. +.TP +\fIfaName\fR \fBunuseful_states\fR +Returns the set of states which are not able to reach a final state by +any number of transitions. This is +.sp +.CS + + + [faName states] - [faName useful_states] + +.CE +.TP +\fIfaName\fR \fBuseful\fR \fIs\fR +A predicate. It tests whether the state \fIs\fR in the FA \fIfaName\fR +is able to reach a final state by one or more transitions. +The result is a boolean value. It will be set to \fBtrue\fR if the +state is useful, and \fBfalse\fR otherwise. +.TP +\fIfaName\fR \fBepsilon_closure\fR \fIs\fR +Returns the set of states which are reachable from the state \fIs\fR +in the FA \fIfaName\fR by one or more epsilon transitions, i.e +transitions over the empty symbol, transitions which do not consume +input. This is called the \fIepsilon closure\fR of \fIs\fR. +.TP +\fIfaName\fR \fBreverse\fR +.TP +\fIfaName\fR \fBcomplete\fR +.TP +\fIfaName\fR \fBremove_eps\fR +.TP +\fIfaName\fR \fBtrim\fR ?\fIwhat\fR? +.TP +\fIfaName\fR \fBdeterminize\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBminimize\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBcomplement\fR +.TP +\fIfaName\fR \fBkleene\fR +.TP +\fIfaName\fR \fBoptional\fR +.TP +\fIfaName\fR \fBunion\fR \fIfa\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBintersect\fR \fIfa\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBdifference\fR \fIfa\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBconcatenate\fR \fIfa\fR ?\fImapvar\fR? +.TP +\fIfaName\fR \fBfromRegex\fR \fIregex\fR ?\fIover\fR? +These methods provide more complex operations on the FA. Please see +the same-named commands in the package \fBgrammar::fa::op\fR for +descriptions of what they do. +.PP +.PP +.SH EXAMPLES +.PP +.SH "FINITE AUTOMATONS" +.PP +For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where +.IP \(bu +S is a set of \fIstates\fR, +.IP \(bu +Sy a set of \fIinput symbols\fR, +.IP \(bu +St is a subset of S, the set of \fIstart\fR states, also known as +\fIinitial\fR states. +.IP \(bu +Fi is a subset of S, the set of \fIfinal\fR states, also known as +\fIaccepting\fR. +.IP \(bu +T is a function from S x (Sy + epsilon) to {S}, the \fItransition function\fR. +Here \fBepsilon\fR 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 \fIsuccessor states\fR. +.PP +.PP +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. +.PP +FA's are used to process streams of symbols over Sy. +.PP +A specific FA is said to \fIaccept\fR 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 \fIlanguage\fR of +the FA. One important equivalence is that the set of languages which +can be accepted by an FA is the set of \fIregular languages\fR. +.PP +Another important concept is that of deterministic FAs. A FA is said +to be \fIdeterministic\fR 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). +.PP +While one of the premier applications of FAs is in \fIparsing\fR, +especially in the \fIlexer\fR stage (where symbols == characters), +this is not the only possibility by far. +.PP +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 \fIfinite transducer\fR, which has an +additional set OSy of \fIoutput symbols\fR and also an additional +\fIoutput function\fR 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. +.PP +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". +.PP +Transducers are not handled by this package. They will get their own +package in the future. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_fa\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2004-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_fa/faop.n Index: embedded/man/files/modules/grammar_fa/faop.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_fa/faop.n @@ -0,0 +1,661 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_fa/faop.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::fa::op" n 0.4 tcllib "Finite automaton operations and usage" +.BS +.SH NAME +grammar::fa::op \- Operations on finite automatons +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBgrammar::fa::op ?0.4.1?\fR +.sp +\fB::grammar::fa::op::constructor\fR \fIcmd\fR +.sp +\fB::grammar::fa::op::reverse\fR \fIfa\fR +.sp +\fB::grammar::fa::op::complete\fR \fIfa\fR ?\fIsink\fR? +.sp +\fB::grammar::fa::op::remove_eps\fR \fIfa\fR +.sp +\fB::grammar::fa::op::trim\fR \fIfa\fR ?\fIwhat\fR? +.sp +\fB::grammar::fa::op::determinize\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::minimize\fR \fIfa\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::complement\fR \fIfa\fR +.sp +\fB::grammar::fa::op::kleene\fR \fIfa\fR +.sp +\fB::grammar::fa::op::optional\fR \fIfa\fR +.sp +\fB::grammar::fa::op::union\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::intersect\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::difference\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::concatenate\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +.sp +\fB::grammar::fa::op::fromRegex\fR \fIfa\fR \fIregex\fR ?\fIover\fR? +.sp +\fB::grammar::fa::op::toRegexp\fR \fIfa\fR +.sp +\fB::grammar::fa::op::toRegexp2\fR \fIfa\fR +.sp +\fB::grammar::fa::op::toTclRegexp\fR \fIregexp\fR \fIsymdict\fR +.sp +\fB::grammar::fa::op::simplifyRegexp\fR \fIregexp\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a number of complex operations on finite +automatons (Short: FA), +as provided by the package \fBgrammar::fa\fR. +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 \fBgrammar::fa\fR +and \fBgrammar::fa::interpreter\fR for that. +Another package related to this is \fBgrammar::fa::compiler\fR +which turns a FA into an executor class which has the definition of +the FA hardwired into it. +.PP +For more information about what a finite automaton is see section +\fIFINITE AUTOMATONS\fR in package \fBgrammar::fa\fR. +.SH 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. +\fIStructure operations\fR +.TP +\fB::grammar::fa::op::constructor\fR \fIcmd\fR +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. +.sp +Any container class using this package for complex operations should set +its own class command as the constructor. See package \fBgrammar::fa\fR +for an example. +.TP +\fB::grammar::fa::op::reverse\fR \fIfa\fR +Reverses the \fIfa\fR. This is done by reversing the direction of all +transitions and swapping the sets of \fIstart\fR and \fIfinal\fR +states. The language of \fIfa\fR changes unpredictably. +.TP +\fB::grammar::fa::op::complete\fR \fIfa\fR ?\fIsink\fR? +Completes the \fIfa\fR \fIcomplete\fR, but nothing is done if the +\fIfa\fR is already \fIcomplete\fR. This implies that only the first +in a series of multiple consecutive complete operations on \fIfa\fR +will perform anything. The remainder will be null operations. +.sp +The language of \fIfa\fR is unchanged by this operation. +.sp +This is done by adding a single new state, the \fIsink\fR, 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. +.sp +Note: When a FA has epsilon-transitions transitions over a symbol for +a state S can be indirect, i.e. not attached directly to S, but to a +state in the epsilon-closure of S. The symbols for such indirect +transitions count when computing completeness of a state. In other +words, these indirectly reached symbols are \fInot\fR missing. +.sp +The argument \fIsink\fR provides the name for the new state and most +not be present in the \fIfa\fR if specified. If the name is not +specified the command will name the state "sink\fBn\fR", where \fBn\fR +is set so that there are no collisions with existing states. +.sp +Note that the sink state is \fInot useful\fR by definition. In +other words, while the FA becomes complete, it is also +\fInot useful\fR in the strict sense as it has a state from which +no final state can be reached. +.TP +\fB::grammar::fa::op::remove_eps\fR \fIfa\fR +Removes all epsilon-transitions from the \fIfa\fR in such a manner the +the language of \fIfa\fR is unchanged. However nothing is done if the +\fIfa\fR is already \fIepsilon-free\fR. +This implies that only the first in a series of multiple consecutive +complete operations on \fIfa\fR will perform anything. The remainder +will be null operations. +.sp +\fINote:\fR This operation may cause states to become unreachable or +not useful. These states are not removed by this operation. +Use \fB::grammar::fa::op::trim\fR for that instead. +.TP +\fB::grammar::fa::op::trim\fR \fIfa\fR ?\fIwhat\fR? +Removes unwanted baggage from \fIfa\fR. +The legal values for \fIwhat\fR are listed below. The command defaults +to \fB!reachable|!useful\fR if no specific argument was given. +.RS +.TP +\fB!reachable\fR +Removes all states which are not reachable from a start state. +.TP +\fB!useful\fR +Removes all states which are unable to reach a final state. +.TP +\fB!reachable&!useful\fR +.TP +\fB!(reachable|useful)\fR +Removes all states which are not reachable from a start state and are +unable to reach a final state. +.TP +\fB!reachable|!useful\fR +.TP +\fB!(reachable&useful)\fR +Removes all states which are not reachable from a start state or are +unable to reach a final state. +.RE +.sp +.TP +\fB::grammar::fa::op::determinize\fR \fIfa\fR ?\fImapvar\fR? +Makes the \fIfa\fR deterministic without changing the language +accepted by the \fIfa\fR. However nothing is done if the \fIfa\fR is +already \fIdeterministic\fR. This implies that only the first in a +series of multiple consecutive complete operations on \fIfa\fR will +perform anything. The remainder will be null operations. +.sp +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 \fImapvar\fR, 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. +.sp +\fINote\fR: An empty dictionary signals that the command was able to +make the \fIfa\fR deterministic without performing a full subset +construction, just by removing states and shuffling transitions around +(As part of making the FA epsilon-free). +.sp +\fINote\fR: 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 +\fIdeterministic\fR. +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. +.TP +\fB::grammar::fa::op::minimize\fR \fIfa\fR ?\fImapvar\fR? +Creates a FA which accepts the same language as \fIfa\fR, but has a +minimal number of states. Uses Brzozowski's method to accomplish this. +.sp +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 \fImapvar\fR, 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. +.sp +\fINote\fR: An empty dictionary signals that the command was able to +minimize the \fIfa\fR without having to compute new states. This +should happen if and only if the input FA was already minimal. +.sp +\fINote\fR: 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. +.PP +\fILanguage operations\fR +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). +.TP +\fB::grammar::fa::op::complement\fR \fIfa\fR +Complements \fIfa\fR. This is possible if and only if \fIfa\fR is +\fIcomplete\fR and \fIdeterministic\fR. The resulting FA accepts the +complementary language of \fIfa\fR. In other words, all inputs not +accepted by the input are accepted by the result, and vice versa. +.sp +The result will have all states and transitions of the input, and +different final states. +.TP +\fB::grammar::fa::op::kleene\fR \fIfa\fR +Applies Kleene's closure to \fIfa\fR. +The resulting FA accepts all strings \fBS\fR for which we can find a +natural number \fBn\fR (0 inclusive) and strings \fBA1\fR ... \fBAn\fR +in the language of \fIfa\fR such that \fBS\fR is the concatenation of +\fBA1\fR ... \fBAn\fR. +In other words, the language of the result is the infinite union over +finite length concatenations over the language of \fIfa\fR. +.sp +The result will have all states and transitions of the input, and new +start and final states. +.TP +\fB::grammar::fa::op::optional\fR \fIfa\fR +Makes the \fIfa\fR optional. In other words it computes the FA which +accepts the language of \fIfa\fR and the empty the word (epsilon) as +well. +.sp +The result will have all states and transitions of the input, and new +start and final states. +.TP +\fB::grammar::fa::op::union\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +Combines the FAs \fIfa\fR and \fIfb\fR such that the resulting FA +accepts the union of the languages of the two FAs. +.sp +The result will have all states and transitions of the two input FAs, +and new start and final states. All states of \fIfb\fR which exist in +\fIfa\fR as well will be renamed, and the \fImapvar\fR will contain a +mapping from the old states of \fIfb\fR to the new ones, if present. +.sp +It should be noted that the result will be non-deterministic, even if +the inputs are deterministic. +.TP +\fB::grammar::fa::op::intersect\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +Combines the FAs \fIfa\fR and \fIfb\fR 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 \fIfa\fR and \fIfb\fR. The result will be useful, but +not necessarily deterministic or minimal. +.sp +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 \fImapvar\fR, 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 \fIfa\fR, the +second element will be drawn from \fIfb\fR. +.TP +\fB::grammar::fa::op::difference\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +Combines the FAs \fIfa\fR and \fIfb\fR 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 \fIfa\fR, but not by \fIfb\fR. This can also be expressed +as the intersection of \fIfa\fR with the complement of \fIfb\fR. The +result will be useful, but not necessarily deterministic or minimal. +.sp +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 \fImapvar\fR, 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 \fIfa\fR, the +second element will be drawn from \fIfb\fR. +.TP +\fB::grammar::fa::op::concatenate\fR \fIfa\fR \fIfb\fR ?\fImapvar\fR? +Combines the FAs \fIfa\fR and \fIfb\fR 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 \fIfa\fR, and \fIfb\fR resp. and W is the concatenation of +A and B. +.sp +The result FA will be non-deterministic. +.TP +\fB::grammar::fa::op::fromRegex\fR \fIfa\fR \fIregex\fR ?\fIover\fR? +Generates a non-deterministic FA which accepts the same language as +the regular expression \fIregex\fR. If the \fIover\fR 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 \fIregex\fR when \fIover\fR was not +specified. This set is important if and only if the complement +operator "!" is used in \fIregex\fR as the complementary language of +an FA is quite different for different sets of symbols. +.sp +The regular expression is represented by a nested list, which forms +a syntax tree. The following structures are legal: +.RS +.TP +{S x} +Atomic regular expression. Everything else is constructed from +these. Accepts the \fBS\fRymbol "x". +.TP +{. A1 A2 ...} +Concatenation operator. Accepts the concatenation of the regular +expressions \fBA1\fR, \fBA2\fR, etc. +.sp +\fINote\fR that this operator accepts zero or more arguments. With zero +arguments the represented language is \fIepsilon\fR, the empty word. +.TP +{| A1 A2 ...} +Choice operator, also called "Alternative". Accepts all input accepted +by at least one of the regular expressions \fBA1\fR, \fBA2\fR, etc. In +other words, the union of \fBA1\fR, \fBA2\fR. +.sp +\fINote\fR that this operator accepts zero or more arguments. With zero +arguments the represented language is the \fIempty\fR language, +the language without words. +.TP +{& A1 A2 ...} +Intersection operator, logical and. Accepts all input accepted which +is accepted by all of the regular expressions \fBA1\fR, \fBA2\fR, +etc. In other words, the intersection of \fBA1\fR, \fBA2\fR. +.TP +{? A} +Optionality operator. Accepts the empty word and anything from the +regular expression \fBA\fR. +.TP +{* A} +Kleene closure. Accepts the empty word and any finite concatenation of +words accepted by the regular expression \fBA\fR. +.TP +{+ A} +Positive Kleene closure. Accepts any finite concatenation of words +accepted by the regular expression \fBA\fR, but not the empty word. +.TP +{! A} +Complement operator. Accepts any word not accepted by the regular +expression \fBA\fR. Note that the complement depends on the set of +symbol the result should run over. See the discussion of the argument +\fIover\fR before. +.RE +.TP +\fB::grammar::fa::op::toRegexp\fR \fIfa\fR +This command generates and returns a regular expression which accepts +the same language as the finite automaton \fIfa\fR. The regular +expression is in the format as described above, for +\fB::grammar::fa::op::fromRegex\fR. +.TP +\fB::grammar::fa::op::toRegexp2\fR \fIfa\fR +This command has the same functionality as \fB::grammar::fa::op::toRegexp\fR, +but uses a different algorithm to simplify the generated regular expressions. +.TP +\fB::grammar::fa::op::toTclRegexp\fR \fIregexp\fR \fIsymdict\fR +This command generates and returns a regular expression in Tcl syntax for the +regular expression \fIregexp\fR, if that is possible. \fIregexp\fR is in the +same format as expected by \fB::grammar::fa::op::fromRegex\fR. +.sp +The command will fail and throw an error if \fIregexp\fR contains +complementation and intersection operations. +.sp +The argument \fIsymdict\fR is a dictionary mapping symbol names to +pairs of \fIsyntactic type\fR and Tcl-regexp. If a symbol +occurring in the \fIregexp\fR 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. +.TP +\fB::grammar::fa::op::simplifyRegexp\fR \fIregexp\fR +This command simplifies a regular expression by applying the following +algorithm first to the main expression and then recursively to all +sub-expressions: +.RS +.IP [1] +Convert the expression into a finite automaton. +.IP [2] +Minimize the automaton. +.IP [3] +Convert the automaton back to a regular expression. +.IP [4] +Choose the shorter of original expression and expression from +the previous step. +.RE +.PP +.PP +.SH EXAMPLES +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_fa\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/gasm.n Index: embedded/man/files/modules/grammar_me/gasm.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/gasm.n @@ -0,0 +1,644 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/gasm.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me::cpu::gasm" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me::cpu::gasm \- ME assembler +.SH SYNOPSIS +package require \fBgrammar::me::cpu::gasm ?0.1?\fR +.sp +\fB::grammar::me::cpu::gasm::begin\fR \fIg\fR \fIn\fR ?\fImode\fR? ?\fInote\fR? +.sp +\fB::grammar::me::cpu::gasm::done\fR \fB-->\fR \fIt\fR +.sp +\fB::grammar::me::cpu::gasm::state\fR +.sp +\fB::grammar::me::cpu::gasm::state!\fR \fIs\fR +.sp +\fB::grammar::me::cpu::gasm::lift\fR \fIt\fR \fIdst\fR \fB=\fR \fIsrc\fR +.sp +\fB::grammar::me::cpu::gasm::Inline\fR \fIt\fR \fInode\fR \fIlabel\fR +.sp +\fB::grammar::me::cpu::gasm::Cmd\fR \fIcmd\fR ?\fIarg\fR...? +.sp +\fB::grammar::me::cpu::gasm::Bra\fR +.sp +\fB::grammar::me::cpu::gasm::Nop\fR \fItext\fR +.sp +\fB::grammar::me::cpu::gasm::Note\fR \fItext\fR +.sp +\fB::grammar::me::cpu::gasm::Jmp\fR \fIlabel\fR +.sp +\fB::grammar::me::cpu::gasm::Exit\fR +.sp +\fB::grammar::me::cpu::gasm::Who\fR \fIlabel\fR +.sp +\fB::grammar::me::cpu::gasm::/Label\fR \fIname\fR +.sp +\fB::grammar::me::cpu::gasm::/Clear\fR +.sp +\fB::grammar::me::cpu::gasm::/Ok\fR +.sp +\fB::grammar::me::cpu::gasm::/Fail\fR +.sp +\fB::grammar::me::cpu::gasm::/At\fR \fIname\fR +.sp +\fB::grammar::me::cpu::gasm::/CloseLoop\fR +.sp +.BE +.SH 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 \fBpage::compiler::peg::mecpu\fR. Despite that it is actually +mostly agnostic regarding the instructions, users can choose any +instruction set they like. +.PP +The program under construction is held in a graph structure (See +package \fBstruct::graph\fR) during assembly and subsequent +manipulation, with instructions represented by nodes, and the flow of +execution between instructions explicitly encoded in the arcs between +them. +.PP +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. +.PP +While the graph the assembler operates on is supplied from the +outside, i.e. external, it does manage some internal state, namely: +.IP [1] +The handle of the graph node most assembler operations will +work on, the \fIanchor\fR. +.IP [2] +A mapping from arbitrary strings to instructions. I.e. it is +possible to \fIlabel\fR an instruction during assembly, and later +recall that instruction by its label. +.IP [3] +The condition code to use when creating arcs between +instructions, which is one of \fBalways\fR, \fBok\fR, and +\fBfail\fR. +.IP [4] +The current operation mode, one of \fBhalt\fR, +\fBokfail\fR, and \fB!okfail\fR. +.IP [5] +The name of a node in a tree. This, and the operation mode +above are the parts most heavily influenced by the needs of a grammar +compiler, as they assume some basic program structures (selected +through the operation mode), and intertwine the graph with a tree, +like the AST for the grammar to be compiled. +.PP +.SH 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. +.PP +.IP [1] +Any graph object command used by the assembler has to provide +the API as specified in the documentation for the package +\fBstruct::graph\fR. +.IP [2] +Any tree object command used by the assembler has to provide +the API as specified in the documentation for the package +\fBstruct::tree\fR. +.IP [3] +Any instruction (node) generated by the assembler in a graph +will have at least two, and at most three attributes: +.RS +.TP +\fBinstruction\fR +The value of this attribute is the name of +the instruction. The only names currently defined by the assembler are +the three pseudo-instructions +.RS +.TP +\fBNOP\fR +This instruction does nothing. Useful for fixed +framework nodes, unchanging jump destinations, and the like. No +arguments. +.TP +\fBC\fR +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. +.TP +\fBBRA\fR +A .NOP serving as explicitly coded conditional +branch. No arguments. +.RE +.IP +However we reserve the space of all instructions whose names begin +with a "." (dot) for future use by the assembler. +.TP +\fBarguments\fR +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. +.TP +\fBexpr\fR +This attribute is optional. When it is present its +value is the name of a node in the tree intertwined with the graph. +.RE +.IP [4] +Any arc between two instructions will have one attribute: +.RS +.TP +\fBcondition\fR +The value of this attribute determines under which +condition execution will take this arc. It is one of \fBalways\fR, +\fBok\fR, and \fBfail\fR. 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. +.RE +.IP [5] +A tree node given to the assembler for cross-referencing will +be written to and given the following attributes, some fixed, some +dependent on the operation mode. All values will be references to +nodes in the instruction graph. Some of the instruction will expect +some or specific sets of these attributes. +.RS +.TP +\fBgas::entry\fR +Always written. +.TP +\fBgas::exit\fR +Written for all modes but \fBokfail\fR. +.TP +\fBgas::exit::ok\fR +Written for mode \fBokfail\fR. +.TP +\fBgas::exit::fail\fR +Written for mode \fBokfail\fR. +.RE +.PP +.SH API +.TP +\fB::grammar::me::cpu::gasm::begin\fR \fIg\fR \fIn\fR ?\fImode\fR? ?\fInote\fR? +This command starts the assembly of an instruction sequence, and +(re)initializes the state of the assembler. After completion of the +instruction sequence use \fB::grammar::me::cpu::gasm::done\fR to +finalize the assembler. +.sp +It will operate on the graph \fIg\fR in the specified \fImode\fR +(Default is \fBokfail\fR). 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 +\fImode\fR-dependent: +.RS +.TP +\fBhalt\fR +An "icf_halt" instruction labeled "exit/return". +.TP +\fB!okfail\fR +An "icf_ntreturn" instruction labeled "exit/return". +.TP +\fBokfail\fR +Two .NOP instructions labeled "exit/ok" and +"exit/fail" respectively. +.RE +.IP +The \fInote\fR, if specified (default is not), is given to the "entry" .NOP instruction. +.sp +The node reference \fIn\fR is simply stored for use by +\fB::grammar::me::cpu::gasm::done\fR. It has to refer to a node in the +tree \fIt\fR argument of that command. +.sp +After the initialization is done the "entry" instruction will be the +\fIanchor\fR, and the condition code will be set to \fBalways\fR. +.sp +The command returns the empy string as its result. +.TP +\fB::grammar::me::cpu::gasm::done\fR \fB-->\fR \fIt\fR +This command finalizes the creation of an instruction sequence and +then clears the state of the assembler. +\fINOTE\fR that this \fIdoes not\fR 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 \fB::grammar::me::cpu::gasm::begin\fR. +.sp +Before the state is cleared selected references to selected +instructions will be written to attributes of the node \fIn\fR in the +tree \fIt\fR. +Which instructions are saved is \fImode\fR-dependent. Both \fImode\fR +and the destination node \fIn\fR were specified during invokation of +\fB::grammar::me::cpu::gasm::begin\fR. +.sp +Independent of the mode a reference to the instruction labeled "entry" +will be saved to the attribute \fBgas::entry\fR of \fIn\fR. The +reference to the node \fIn\fR will further be saved into the attribute +"expr" of the "entry" instruction. Beyond that +.RS +.TP +\fBhalt\fR +A reference to the instruction labeled +"exit/return" will be saved to the attribute \fBgas::exit\fR of +\fIn\fR. +.TP +\fBokfail\fR +See \fBhalt\fR. +.TP +\fB!okfail\fR +Reference to the two instructions labeled +"exit/ok" and "exit/fail" will be saved to the attributes +\fBgas::exit::ok\fR and \fBgas::exit::fail\fR of \fIn\fR +respectively. +.RE +.sp +The command returns the empy string as its result. +.TP +\fB::grammar::me::cpu::gasm::state\fR +This command returns the current state of the assembler. Its format is +not documented and considered to be internal to the package. +.TP +\fB::grammar::me::cpu::gasm::state!\fR \fIs\fR +This command takes a serialized assembler state \fIs\fR as returned by +\fB::grammar::me::cpu::gasm::state\fR and makes it the current state +of the assembler. +.sp +\fINote\fR that this may overwrite label definitions, however all +non-conflicting label definitions in the state before are not touched +and merged with \fIs\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::lift\fR \fIt\fR \fIdst\fR \fB=\fR \fIsrc\fR +This command operates on the tree \fIt\fR. It copies the contents of +the attributes \fBgas::entry\fR, \fBgas::exit::ok\fR and +\fBgas::exit::fail\fR from the node \fIsrc\fR to the node \fIdst\fR. +It returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::Inline\fR \fIt\fR \fInode\fR \fIlabel\fR +This command links an instruction sequence created by an earlier +begin/done pair into the current instruction sequence. +.sp +To this end it +.RS +.IP [1] +reads the instruction references from the attributes +\fBgas::entry\fR, \fBgas::exit::ok\fR, and \fBgas::exit::fail\fR +from the node \fIn\fR of the tree \fIt\fR and makes them available to +assembler und the labels \fIlabel\fR/entry, \fIlabel\fR/exit::ok, and +\fIlabel\fR/exit::fail respectively. +.IP [2] +Creates an arc from the \fIanchor\fR to the node labeled +\fIlabel\fR/entry, and tags it with the current condition code. +.IP [3] +Makes the node labeled \fIlabel\fR/exit/ok the new \fIanchor\fR. +.RE +.IP +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::Cmd\fR \fIcmd\fR ?\fIarg\fR...? +This is the basic command to add instructions to the graph. +It creates a new instruction of type \fIcmd\fR with the given +arguments \fIarg\fR... +If the \fIanchor\fR was defined it will also create an arc from the +\fIanchor\fR to the new instruction using the current condition code. +After the call the new instruction will be the \fIanchor\fR and the +current condition code will be set to \fBalways\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::Bra\fR +This is a convenience command to create a .BRA pseudo-instruction. It +uses \fB::grammar::me::cpu::gasm::Cmd\fR to actually create the +instruction and inherits its behaviour. +.TP +\fB::grammar::me::cpu::gasm::Nop\fR \fItext\fR +This is a convenience command to create a .NOP pseudo-instruction. It +uses \fB::grammar::me::cpu::gasm::Cmd\fR to actually create the +instruction and inherits its behaviour. +The \fItext\fR will be saved as the first and only argument of the new +instruction. +.TP +\fB::grammar::me::cpu::gasm::Note\fR \fItext\fR +This is a convenience command to create a .C pseudo-instruction, +i.e. a comment. It uses \fB::grammar::me::cpu::gasm::Cmd\fR to +actually create the instruction and inherits its behaviour. +The \fItext\fR will be saved as the first and only argument of the new +instruction. +.TP +\fB::grammar::me::cpu::gasm::Jmp\fR \fIlabel\fR +This command creates an arc from the \fIanchor\fR to the instruction +labeled with \fIlabel\fR, and tags with the the current condition +code. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::Exit\fR +This command creates an arc from the \fIanchor\fR to one of the exit +instructions, based on the operation mode (see +\fB::grammar::me::cpu::gasm::begin\fR), and tags it with current +condition code. +.sp +For mode \fBokfail\fR 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 \fBalways\fR, independent +the current condition code. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::Who\fR \fIlabel\fR +This command returns a reference to the instruction labeled with +\fIlabel\fR. +.TP +\fB::grammar::me::cpu::gasm::/Label\fR \fIname\fR +This command labels the \fIanchor\fR with \fIname\fR. +\fINote\fR that an instruction can have more than one label. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::/Clear\fR +This command clears the \fIanchor\fR, leaving it undefined, and +further resets the current condition code to \fBalways\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::/Ok\fR +This command sets the current condition code to \fBok\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::/Fail\fR +This command sets the current condition code to \fBfail\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::/At\fR \fIname\fR +This command sets the \fIanchor\fR to the instruction labeled with +\fIname\fR, and further resets the current condition code to +\fBalways\fR. +.sp +The command returns the empty string as its result. +.TP +\fB::grammar::me::cpu::gasm::/CloseLoop\fR +This command marks the \fIanchor\fR as the last instruction in a loop +body, by creating the attribute \fBLOOP\fR. +.sp +The command returns the empty string as its result. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +assembler, grammar, graph, parsing, tree, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_ast.n Index: embedded/man/files/modules/grammar_me/me_ast.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_ast.n @@ -0,0 +1,344 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_ast.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me_ast" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me_ast \- Various representations of ASTs +.SH DESCRIPTION +This document specifies various representations for the +\fIabstract syntax tree\fRs (short \fIAST\fR) generated by +instances of ME virtual machines, independent of variant. +Please go and read the document \fBgrammar::me_intro\fR first if +you do not know what a ME virtual machine is. +.PP +ASTs and all the representations we specify distinguish between two +types of nodes, namely: +.PP +.TP +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. +.TP +Nonterminal +Nonterminal nodes represent a nonterminal symbol of the grammar used +during parsing. They can occur as leaf and inner nodes of the +tree. +.PP +.PP +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). +.PP +The root of an AS tree can be either a terminal or nonterminal node. +.SH "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. +.PP +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. +.SH "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 +\fBstruct::tree\fR. I.e it has to support at least all of the +methods described by that package, and may support more. +.PP +Because of this the remainder of the specifications is written using +the terms of \fBstruct::tree\fR. +.PP +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: +.TP +type +The type of the AST node. The recognized values are \fBterminal\fR +and \fBnonterminal\fR. +.TP +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. +.TP +detail +This attribute is present only for nonterminal nodes. It contains the +name of the nonterminal symbol stored in the node. +.PP +.SH "EXTENDED AST OBJECTS" +Extended AST objects are like AST objects, with additional +information. +.TP +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. +.sp +Each element of the list contains the token name, the associated +lexeme attribute, line number, and column index, in this order. +.TP +range_lc +This new attribute is defined for all nodes, and contains the +locations from attribute \fIrange\fR translated into line number and +column index. Lines are counted from 1, columns are counted from 0. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +AST, abstract syntax tree +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_cpu.n Index: embedded/man/files/modules/grammar_me/me_cpu.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_cpu.n @@ -0,0 +1,530 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_cpu.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005-2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me::cpu" n 0.2 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me::cpu \- Virtual machine implementation II for parsing token streams +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBgrammar::me::cpu ?0.2?\fR +.sp +\fB::grammar::me::cpu\fR \fImeName\fR \fImatchcode\fR +.sp +\fBmeName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fImeName\fR \fBlc\fR \fIlocation\fR +.sp +\fImeName\fR \fBtok\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fImeName\fR \fBpc\fR \fIstate\fR +.sp +\fImeName\fR \fBiseof\fR \fIstate\fR +.sp +\fImeName\fR \fBat\fR \fIstate\fR +.sp +\fImeName\fR \fBcc\fR \fIstate\fR +.sp +\fImeName\fR \fBsv\fR +.sp +\fImeName\fR \fBok\fR +.sp +\fImeName\fR \fBerror\fR +.sp +\fImeName\fR \fBlstk\fR \fIstate\fR +.sp +\fImeName\fR \fBastk\fR \fIstate\fR +.sp +\fImeName\fR \fBmstk\fR \fIstate\fR +.sp +\fImeName\fR \fBestk\fR \fIstate\fR +.sp +\fImeName\fR \fBrstk\fR \fIstate\fR +.sp +\fImeName\fR \fBnc\fR \fIstate\fR +.sp +\fImeName\fR \fBast\fR +.sp +\fImeName\fR \fBhalted\fR +.sp +\fImeName\fR \fBcode\fR +.sp +\fImeName\fR \fBeof\fR +.sp +\fImeName\fR \fBput\fR \fItok\fR \fIlex\fR \fIline\fR \fIcol\fR +.sp +\fImeName\fR \fBputstring\fR \fIstring\fR \fIlvar\fR \fIcvar\fR +.sp +\fImeName\fR \fBrun\fR ?\fIn\fR? +.sp +\fImeName\fR \fBpull\fR \fInextcmd\fR +.sp +\fImeName\fR \fBreset\fR +.sp +\fImeName\fR \fBdestroy\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides an implementation of the ME virtual machine. +Please go and read the document \fBgrammar::me_intro\fR first if +you do not know what a ME virtual machine is. +.PP +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. +.PP +Internally the package actually uses the value-based machine +manipulation commands as provided by the package +\fBgrammar::me::cpu::core\fR to perform its duties. +.SH API +.SS "CLASS API" +The package directly provides only a single command for the +construction of ME virtual machines. +.TP +\fB::grammar::me::cpu\fR \fImeName\fR \fImatchcode\fR +The command creates a new ME machine object with an associated global +Tcl command whose name is \fImeName\fR. This command may be used to +invoke various operations on the machine. +It has the following general form: +.RS +.TP +\fBmeName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.sp +The argument \fImatchcode\fR contains the match instructions the +machine has to execute while parsing the input stream. Please read +section \fBMATCH CODE REPRESENTATION\fR of the +documentation for the package \fBgrammar::me::cpu::core\fR for +the specification of the structure of this value. +.sp +The \fItokmap\fR argument taken by the implementation provided by the +package \fBgrammar::me::tcl\fR is here hidden inside of the match +instructions and therefore not needed. +.PP +.PP +.SS "OBJECT API" +All ME virtual machine objects created by the class command specified +in section \fBCLASS API\fR support the methods listed below. +.PP +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. +.TP +\fImeName\fR \fBlc\fR \fIlocation\fR +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. +.sp +\fINote\fR 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 +\fB0\fR to \fB6\fR, 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. +.TP +\fImeName\fR \fBtok\fR ?\fIfrom\fR ?\fIto\fR?? +This method returns a Tcl list containing the part of the input stream +between the locations \fIfrom\fR and \fIto\fR (both inclusive). If +\fIto\fR is not specified it will default to the value of \fIfrom\fR. +If \fIfrom\fR is not specified either the whole input stream is returned. +.sp +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 \fBlc\fR. +.TP +\fImeName\fR \fBpc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter. +.TP +\fImeName\fR \fBiseof\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag. +.TP +\fImeName\fR \fBat\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current location in the input stream. +.TP +\fImeName\fR \fBcc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current token. +.TP +\fImeName\fR \fBsv\fR +This command returns the current semantic value \fISV\fR stored in +the machine. This is an abstract syntax tree as specified in the +document \fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +.TP +\fImeName\fR \fBok\fR +This method returns the current match status \fIOK\fR. +.TP +\fImeName\fR \fBerror\fR +This method returns the current error status \fIER\fR. +.TP +\fImeName\fR \fBlstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the location stack. +.TP +\fImeName\fR \fBastk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the AST stack. +.TP +\fImeName\fR \fBmstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the AST marker stack. +.TP +\fImeName\fR \fBestk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the error stack. +.TP +\fImeName\fR \fBrstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the subroutine return stack. +.TP +\fImeName\fR \fBnc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary. +.TP +\fImeName\fR \fBast\fR +This method returns the current top entry of the AST stack \fIAS\fR. +This is an abstract syntax tree as specified in the document +\fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +.TP +\fImeName\fR \fBhalted\fR +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 \fBrun\fR the engine will be ignored, +until a \fBreset\fR is made. +.TP +\fImeName\fR \fBcode\fR +This method returns the \fIcode\fR information used to construct the +object. In other words, the match program executed by the machine. +.TP +\fImeName\fR \fBeof\fR +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. +.TP +\fImeName\fR \fBput\fR \fItok\fR \fIlex\fR \fIline\fR \fIcol\fR +This method adds the token \fItok\fR to the end of the input stream, +with associated lexeme data \fIlex\fR and \fIline\fR/\fIcol\fRumn +information. +.TP +\fImeName\fR \fBputstring\fR \fIstring\fR \fIlvar\fR \fIcvar\fR +This method adds each individual character in the \fIstring\fR 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 \fIlvar\fR and +\fIcvar\fR. +.TP +\fImeName\fR \fBrun\fR ?\fIn\fR? +This methods causes the engine to execute match instructions until +either +.RS +.IP \(bu +\fIn\fR instructions have been executed, or +.IP \(bu +a halt instruction was executed, or +.IP \(bu +the input queue is empty and the code is asking for more tokens to +process. +.RE +.sp +If no limit \fIn\fR was set only the last two conditions are checked +for. +.TP +\fImeName\fR \fBpull\fR \fInextcmd\fR +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 +\fInextcmd\fR ceases to deliver more tokens. +.sp +The command prefix \fInextcmd\fR 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 +\fIict_advance\fR. +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. +.sp +The end of the input stream for this method does not imply that method +\fBeof\fR 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. +.TP +\fImeName\fR \fBreset\fR +This method resets the machine to its initial state, discarding any +state it may have. +.TP +\fImeName\fR \fBdestroy\fR +This method deletes the object and releases all resurces it claimed. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +grammar, parsing, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005-2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_cpucore.n Index: embedded/man/files/modules/grammar_me/me_cpucore.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_cpucore.n @@ -0,0 +1,643 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_cpucore.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005-2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me::cpu::core" n 0.2 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me::cpu::core \- ME virtual machine state manipulation +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBgrammar::me::cpu::core ?0.2?\fR +.sp +\fB::grammar::me::cpu::core\fR \fBdisasm\fR \fIasm\fR +.sp +\fB::grammar::me::cpu::core\fR \fBasm\fR \fIasm\fR +.sp +\fB::grammar::me::cpu::core\fR \fBnew\fR \fIasm\fR +.sp +\fB::grammar::me::cpu::core\fR \fBlc\fR \fIstate\fR \fIlocation\fR +.sp +\fB::grammar::me::cpu::core\fR \fBtok\fR \fIstate\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fB::grammar::me::cpu::core\fR \fBpc\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBiseof\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBat\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBcc\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBsv\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBok\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBerror\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBlstk\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBastk\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBmstk\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBestk\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBrstk\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBnc\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBast\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBhalted\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBcode\fR \fIstate\fR +.sp +\fB::grammar::me::cpu::core\fR \fBeof\fR \fIstatevar\fR +.sp +\fB::grammar::me::cpu::core\fR \fBput\fR \fIstatevar\fR \fItok\fR \fIlex\fR \fIline\fR \fIcol\fR +.sp +\fB::grammar::me::cpu::core\fR \fBrun\fR \fIstatevar\fR ?\fIn\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides an implementation of the ME virtual machine. +Please go and read the document \fBgrammar::me_intro\fR first if +you do not know what a ME virtual machine is. +.PP +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. +.PP +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 +\fIonly\fR through the commands of this package to ensure that +internal representation is not shimmered away. +.PP +The actual structure used by all state values is described in section +\fBCPU STATE\fR. +.SH API +The package directly provides only a single command, and all the +functionality is made available through its methods. +.TP +\fB::grammar::me::cpu::core\fR \fBdisasm\fR \fIasm\fR +This method returns a list containing a disassembly of the match +instructions in \fIasm\fR. The format of \fIasm\fR is specified in the +section \fBMATCH PROGRAM REPRESENTATION\fR. +.sp +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. +.TP +\fB::grammar::me::cpu::core\fR \fBasm\fR \fIasm\fR +This method returns code in the format as specified in section +\fBMATCH PROGRAM REPRESENTATION\fR generated from ME assembly +code \fIasm\fR, which is in the format as returned by the method +\fBdisasm\fR. +.TP +\fB::grammar::me::cpu::core\fR \fBnew\fR \fIasm\fR +This method creates state value for a ME virtual machine in its +initial state and returns it as its result. +.sp +The argument \fImatchcode\fR 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 +\fBMATCH PROGRAM REPRESENTATION\fR. +.sp +The \fItokmap\fR argument taken by the implementation provided by the +package \fBgrammar::me::tcl\fR is here hidden inside of the match +instructions and therefore not needed. +.TP +\fB::grammar::me::cpu::core\fR \fBlc\fR \fIstate\fR \fIlocation\fR +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. +.sp +\fINote\fR 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 +\fB0\fR to \fB6\fR, 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. +.sp +This utility allows higher levels to convert the location offsets +found in the error status and the AST into more human readable data. +.TP +\fB::grammar::me::cpu::core\fR \fBtok\fR \fIstate\fR ?\fIfrom\fR ?\fIto\fR?? +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 \fIfrom\fR and \fIto\fR (both inclusive). If \fIto\fR is not +specified it will default to the value of \fIfrom\fR. If \fIfrom\fR is +not specified either the whole input stream is returned. +.sp +This method places the same restrictions on its location arguments as +the method \fBlc\fR. +.TP +\fB::grammar::me::cpu::core\fR \fBpc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter. +.TP +\fB::grammar::me::cpu::core\fR \fBiseof\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag. +.TP +\fB::grammar::me::cpu::core\fR \fBat\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current location in the input stream. +.TP +\fB::grammar::me::cpu::core\fR \fBcc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current token. +.TP +\fB::grammar::me::cpu::core\fR \fBsv\fR \fIstate\fR +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 +\fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +.TP +\fB::grammar::me::cpu::core\fR \fBok\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the match status stored in it. +.TP +\fB::grammar::me::cpu::core\fR \fBerror\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the current error status stored in it. +.TP +\fB::grammar::me::cpu::core\fR \fBlstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the location stack. +.TP +\fB::grammar::me::cpu::core\fR \fBastk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the AST stack. +.TP +\fB::grammar::me::cpu::core\fR \fBmstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the AST marker stack. +.TP +\fB::grammar::me::cpu::core\fR \fBestk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the error stack. +.TP +\fB::grammar::me::cpu::core\fR \fBrstk\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the subroutine return stack. +.TP +\fB::grammar::me::cpu::core\fR \fBnc\fR \fIstate\fR +This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary. +.TP +\fB::grammar::me::cpu::core\fR \fBast\fR \fIstate\fR +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 +\fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +.TP +\fB::grammar::me::cpu::core\fR \fBhalted\fR \fIstate\fR +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. +.TP +\fB::grammar::me::cpu::core\fR \fBcode\fR \fIstate\fR +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. +.TP +\fB::grammar::me::cpu::core\fR \fBeof\fR \fIstatevar\fR +This method takes the state value of a ME virtual machine as stored in +the variable named by \fIstatevar\fR 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. +.TP +\fB::grammar::me::cpu::core\fR \fBput\fR \fIstatevar\fR \fItok\fR \fIlex\fR \fIline\fR \fIcol\fR +This method takes the state value of a ME virtual machine as stored in +the variable named by \fIstatevar\fR and modifies it so that the token +\fItok\fR is added to the end of the input queue, with associated +lexeme data \fIlex\fR and \fIline\fR/\fIcol\fRumn information. +.sp +The operation will fail with an error if the eof flag of the machine +has been set through the method \fBeof\fR. +.TP +\fB::grammar::me::cpu::core\fR \fBrun\fR \fIstatevar\fR ?\fIn\fR? +This method takes the state value of a ME virtual machine as stored in +the variable named by \fIstatevar\fR, executes a number of +instructions and stores the state resulting from their modifications +back into the variable. +.sp +The execution loop will run until either +.RS +.IP \(bu +\fIn\fR instructions have been executed, or +.IP \(bu +a halt instruction was executed, or +.IP \(bu +the input queue is empty and the code is asking for more tokens to +process. +.RE +.sp +If no limit \fIn\fR was set only the last two conditions are checked +for. +.PP +.SS "MATCH PROGRAM REPRESENTATION" +A match program is represented by nested Tcl list. The first element, +\fIasm\fR, is a list of integer numbers, the instructions to execute, +and their arguments. The second element, \fIpool\fR, is a list of +strings, referenced by the instructions, for error messages, token +names, etc. The third element, \fItokmap\fR, provides ordering +information for the tokens, mapping their names to their numerical +rank. This element can be empty, forcing lexicographic comparison when +matching ranges. +.PP +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. +.PP +Jump destination arguments are absolute indices into the \fIasm\fR +element, refering to the instruction to jump to. Any string arguments +are absolute indices into the \fIpool\fR element. Tokens, characters, +messages, and token (actually character) classes to match are coded as +references into the \fIpool\fR as well. +.PP +.IP [1] +"\fBict_advance\fR \fImessage\fR" +.IP [2] +"\fBict_match_token\fR \fItok\fR \fImessage\fR" +.IP [3] +"\fBict_match_tokrange\fR \fItokbegin\fR \fItokend\fR \fImessage\fR" +.IP [4] +"\fBict_match_tokclass\fR \fIcode\fR \fImessage\fR" +.IP [5] +"\fBinc_restore\fR \fIbranchlabel\fR \fInt\fR" +.IP [6] +"\fBinc_save\fR \fInt\fR" +.IP [7] +"\fBicf_ntcall\fR \fIbranchlabel\fR" +.IP [8] +"\fBicf_ntreturn\fR" +.IP [9] +"\fBiok_ok\fR" +.IP [10] +"\fBiok_fail\fR" +.IP [11] +"\fBiok_negate\fR" +.IP [12] +"\fBicf_jalways\fR \fIbranchlabel\fR" +.IP [13] +"\fBicf_jok\fR \fIbranchlabel\fR" +.IP [14] +"\fBicf_jfail\fR \fIbranchlabel\fR" +.IP [15] +"\fBicf_halt\fR" +.IP [16] +"\fBicl_push\fR" +.IP [17] +"\fBicl_rewind\fR" +.IP [18] +"\fBicl_pop\fR" +.IP [19] +"\fBier_push\fR" +.IP [20] +"\fBier_clear\fR" +.IP [21] +"\fBier_nonterminal\fR \fImessage\fR" +.IP [22] +"\fBier_merge\fR" +.IP [23] +"\fBisv_clear\fR" +.IP [24] +"\fBisv_terminal\fR" +.IP [25] +"\fBisv_nonterminal_leaf\fR \fInt\fR" +.IP [26] +"\fBisv_nonterminal_range\fR \fInt\fR" +.IP [27] +"\fBisv_nonterminal_reduce\fR \fInt\fR" +.IP [28] +"\fBias_push\fR" +.IP [29] +"\fBias_mark\fR" +.IP [30] +"\fBias_mrewind\fR" +.IP [31] +"\fBias_mpop\fR" +.PP +.SH "CPU STATE" +A state value is a list containing the following elements, in the order listed below: +.IP [1] +\fIcode\fR: Match instructions, see \fBMATCH PROGRAM REPRESENTATION\fR. +.IP [2] +\fIpc\fR: Program counter, \fIint\fR. +.IP [3] +\fIhalt\fR: Halt flag, \fIboolean\fR. +.IP [4] +\fIeof\fR: Eof flag, \fIboolean\fR +.IP [5] +\fItc\fR: Terminal cache, and input queue. Structure see below. +.IP [6] +\fIcl\fR: Current location, \fIint\fR. +.IP [7] +\fIct\fR: Current token, \fIstring\fR. +.IP [8] +\fIok\fR: Match status, \fIboolean\fR. +.IP [9] +\fIsv\fR: Semantic value, \fIlist\fR. +.IP [10] +\fIer\fR: Error status, \fIlist\fR. +.IP [11] +\fIls\fR: Location stack, \fIlist\fR. +.IP [12] +\fIas\fR: AST stack, \fIlist\fR. +.IP [13] +\fIms\fR: AST marker stack, \fIlist\fR. +.IP [14] +\fIes\fR: Error stack, \fIlist\fR. +.IP [15] +\fIrs\fR: Return stack, \fIlist\fR. +.IP [16] +\fInc\fR: Nonterminal cache, \fIdictionary\fR. +.PP +.PP +\fItc\fR, 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. +.PP +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. +.PP +\fIer\fR, 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 \fIpool\fR element of the \fIcode\fR. +.PP +\fInc\fR, 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +grammar, parsing, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005-2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_intro.n Index: embedded/man/files/modules/grammar_me/me_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_intro.n @@ -0,0 +1,309 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me_intro" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me_intro \- Introduction to virtual machines for parsing token streams +.SH DESCRIPTION +This document is an introduction to and overview of the basic +facilities for the parsing and/or matching of \fItoken\fR +streams. One possibility often used for the token domain are +characters. +.PP +The packages themselves all provide variants of one +\fIvirtual machine\fR, called a \fImatch engine\fR (short +\fIME\fR), 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 +(\fIAST\fR). +.PP +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. +.PP +The relevant documents are: +.PP +.TP +\fBgrammar::me_vm\fR +Virtual machine specification. +.TP +\fBgrammar::me_ast\fR +Specification of various representations used for abstract syntax +trees. +.TP +\fBgrammar::me::util\fR +Utility commands. +.TP +\fBgrammar::me::tcl\fR +Singleton ME virtual machine implementation tied to Tcl for control +flow and stacks. Hardwired for pull operation. Uninteruptible during +processing. +.TP +\fBgrammar::me::cpu\fR +Object-based ME virtual machine implementation with explicit control +flow, and stacks, using bytecodes. Suspend/Resumable. Push/pull +operation. +.TP +\fBgrammar::me::cpu::core\fR +Core functionality for state manipulation and stepping used in the +bytecode based implementation of ME virtual machines. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +CFG, CFL, LL(k), PEG, TPDL, context-free grammar, context-free languages, expression, grammar, matching, parsing, parsing expression grammar, push down automaton, recursive descent, top-down parsing languages, transducer, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_tcl.n Index: embedded/man/files/modules/grammar_me/me_tcl.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_tcl.n @@ -0,0 +1,597 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_tcl.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me::tcl" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me::tcl \- Virtual machine implementation I for parsing token streams +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBgrammar::me::tcl ?0.1?\fR +.sp +\fB::grammar::me::tcl\fR \fBcmd\fR \fI...\fR +.sp +\fB::grammar::me::tcl\fR \fBinit\fR \fInextcmd\fR ?\fItokmap\fR? +.sp +\fB::grammar::me::tcl\fR \fBlc\fR \fIlocation\fR +.sp +\fB::grammar::me::tcl\fR \fBtok\fR \fIfrom\fR ?\fIto\fR? +.sp +\fB::grammar::me::tcl\fR \fBtokens\fR +.sp +\fB::grammar::me::tcl\fR \fBsv\fR +.sp +\fB::grammar::me::tcl\fR \fBast\fR +.sp +\fB::grammar::me::tcl\fR \fBastall\fR +.sp +\fB::grammar::me::tcl\fR \fBctok\fR +.sp +\fB::grammar::me::tcl\fR \fBnc\fR +.sp +\fB::grammar::me::tcl\fR \fBnext\fR +.sp +\fB::grammar::me::tcl\fR \fBord\fR +.sp +\fB::grammar::me::tcl::ict_advance\fR \fImessage\fR +.sp +\fB::grammar::me::tcl::ict_match_token\fR \fItok\fR \fImessage\fR +.sp +\fB::grammar::me::tcl::ict_match_tokrange\fR \fItokbegin\fR \fItokend\fR \fImessage\fR +.sp +\fB::grammar::me::tcl::ict_match_tokclass\fR \fIcode\fR \fImessage\fR +.sp +\fB::grammar::me::tcl::inc_restore\fR \fInt\fR +.sp +\fB::grammar::me::tcl::inc_save\fR \fInt\fR \fIstartlocation\fR +.sp +\fB::grammar::me::tcl::iok_ok\fR +.sp +\fB::grammar::me::tcl::iok_fail\fR +.sp +\fB::grammar::me::tcl::iok_negate\fR +.sp +\fB::grammar::me::tcl::icl_get\fR +.sp +\fB::grammar::me::tcl::icl_rewind\fR \fIoldlocation\fR +.sp +\fB::grammar::me::tcl::ier_get\fR +.sp +\fB::grammar::me::tcl::ier_clear\fR +.sp +\fB::grammar::me::tcl::ier_nonterminal\fR \fImessage\fR \fIlocation\fR +.sp +\fB::grammar::me::tcl::ier_merge\fR \fIolderror\fR +.sp +\fB::grammar::me::tcl::isv_clear\fR +.sp +\fB::grammar::me::tcl::isv_terminal\fR +.sp +\fB::grammar::me::tcl::isv_nonterminal_leaf\fR \fInt\fR \fIstartlocation\fR +.sp +\fB::grammar::me::tcl::isv_nonterminal_range\fR \fInt\fR \fIstartlocation\fR +.sp +\fB::grammar::me::tcl::isv_nonterminal_reduce\fR \fInt\fR \fIstartlocation\fR ?\fImarker\fR? +.sp +\fB::grammar::me::tcl::ias_push\fR +.sp +\fB::grammar::me::tcl::ias_mark\fR +.sp +\fB::grammar::me::tcl::ias_pop2mark\fR \fImarker\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides an implementation of the ME virtual machine. +Please go and read the document \fBgrammar::me_intro\fR first if +you do not know what a ME virtual machine is. +.PP +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. +.PP +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. +.PP +A related package is \fBgrammar::peg::interp\fR which provides a +generic interpreter / parser for parsing expression grammars (PEGs), +implemented on top of this implementation of the ME virtual machine. +.SH 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. +.TP +\fB::grammar::me::tcl\fR \fBcmd\fR \fI...\fR +This is an ensemble command providing access to the commands listed in +this section. See the methods themselves for detailed specifications. +.TP +\fB::grammar::me::tcl\fR \fBinit\fR \fInextcmd\fR ?\fItokmap\fR? +This command (re)initializes the machine. It returns the empty +string. This command has to be invoked before any other command of +this package. +.sp +The command prefix \fInextcmd\fR 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 +\fIict_advance\fR. +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. +.sp +The optional dictionary \fItokmap\fR maps from tokens to integer +numbers. If present the numbers impose an order on the tokens, which +is subsequently used by \fIict_match_tokrange\fR 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. +.TP +\fB::grammar::me::tcl\fR \fBlc\fR \fIlocation\fR +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. +.sp +\fINote\fR 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 +\fB0\fR to \fB6\fR, 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. +.sp +After a call of \fBinit\fR the state used for the conversion is +cleared, making further conversions impossible until the machine has +read tokens again. +.TP +\fB::grammar::me::tcl\fR \fBtok\fR \fIfrom\fR ?\fIto\fR? +This command returns a Tcl list containing the part of the input +stream between the locations \fIfrom\fR and \fIto\fR (both +inclusive). If \fIto\fR is not specified it will default to the value +of \fIfrom\fR. +.sp +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 \fInextcmd\fR callback given to \fB::grammar::me::tcl::init\fR +.sp +This command places the same restrictions on its location arguments as +\fB::grammar::me::tcl::lc\fR. +.TP +\fB::grammar::me::tcl\fR \fBtokens\fR +This command returns the number of tokens currently known to the ME +virtual machine. +.TP +\fB::grammar::me::tcl\fR \fBsv\fR +This command returns the current semantic value \fISV\fR stored in +the machine. This is an abstract syntax tree as specified in the +document \fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +.TP +\fB::grammar::me::tcl\fR \fBast\fR +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 \fBgrammar::me_ast\fR, section +\fBAST VALUES\fR. +.TP +\fB::grammar::me::tcl\fR \fBastall\fR +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 +\fBgrammar::me_ast\fR, section \fBAST VALUES\fR. +The top of the stack resides at the end of the list. +.TP +\fB::grammar::me::tcl\fR \fBctok\fR +This method returns the current token considered by the ME virtual +machine. +.TP +\fB::grammar::me::tcl\fR \fBnc\fR +This method returns the contents of the nonterminal cache as a +dictionary mapping from "\fBsymbol\fR,\fBlocation\fR" to match +information. +.TP +\fB::grammar::me::tcl\fR \fBnext\fR +This method returns the next token callback as specified during +initialization of the ME virtual machine. +.TP +\fB::grammar::me::tcl\fR \fBord\fR +This method returns a dictionary containing the \fItokmap\fR specified +during initialization of the ME virtual machine. +\fB\fB::grammar::me::tcl::ok\fR\fR +This variable contains the current match status \fIOK\fR. 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. +.PP +.PP +.SH "MACHINE STATE" +Please go and read the document \fBgrammar::me_vm\fR first for a +specification of the basic ME virtual machine and its state. +.PP +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. +.SH "MACHINE INSTRUCTIONS" +Please go and read the document \fBgrammar::me_vm\fR first for a +specification of the basic ME virtual machine and its instruction set. +.PP +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 \fInot\fR +reachable through the ensemble command \fB::grammar::me::tcl\fR. +.PP +.TP +\fB::grammar::me::tcl::ict_advance\fR \fImessage\fR +No changes. +.TP +\fB::grammar::me::tcl::ict_match_token\fR \fItok\fR \fImessage\fR +No changes. +.TP +\fB::grammar::me::tcl::ict_match_tokrange\fR \fItokbegin\fR \fItokend\fR \fImessage\fR +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. +.TP +\fB::grammar::me::tcl::ict_match_tokclass\fR \fIcode\fR \fImessage\fR +No changes. +.TP +\fB::grammar::me::tcl::inc_restore\fR \fInt\fR +Instead of taking a branchlabel the command returns a boolean value. +The result will be \fBtrue\fR if and only if cached information was +found. The caller has to perform the appropriate branching. +.TP +\fB::grammar::me::tcl::inc_save\fR \fInt\fR \fIstartlocation\fR +The command takes the start location as additional argument, as it is +managed on the Tcl stack, and not in the machine state. +.TP +\fBicf_ntcall\fR \fIbranchlabel\fR +.TP +\fBicf_ntreturn\fR +These two instructions are not mapped to commands. They are control +flow instructions and handled in Tcl. +.TP +\fB::grammar::me::tcl::iok_ok\fR +No changes. +.TP +\fB::grammar::me::tcl::iok_fail\fR +No changes. +.TP +\fB::grammar::me::tcl::iok_negate\fR +No changes. +.TP +\fBicf_jalways\fR \fIbranchlabel\fR +.TP +\fBicf_jok\fR \fIbranchlabel\fR +.TP +\fBicf_jfail\fR \fIbranchlabel\fR +.TP +\fBicf_halt\fR +These four instructions are not mapped to commands. They are control +flow instructions and handled in Tcl. +.TP +\fB::grammar::me::tcl::icl_get\fR +This command returns the current location \fICL\fR in the input. +It replaces \fIicl_push\fR. +.TP +\fB::grammar::me::tcl::icl_rewind\fR \fIoldlocation\fR +The command takes the location as argument as it comes from the +Tcl stack, not the machine state. +.TP +\fBicl_pop\fR +Not mapped, the stacks are not managed by the package. +.TP +\fB::grammar::me::tcl::ier_get\fR +This command returns the current error state \fIER\fR. +It replaces \fIier_push\fR. +.TP +\fB::grammar::me::tcl::ier_clear\fR +No changes. +.TP +\fB::grammar::me::tcl::ier_nonterminal\fR \fImessage\fR \fIlocation\fR +The command takes the location as argument as it comes from the +Tcl stack, not the machine state. +.TP +\fB::grammar::me::tcl::ier_merge\fR \fIolderror\fR +The command takes the second error state to merge as argument as it +comes from the Tcl stack, not the machine state. +.TP +\fB::grammar::me::tcl::isv_clear\fR +No changes. +.TP +\fB::grammar::me::tcl::isv_terminal\fR +No changes. +.TP +\fB::grammar::me::tcl::isv_nonterminal_leaf\fR \fInt\fR \fIstartlocation\fR +The command takes the start location as argument as it comes from the +Tcl stack, not the machine state. +.TP +\fB::grammar::me::tcl::isv_nonterminal_range\fR \fInt\fR \fIstartlocation\fR +The command takes the start location as argument as it comes from the +Tcl stack, not the machine state. +.TP +\fB::grammar::me::tcl::isv_nonterminal_reduce\fR \fInt\fR \fIstartlocation\fR ?\fImarker\fR? +The command takes start location and marker as argument as it comes +from the Tcl stack, not the machine state. +.TP +\fB::grammar::me::tcl::ias_push\fR +No changes. +.TP +\fB::grammar::me::tcl::ias_mark\fR +This command returns a marker for the current state of the AST stack +\fIAS\fR. The marker stack is not managed by the machine. +.TP +\fB::grammar::me::tcl::ias_pop2mark\fR \fImarker\fR +The command takes the marker as argument as it comes from the +Tcl stack, not the machine state. It replaces \fIias_mpop\fR. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +grammar, parsing, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_util.n Index: embedded/man/files/modules/grammar_me/me_util.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_util.n @@ -0,0 +1,326 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_util.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me::util" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me::util \- AST utilities +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBgrammar::me::util ?0.1?\fR +.sp +\fB::grammar::me::util::ast2tree\fR \fIast\fR \fItree\fR ?\fIroot\fR? +.sp +\fB::grammar::me::util::ast2etree\fR \fIast\fR \fImcmd\fR \fItree\fR ?\fIroot\fR? +.sp +\fBmcmd\fR \fBlc\fR \fIlocation\fR +.sp +\fBmcmd\fR \fBtok\fR \fIfrom\fR ?\fIto\fR? +.sp +\fB::grammar::me::util::tree2ast\fR \fItree\fR ?\fIroot\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a number of utility command for the conversion +between the various representations of abstract syntax trees as +specified in the document \fBgrammar::me_ast\fR. +.TP +\fB::grammar::me::util::ast2tree\fR \fIast\fR \fItree\fR ?\fIroot\fR? +This command converts an \fIast\fR from value to object +representation. All nodes in the \fIast\fR will be converted into +nodes of this \fItree\fR, with the root of the AST a child of the node +\fIroot\fR. 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. +.TP +\fB::grammar::me::util::ast2etree\fR \fIast\fR \fImcmd\fR \fItree\fR ?\fIroot\fR? +This command is like \fB::grammar::me::util::ast2tree\fR, except that +the result is in the extended object representation of the input AST. +The source of the extended information is the command prefix +\fImcmd\fR. +It has to understand two methods, \fBlc\fR, and \fBtok\fR, with +the semantics specified below. +.RS +.TP +\fBmcmd\fR \fBlc\fR \fIlocation\fR +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. +.TP +\fBmcmd\fR \fBtok\fR \fIfrom\fR ?\fIto\fR? +Takes one or two locations \fIfrom\fR and \fIto\fR as offset in the +input stream and returns a Tcl list containing the specified part of +the input stream. Both location are inclusive. If \fIto\fR is not +specified it will default to the value of \fIfrom\fR. +.sp +Each element of the returned list is a list containing the token, its +associated lexeme, the line number, and column index, in this order. +.RE +.sp +Both the ensemble command \fB::grammar::me::tcl\fR provided by the +package \fBgrammar::me::tcl\fR and the objects command created by +the package \fB::grammar::me::cpu\fR fit the above specification. +.TP +\fB::grammar::me::util::tree2ast\fR \fItree\fR ?\fIroot\fR? +This command converts an \fIast\fR in (extended) object representation +into a value and returns it. +If a \fIroot\fR node is specified the AST is generated from that node +downward. Otherwise the root of the tree object is used as the +starting point. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +abstract syntax tree, syntax tree, tree +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_me/me_vm.n Index: embedded/man/files/modules/grammar_me/me_vm.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_me/me_vm.n @@ -0,0 +1,726 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_me/me_vm.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::me_vm" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::me_vm \- Virtual machine for parsing token streams +.SH DESCRIPTION +Please go and read the document \fBgrammar::me_intro\fR first for +an overview of the various documents and their relations. +.PP +This document specifies a virtual machine for the controlled matching +and parsing of token streams, creating an +\fIabstract syntax tree\fR (short \fIAST\fR) 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. +.PP +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. +.PP +The following sections will discuss first the abstract state kept by +ME virtual machines, and then their instruction set. +.SH "MACHINE STATE" +A ME virtual machine manages the following state: +.TP +\fICurrent token\fR CT +The token from the input under consideration by the machine. +.sp +This information is used and modified by the instructions defined in +the section +\fBTERMINAL MATCHING\fR. +.TP +\fICurrent location\fR CL +The location of the \fIcurrent token\fR in the input stream, as +offset relative to the beginning of the stream. The first token is +considered to be at offset \fB0\fR. +.sp +This information is implicitly used and modified by the instructions +defined in the sections +\fBTERMINAL MATCHING\fR and +\fBNONTERMINAL MATCHING\fR, +and can be directly queried and modified by the instructions defined +in section +\fBINPUT LOCATION HANDLING\fR. +.TP +\fILocation stack\fR 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. +.sp +This information is implicitly used and modified by the instructions +defined in the sections +\fBTERMINAL MATCHING\fR and +\fBNONTERMINAL MATCHING\fR, +and can be directly queried and modified by the instructions defined +in section +\fBINPUT LOCATION HANDLING\fR. +.TP +\fIMatch status\fR OK +A boolean value, the result of the last attempt at matching input. +It is set to \fBtrue\fR if that attempt was successful, and +\fBfalse\fR otherwise. +.sp +This information is influenced by the instructions defined in the +sections +\fBTERMINAL MATCHING\fR, +\fBNONTERMINAL MATCHING\fR, and +\fBUNCONDITIONAL MATCHING\fR. +It is queried by the instructions defined in the section +\fBCONTROL FLOW\fR. +.TP +\fISemantic value\fR 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. +.sp +This information is influenced by the instructions defined in the +sections +\fBSEMANTIC VALUES\fR, and +\fBAST STACK HANDLING\fR. +.TP +\fIAST stack\fR AS +A stack of partial abstract syntax trees constructed by the machine +during matching. +.sp +This information is influenced by the instructions defined in the +sections +\fBSEMANTIC VALUES\fR, and +\fBAST STACK HANDLING\fR. +.TP +\fIAST Marker stack\fR 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. +.sp +This information is influenced by the instructions defined in the +sections +\fBSEMANTIC VALUES\fR, and +\fBAST STACK HANDLING\fR. +.TP +\fIError status\fR 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. +.sp +\fINote\fR 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. +.sp +This information is queried and influenced by the instructions defined +in the sections +\fBTERMINAL MATCHING\fR, +\fBNONTERMINAL MATCHING\fR, and +\fBERROR HANDLING\fR. +.TP +\fIError stack\fR 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. +.sp +This information is queried and influenced by the instructions defined +in the sections +\fBTERMINAL MATCHING\fR, +\fBNONTERMINAL MATCHING\fR, and +\fBERROR HANDLING\fR. +.TP +\fIReturn stack\fR 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. +.sp +This information is queried and influenced by the instructions defined +in the section +\fBNONTERMINAL MATCHING\fR. +.TP +\fINonterminal cache\fR NC +A cache of machine states (A 4-tuple containing a location in the +input, match status \fIOK\fR, semantic value \fISV\fR, and error +status \fIER\fR) keyed by name of nonterminal symbol and location in +the input stream. +.sp +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. +.sp +This status is queried and influenced by the instructions defined in +the section +\fBNONTERMINAL MATCHING\fR. +.PP +.SH "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. +.SS "TERMINAL MATCHING" +First the instructions to match tokens from the input stream, and +by extension all terminal symbols. +.PP +These instructions are the only ones which may retrieve a new token +from the input stream. This is a \fImay\fR and not a \fIwill\fR +because the instructions will a retrieve new token if, and only if the +current location \fICL\fR is at the head of the stream. +If the machine has backtracked (see \fBicl_rewind\fR) the instructions +will retrieve the token to compare against from the internal cache. +.PP +.TP +\fBict_advance\fR \fImessage\fR +This instruction tries to advance to the next token in the input +stream, i.e. the one after the current location \fICL\fR. The +instruction will fail if, and only if the end of the input stream is +reached, i.e. if there is no next token. +.sp +The sucess/failure of the instruction is remembered in the match +status \fIOK\fR. In the case of failure the error status \fIER\fR is +set to the current location and the message \fImessage\fR. +In the case of success the error status \fIER\fR is cleared, the new +token is made the current token \fICT\fR, and the new location is +made the current location \fICL\fR. +.sp +The argument \fImessage\fR is a reference to the string to put into +the error status \fIER\fR, if such is needed. +.TP +\fBict_match_token\fR \fItok\fR \fImessage\fR +This instruction tests the current token \fICT\fR for equality +with the argument \fItok\fR and records the result in the match +status \fIOK\fR. The instruction fails if the current token is +not equal to \fItok\fR. +.sp +In case of failure the error status \fIER\fR is set to the current +location \fICL\fR and the message \fImessage\fR, and the +current location \fICL\fR is moved one token backwards. +Otherwise, i.e. upon success, the error status \fIER\fR is cleared +and the current location \fICL\fR is not touched. +.TP +\fBict_match_tokrange\fR \fItokbegin\fR \fItokend\fR \fImessage\fR +This instruction tests the current token \fICT\fR for being in +the range of tokens from \fItokbegin\fR to \fItokend\fR +(inclusive) and records the result in the match status \fIOK\fR. The +instruction fails if the current token is not inside the range. +.sp +In case of failure the error status \fIER\fR is set to the current +location \fICL\fR and the message \fImessage\fR, and the current location +\fICL\fR is moved one token backwards. +Otherwise, i.e. upon success, the error status \fIER\fR is cleared +and the current location \fICL\fR is not touched. +.TP +\fBict_match_tokclass\fR \fIcode\fR \fImessage\fR +This instruction tests the current token \fICT\fR for being a member +of the token class \fIcode\fR and records the result in the match +status \fIOK\fR. The instruction fails if the current token is not a +member of the specified class. +.sp +In case of failure the error status \fIER\fR is set to the current +location \fICL\fR and the message \fImessage\fR, and the +current location \fICL\fR is moved one token backwards. +Otherwise, i.e. upon success, the error status \fIER\fR is cleared +and the current location \fICL\fR is not touched. +.sp +Currently the following classes are legal: +.RS +.TP +alnum +A token is accepted if it is a unicode alphabetical character, or a digit. +.TP +alpha +A token is accepted if it is a unicode alphabetical character. +.TP +digit +A token is accepted if it is a unicode digit character. +.TP +xdigit +A token is accepted if it is a hexadecimal digit character. +.TP +punct +A token is accepted if it is a unicode punctuation character. +.TP +space +A token is accepted if it is a unicode space character. +.RE +.PP +.PP +.SS "NONTERMINAL MATCHING" +The instructions in this section handle the matching of nonterminal +symbols. They query the nonterminal cache \fINC\fR for saved +information, and put such information into the cache. +.PP +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. +.PP +.TP +\fBinc_restore\fR \fIbranchlabel\fR \fInt\fR +This instruction checks if the nonterminal cache \fINC\fR contains +information about the nonterminal symbol \fInt\fR, at the current +location \fICL\fR. If that is the case the instruction will update +the machine state (current location \fICL\fR, match status \fIOK\fR, +semantic value \fISV\fR, and error status \fIER\fR) with the found +information and continue execution at the instruction refered to by +the \fIbranchlabel\fR. The new current location \fICL\fR will be the +last token matched by the nonterminal symbol, i.e. belonging to it. +.sp +If no information was found the instruction will continue execution at +the next instruction. +.sp +Together with \fBicf_ntcall\fR it is possible to generate code for +memoized and non-memoized matching of nonterminal symbols, either as +subroutine calls, or inlined in the caller. +.TP +\fBinc_save\fR \fInt\fR +This instruction saves the current state of the machine (current +location \fICL\fR, match status \fIOK\fR, semantic value \fISV\fR, +and error status \fIER\fR), to the nonterminal cache \fINC\fR. It +will also pop an entry from the location stack \fILS\fR and save it +as the start location of the match. +.sp +It is expected to be called at the end of matching a nonterminal +symbol, with \fInt\fR the name of the nonterminal symbol the code was +working on. This allows the instruction \fBinc_restore\fR to check for +and retrieve the data, should we have to match this nonterminal symbol +at the same location again, during backtracking. +.TP +\fBicf_ntcall\fR \fIbranchlabel\fR +This instruction invokes the code for matching the nonterminal symbol +\fInt\fR as a subroutine. To this end it stores the current program +counter \fIPC\fR on the return stack \fIRS\fR, the current location +\fICL\fR on the location stack \fILS\fR, and then continues +execution at the address \fIbranchlabel\fR. +.sp +The next matching \fBicf_ntreturn\fR will cause the execution to +continue at the instruction coming after the call. +.TP +\fBicf_ntreturn\fR +This instruction will pop an entry from the return stack \fIRS\fR, +assign it to the program counter \fIPC\fR, and then continue +execution at the new address. +.PP +.PP +.SS "UNCONDITIONAL MATCHING" +The instructions in this section are the remaining match +operators. They change the match status \fIOK\fR directly and +unconditionally. +.TP +\fBiok_ok\fR +This instruction sets the match status \fIOK\fR to \fBtrue\fR, +indicating a successful match. +.TP +\fBiok_fail\fR +This instruction sets the match status \fIOK\fR to \fBfalse\fR, +indicating a failed match. +.TP +\fBiok_negate\fR +This instruction negates the match status \fIOK\fR, turning a failure +into a success and vice versa. +.PP +.PP +.SS "CONTROL FLOW" +The instructions in this section implement both conditional and +unconditional control flow. The conditional jumps query the match +status \fIOK\fR. +.TP +\fBicf_jalways\fR \fIbranchlabel\fR +This instruction sets the program counter \fIPC\fR to the address +specified by \fIbranchlabel\fR and then continues execution from +there. This is an unconditional jump. +.TP +\fBicf_jok\fR \fIbranchlabel\fR +This instruction sets the program counter \fIPC\fR to the address +specified by \fIbranchlabel\fR. This happens if, and only if the match +status \fIOK\fR indicates a success. Otherwise it simply continues +execution at the next instruction. This is a conditional jump. +.TP +\fBicf_jfail\fR \fIbranchlabel\fR +This instruction sets the program counter \fIPC\fR to the address +specified by \fIbranchlabel\fR. This happens if, and only if the match +status \fIOK\fR indicates a failure. Otherwise it simply continues +execution at the next instruction. This is a conditional jump. +.TP +\fBicf_halt\fR +This instruction halts the machine and blocks any further execution. +.PP +.SS "INPUT LOCATION HANDLING" +The instructions in this section are for backtracking, they manipulate +the current location \fICL\fR 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 \fICL\fR to saved +locations, making them one of the components enabling the +implementation of backtracking parsers. +.TP +\fBicl_push\fR +This instruction pushes a copy of the current location \fICL\fR on +the location stack \fILS\fR. +.TP +\fBicl_rewind\fR +This instruction pops an entry from the location stack \fILS\fR and +then moves the current location \fICL\fR back to this point in the +input. +.TP +\fBicl_pop\fR +This instruction pops an entry from the location stack \fILS\fR and +discards it. +.PP +.PP +.SS "ERROR HANDLING" +The instructions in this section provide read and write access to the +error status \fIER\fR of the machine. +.TP +\fBier_push\fR +This instruction pushes a copy of the current error status \fIER\fR +on the error stack \fIES\fR. +.TP +\fBier_clear\fR +This instruction clears the error status \fIER\fR. +.TP +\fBier_nonterminal\fR \fImessage\fR +This instruction checks if the error status \fIER\fR contains an +error whose location is just past the location found in the top entry +of the location stack \fILS\fR. +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 \fImessage\fR. +.TP +\fBier_merge\fR +This instruction pops an entry from the error stack \fIES\fR, merges +it with the current error status \fIER\fR and stores the result of +the merge as the new error status \fIER\fR. +.sp +The merge is performed as described below: +.sp +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). +.PP +.SS "SEMANTIC VALUES" +The instructions in this section manipulate the semantic value +\fISV\fR. +.TP +\fBisv_clear\fR +This instruction clears the semantic value \fISV\fR. +.TP +\fBisv_terminal\fR +This instruction creates a terminal AST node for the current token +\fICT\fR, makes it the semantic value \fISV\fR, and also pushes the +node on the AST stack \fIAS\fR. +.TP +\fBisv_nonterminal_leaf\fR \fInt\fR +This instruction creates a nonterminal AST node without any children +for the nonterminal \fInt\fR, and makes it the semantic value +\fISV\fR. +.sp +This instruction should be executed if, and only if the match status +\fIOK\fR indicates a success. +In the case of a failure \fBisv_clear\fR should be called. +.TP +\fBisv_nonterminal_range\fR \fInt\fR +This instruction creates a nonterminal AST node for the nonterminal +\fInt\fR, with a single terminal node as its child, and makes this AST +the semantic value \fISV\fR. The terminal node refers to the input +string from the location found on top of the location stack \fILS\fR +to the current location \fICL\fR (both inclusive). +.sp +This instruction should be executed if, and only if the match status +\fIOK\fR indicates a success. +In the case of a failure \fBisv_clear\fR should be called. +.TP +\fBisv_nonterminal_reduce\fR \fInt\fR +This instruction creates a nonterminal AST node for the nonterminal +\fInt\fR and makes it the semantic value \fISV\fR. +.sp +All entries on the AST stack \fIAS\fR above the marker found in the +top entry of the AST Marker stack \fIMS\fR become children of the new +node, with the entry at the stack top becoming the rightmost child. If +the AST Marker stack \fIMS\fR is empty the whole stack is used. The +AST marker stack \fIMS\fR is left unchanged. +.sp +This instruction should be executed if, and only if the match status +\fIOK\fR indicates a success. +In the case of a failure \fBisv_clear\fR should be called. +.PP +.PP +.SS "AST STACK HANDLING" +The instructions in this section manipulate the AST stack \fIAS\fR, +and the AST Marker stack \fIMS\fR. +.TP +\fBias_push\fR +This instruction pushes the semantic value \fISV\fR on the AST stack +\fIAS\fR. +.TP +\fBias_mark\fR +This instruction pushes a marker for the current state of the AST +stack \fIAS\fR on the AST Marker stack \fIMS\fR. +.TP +\fBias_mrewind\fR +This instruction pops an entry from the AST Marker stack \fIMS\fR and +then proceeds to pop entries from the AST stack \fIAS\fR until the +state represented by the popped marker has been reached again. +Nothing is done if the AST stack \fIAS\fR is already smaller than +indicated by the popped marker. +.TP +\fBias_mpop\fR +This instruction pops an entry from the AST Marker stack \fIMS\fR and +discards it. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_me\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +grammar, parsing, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_peg/peg.n Index: embedded/man/files/modules/grammar_peg/peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_peg/peg.n @@ -0,0 +1,819 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_peg/peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::peg" n 0.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::peg \- Create and manipulate parsing expression grammars +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit \fR +.sp +package require \fBgrammar::peg ?0.1?\fR +.sp +\fB::grammar::peg\fR \fIpegName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR? +.sp +\fIpegName\fR \fBdestroy\fR +.sp +\fIpegName\fR \fBclear\fR +.sp +\fIpegName\fR \fB=\fR \fIsrcPEG\fR +.sp +\fIpegName\fR \fB-->\fR \fIdstPEG\fR +.sp +\fIpegName\fR \fBserialize\fR +.sp +\fIpegName\fR \fBdeserialize\fR \fIserialization\fR +.sp +\fIpegName\fR \fBis valid\fR +.sp +\fIpegName\fR \fBstart\fR ?\fIpe\fR? +.sp +\fIpegName\fR \fBnonterminals\fR +.sp +\fIpegName\fR \fBnonterminal add\fR \fInt\fR \fIpe\fR +.sp +\fIpegName\fR \fBnonterminal delete\fR \fInt1\fR ?\fInt2\fR ...? +.sp +\fIpegName\fR \fBnonterminal exists\fR \fInt\fR +.sp +\fIpegName\fR \fBnonterminal rename\fR \fInt\fR \fIntnew\fR +.sp +\fIpegName\fR \fBnonterminal mode\fR \fInt\fR ?\fImode\fR? +.sp +\fIpegName\fR \fBnonterminal rule\fR \fInt\fR +.sp +\fIpegName\fR \fBunknown nonterminals\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a container class for +\fIparsing expression grammars\fR (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 \fBgrammar::mengine\fR and +\fBgrammar::peg::interpreter\fR. 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. +.SS "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 +\fBPARSING EXPRESSION GRAMMARS\fR. +.PP +In short, we have \fIterminal symbols\fR, which are the most basic +building blocks for \fIsentences\fR, and \fInonterminal symbols\fR +with associated \fIparsing expressions\fR, 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 \fIsymbols\fR. +.PP +Here the set of \fIterminal symbols\fR 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. +.PP +A pair of \fInonterminal\fR and \fIparsing expression\fR is also +called a \fIgrammatical rule\fR, or \fIrule\fR 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). +.PP +The \fIstart expression\fR of a grammar is a parsing expression +from which all the sentences contained in the language specified by +the grammar are \fIderived\fR. +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 +.PP +.CS + + + 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 + +.CE +.PP +A derived expression containing only terminal symbols is a +\fIsentence\fR. The set of all sentences which can be derived from +the start expression is the \fIlanguage\fR of the grammar. +.PP +Some definitions for nonterminals and expressions: +.IP [1] +A nonterminal A is called \fIreachable\fR if it is possible to derive +a parsing expression from the start expression which contains A. +.IP [2] +A nonterminal A is called \fIuseful\fR if it is possible to derive a +sentence from it. +.IP [3] +A nonterminal A is called \fIrecursive\fR if it is possible to derive +a parsing expression from it which contains A, again. +.IP [4] +The \fIFIRST set\fR 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 +\fIleft-recursive\fR. +.IP [5] +The \fILAST set\fR 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 +\fIright-recursive\fR. +.IP [6] +The \fIFOLLOW set\fR of a nonterminal A contains all the symbols which +can occur after A in a parsing expression derived from the start +expression. +.IP [7] +A nonterminal (or parsing expression) is called \fInullable\fR if the +empty sentence can be derived from it. +.PP +.PP +And based on the above definitions for grammars: +.IP [1] +A grammar G is \fIrecursive\fR if and only if it contains a nonterminal +A which is recursive. The terms \fIleft-\fR and \fIright-recursive\fR, +and \fIuseful\fR are analogously defined. +.IP [2] +A grammar is \fIminimal\fR if it contains only \fIreachable\fR and +\fIuseful\fR nonterminals. +.IP [3] +A grammar is \fIwellformed\fR if it is not left-recursive. Such +grammars are also \fIcomplete\fR, 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. +.IP [4] +As we wish to allow ourselves to build a grammar incrementally in a +container object we will encounter stages where the RHS of one or more +rules reference symbols which are not yet known to the container. Such +a grammar we call \fIinvalid\fR. +We cannot use the term \fIincomplete\fR as this term is already +taken, see the last item. +.PP +.PP +.SS "CONTAINER CLASS API" +The package exports the API described here. +.TP +\fB::grammar::peg\fR \fIpegName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR? +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 \fBCONTAINER OBJECT API\fR. It may be used to invoke +various operations on the container and the grammar within. +.sp +The new container, i.e. grammar will be empty if no \fIsrc\fR is +specified. Otherwise it will contain a copy of the grammar contained +in the \fIsrc\fR. +The \fIsrc\fR has to be a container object reference for all operators +except \fBdeserialize\fR. +The \fBdeserialize\fR operator requires \fIsrc\fR to be the +serialization of a parsing expression grammar instead. +.sp +An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is \fIvalid\fR, but not +\fIuseful\fR. +.PP +.SS "CONTAINER OBJECT API" +.PP +All grammar container objects provide the following methods for the +manipulation of their contents: +.TP +\fIpegName\fR \fBdestroy\fR +Destroys the grammar, including its storage space and associated +command. +.TP +\fIpegName\fR \fBclear\fR +Clears out the definition of the grammar contained in \fIpegName\fR, +but does \fInot\fR destroy the object. +.TP +\fIpegName\fR \fB=\fR \fIsrcPEG\fR +Assigns the contents of the grammar contained in \fIsrcPEG\fR to +\fIpegName\fR, overwriting any existing definition. +This is the assignment operator for grammars. It copies the grammar +contained in the grammar object \fIsrcPEG\fR over the grammar +definition in \fIpegName\fR. The old contents of \fIpegName\fR are +deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIpegName\fR \fBdeserialize\fR [\fIsrcPEG\fR \fBserialize\fR] + +.CE +.TP +\fIpegName\fR \fB-->\fR \fIdstPEG\fR +This is the reverse assignment operator for grammars. It copies the +automation contained in the object \fIpegName\fR over the grammar +definition in the object \fIdstPEG\fR. +The old contents of \fIdstPEG\fR are deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdstPEG\fR \fBdeserialize\fR [\fIpegName\fR \fBserialize\fR] + +.CE +.TP +\fIpegName\fR \fBserialize\fR +This method serializes the grammar stored in \fIpegName\fR. In other +words it returns a tcl \fIvalue\fR 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. +.sp +The result of this method has to be semantically identical over all +implementations of the \fBgrammar::peg\fR interface. This is what +will enable us to copy grammars between different implementations of +the same interface. +.sp +The result is a list of four elements with the following structure: +.RS +.IP [1] +The constant string \fBgrammar::peg\fR. +.IP [2] +A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values are the parsing expressions describing +their sentennial structure. +.IP [3] +A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values hints to a matcher regarding the semantic +values produced by the symbol. +.IP [4] +The last item is a parsing expression, the \fIstart expression\fR +of the grammar. +.RE +.sp +Assuming the following PEG for simple mathematical expressions +.sp +.CS + + + 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 + +.CE +.sp +a possible serialization is +.sp +.CS + + + grammar::peg \\\\ + {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\\\ + Factor {x Term {* {x AddOp Term}}} \\\\ + Term Number \\\\ + MulOp {/ * /} \\\\ + AddOp {/ + -} \\\\ + Number {x {? Sign} {+ Digit}} \\\\ + Sign {/ + -} \\\\ + Digit {/ 0 1 2 3 4 5 6 7 8 9} \\\\ + } \\\\ + {Expression value Factor value \\\\ + Term value MulOp value \\\\ + AddOp value Number value \\\\ + Sign value Digit value \\\\ + } + Expression + +.CE +.sp +A possible one, because the order of the nonterminals in the +dictionary is not relevant. +.TP +\fIpegName\fR \fBdeserialize\fR \fIserialization\fR +This is the complement to \fBserialize\fR. It replaces the grammar +definition in \fIpegName\fR with the grammar described by the +\fIserialization\fR value. The old contents of \fIpegName\fR are +deleted by this operation. +.TP +\fIpegName\fR \fBis valid\fR +A predicate. It tests whether the PEG in \fIpegName\fR is \fIvalid\fR. +See section \fBTERMS & CONCEPTS\fR for the definition of this +grammar property. +The result is a boolean value. It will be set to \fBtrue\fR if +the PEG has the tested property, and \fBfalse\fR otherwise. +.TP +\fIpegName\fR \fBstart\fR ?\fIpe\fR? +This method defines the \fIstart expression\fR of the grammar. It +replaces the previously defined start expression with the parsing +expression \fIpe\fR. +The method fails and throws an error if \fIpe\fR does not contain a +valid parsing expression as specified in the section +\fBPARSING EXPRESSIONS\fR. In that case the existing start +expression is not changed. +The method returns the empty string as its result. +.sp +If the method is called without an argument it will return the currently +defined start expression. +.TP +\fIpegName\fR \fBnonterminals\fR +Returns the set of all nonterminal symbols known to the grammar. +.TP +\fIpegName\fR \fBnonterminal add\fR \fInt\fR \fIpe\fR +This method adds the nonterminal \fInt\fR and its associated parsing +expression \fIpe\fR to the set of nonterminal symbols and rules of the +PEG contained in the object \fIpegName\fR. +The method fails and throws an error if either the string \fInt\fR is +already known as a symbol of the grammar, or if \fIpe\fR does not +contain a valid parsing expression as specified in the section +\fBPARSING EXPRESSIONS\fR. In that case the current set of +nonterminal symbols and rules is not changed. +The method returns the empty string as its result. +.TP +\fIpegName\fR \fBnonterminal delete\fR \fInt1\fR ?\fInt2\fR ...? +This method removes the named symbols \fInt1\fR, \fInt2\fR from the +set of nonterminal symbols of the PEG contained in the object +\fIpegName\fR. +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. +.sp +The stored grammar becomes invalid if the deleted nonterminals are +referenced by the RHS of still-known rules. +.TP +\fIpegName\fR \fBnonterminal exists\fR \fInt\fR +A predicate. It tests whether the nonterminal symbol \fInt\fR is known +to the PEG in \fIpegName\fR. +The result is a boolean value. It will be set to \fBtrue\fR if the +symbol \fInt\fR is known, and \fBfalse\fR otherwise. +.TP +\fIpegName\fR \fBnonterminal rename\fR \fInt\fR \fIntnew\fR +This method renames the nonterminal symbol \fInt\fR to \fIntnew\fR. +The method fails and throws an error if either \fInt\fR is not known +as a nonterminal, or if \fIntnew\fR is a known symbol. +The method returns the empty string as its result. +.TP +\fIpegName\fR \fBnonterminal mode\fR \fInt\fR ?\fImode\fR? +This mode returns or sets the semantic mode associated with the +nonterminal symbol \fInt\fR. If no \fImode\fR is specified the +current mode of the nonterminal is returned. Otherwise the current +mode is set to \fImode\fR. +The method fails and throws an error if \fInt\fR is not known as a +nonterminal. +The grammar interpreter implemented by the package +\fBgrammar::peg::interpreter\fR recognizes the +following modes: +.RS +.TP +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. +.TP +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. +.TP +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. +.TP +discard +The nonterminal has no semantic value. The ASTs generated by the RHS +are discarded (as well). +.RE +.TP +\fIpegName\fR \fBnonterminal rule\fR \fInt\fR +This method returns the parsing expression associated with the +nonterminal \fInt\fR. +The method fails and throws an error if \fInt\fR is not known as a +nonterminal. +.TP +\fIpegName\fR \fBunknown nonterminals\fR +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. +.PP +.PP +.SS "PARSING EXPRESSIONS" +.PP +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. +.PP +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBalnum\fR is an atomic parsing expression. It matches +any alphanumeric character. +.IP [3] +The string \fBalpha\fR is an atomic parsing expression. It matches +any alphabetical character. +.IP [4] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [5] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [6] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.IP [7] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [8] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [9] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [10] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [11] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [12] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [13] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.PP +.PP +Examples of parsing expressions where already shown, in the +description of the method \fBserialize\fR. +.SH "PARSING EXPRESSION GRAMMARS" +.PP +For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where +.IP \(bu +VN is a set of \fInonterminal symbols\fR, +.IP \(bu +VT is a set of \fIterminal symbols\fR, +.IP \(bu +R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and \fIe\fR a \fIparsing expression\fR. +.IP \(bu +eS is a parsing expression, the \fIstart expression\fR. +.PP +.PP +Further constraints are +.IP \(bu +The intersection of VN and VT is empty. +.IP \(bu +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. +.PP +.PP +Parsing expression are inductively defined via +.IP \(bu +The empty string (epsilon) is a parsing expression. +.IP \(bu +A terminal symbol \fIa\fR is a parsing expression. +.IP \(bu +A nonterminal symbol \fIA\fR is a parsing expression. +.IP \(bu +\fIe1\fR\fIe2\fR is a parsing expression for parsing expressions +\fIe1\fR and \fI2\fR. This is called \fIsequence\fR. +.IP \(bu +\fIe1\fR/\fIe2\fR is a parsing expression for parsing expressions +\fIe1\fR and \fI2\fR. This is called \fIordered choice\fR. +.IP \(bu +\fIe\fR* is a parsing expression for parsing expression +\fIe\fR. This is called \fIzero-or-more repetitions\fR, also known +as \fIkleene closure\fR. +.IP \(bu +\fIe\fR+ is a parsing expression for parsing expression +\fIe\fR. This is called \fIone-or-more repetitions\fR, also known +as \fIpositive kleene closure\fR. +.IP \(bu +!\fIe\fR is a parsing expression for parsing expression +\fIe1\fR. This is called a \fInot lookahead predicate\fR. +.IP \(bu +&\fIe\fR is a parsing expression for parsing expression +\fIe1\fR. This is called an \fIand lookahead predicate\fR. +.PP +.PP +.PP +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). +.PP +They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars. +.SH REFERENCES +.IP [1] +\fIThe Packrat Parsing and Parsing Expression Grammars Page\fR [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. +.IP [2] +\fIParsing Techniques - A Practical Guide \fR [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. +.IP [3] +\fICompilers and Compiler Generators\fR [http://scifac.ru.ac.za/compilers/], an online book using +CoCo/R, a generator for recursive descent parsers. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_peg\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +LL(k), TDPL, context-free languages, expression, grammar, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/grammar_peg/peg_interp.n Index: embedded/man/files/modules/grammar_peg/peg_interp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/grammar_peg/peg_interp.n @@ -0,0 +1,339 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/grammar_peg/peg_interp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "grammar::peg::interp" n 0.1.1 tcllib "Grammar operations and usage" +.BS +.SH NAME +grammar::peg::interp \- Interpreter for parsing expression grammars +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBgrammar::mengine ?0.1?\fR +.sp +package require \fBgrammar::peg::interp ?0.1.1?\fR +.sp +\fB::grammar::peg::interp::setup\fR \fIpeg\fR +.sp +\fB::grammar::peg::interp::parse\fR \fInextcmd\fR \fIerrorvar\fR \fIastvar\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +It is built on top of the virtual machine provided by the package +\fBgrammar::me::tcl\fR and directly interprets the parsing +expression grammar given to it. +In other words, the grammar is \fInot\fR pre-compiled but used as is. +.PP +The grammar to be interpreted is taken from a container object +following the interface specified by the package +\fBgrammar::peg::container\fR. Only the relevant parts +are copied into the state of this package. +.PP +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. +.PP +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. +.SH "THE INTERPRETER API" +The package exports the following API +.TP +\fB::grammar::peg::interp::setup\fR \fIpeg\fR +This command (re)initializes the interpreter. It returns the +empty string. This command has to be invoked first, before any +matching run. +.sp +Its argument \fIpeg\fR 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. +.TP +\fB::grammar::peg::interp::parse\fR \fInextcmd\fR \fIerrorvar\fR \fIastvar\fR +This command interprets the loaded grammar and tries to match it +against the stream of characters represented by the command prefix +\fInextcmd\fR. +.sp +The command prefix \fInextcmd\fR 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. +.sp +The result of the command is a boolean value indicating whether the +matching process was successful (\fBtrue\fR), or not +(\fBfalse\fR). In the case of a match failure error information will +be stored into the variable referenced by \fIerrorvar\fR. The variable +referenced by \fIastvar\fR will always contain the generated abstract +syntax tree, however in the case of an error it will be only partial +and possibly malformed. +.sp +The abstract syntax tree is represented by a nested list, as +described in section \fBAST VALUES\fR of +document \fIgrammar::me_ast\fR. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIgrammar_peg\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +LL(k), TDPL, context-free languages, expression, grammar, matching, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine +.SH CATEGORY +Grammars and finite automata +.SH COPYRIGHT +.nf +Copyright (c) 2005-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/hook/hook.n Index: embedded/man/files/modules/hook/hook.n ================================================================== --- /dev/null +++ embedded/man/files/modules/hook/hook.n @@ -0,0 +1,593 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/hook/hook.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010, by William H. Duquette +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "hook" n 0.1 tcllib "Hooks" +.BS +.SH NAME +hook \- Hooks +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBhook ?0.1?\fR +.sp +\fBhook\fR \fBbind\fR ?\fIsubject\fR? ?\fIhook\fR? ?\fIobserver\fR? ?\fIcmdPrefix\fR? +.sp +\fBhook\fR \fBcall\fR \fIsubject\fR \fIhook\fR ?\fIargs\fR...? +.sp +\fBhook\fR \fBforget\fR \fIobject\fR +.sp +\fBhook\fR \fBcget\fR \fIoption\fR +.sp +\fBhook\fR \fBconfigure\fR \fBoption\fR \fIvalue\fR ... +.sp +.BE +.SH DESCRIPTION +.PP +This package provides the \fBhook\fR ensemble command, which +implements the Subject/Observer pattern. It allows \fIsubjects\fR, +which may be \fImodules\fR, \fIobjects\fR, \fIwidgets\fR, and so +forth, to synchronously call \fIhooks\fR which may be bound to an +arbitrary number of subscribers, called \fIobservers\fR. 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. +.PP +This man page is intended to be a reference only. +.SH CONCEPTS +.SS INTRODUCTION +Tcl modules usually send notifications to other modules in two ways: +via Tk events, and via callback options like the text widget's +\fB-yscrollcommand\fR option. Tk events are available only in Tk, +and callback options require tight coupling between the modules +sending and receiving the notification. +.PP +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 \fIto which all relevant +Views subscribe.\fR 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, \fBhook\fR, +which implements just such a mechanism. +.SS BINDINGS +The \fBhook\fR command manages a collection of hook bindings. A hook +binding has four elements: +.IP [1] +A \fIsubject\fR: the name of the entity that will be calling the +hook. +.IP [2] +The \fIhook\fR itself. A hook usually reflects some occurrence in the +life of the \fIsubject\fR that other entities might care to know +about. A \fIhook\fR has a name, and may also have arguments. Hook +names are arbitrary strings. Each \fIsubject\fR must document the +names and arguments of the hooks it can call. +.IP [3] +The name of the \fIobserver\fR that wishes to receive the \fIhook\fR +from the \fIsubject\fR. +.IP [4] +A command prefix to which the \fIhook\fR arguments will be appended +when the binding is executed. +.PP +.SS "SUBJECTS AND OBSERVERS" +For convenience, this document collectively refers to subjects and +observers as \fIobjects\fR, while placing no requirements on how +these \fIobjects\fR are actually implemented. An object can be a +\fBTclOO\fR or \fBSnit\fR or \fBXOTcl\fR 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. +.PP +Subject and observer names are arbitrary strings; however, as +\fBhook\fR might be used at the package level, it's necessary to have +conventions that avoid name collisions between packages written by +different people. +.PP +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 \fB::foo\fR that creates a set of pseudo-objects and uses +\fBhook\fR 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 \fBhook\fR, these \fB::foo\fR handles +should have names like \fB::foo::1\fR, \fB::foo::2\fR, and so on. +.PP +Because object names are arbitrary strings, application code can use +whatever additional conventions are dictated by the needs of the +application. +.SH REFERENCE +Hook provides the following commands: +.TP +\fBhook\fR \fBbind\fR ?\fIsubject\fR? ?\fIhook\fR? ?\fIobserver\fR? ?\fIcmdPrefix\fR? +This subcommand is used to create, update, delete, and query hook +bindings. +.sp +Called with no arguments it returns a list of the subjects with +hooks to which observers are currently bound. +.sp +Called with one argument, a \fIsubject\fR, it returns a list of +the subject's hooks to which observers are currently bound. +.sp +Called with two arguments, a \fIsubject\fR and a \fIhook\fR, it +returns a list of the observers which are currently bound to this +\fIsubject\fR and \fIhook\fR. +.sp +Called with three arguments, a \fIsubject\fR, a \fIhook\fR, and +an \fIobserver\fR, 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. +.sp +Called with four arguments, it creates, updates, or deletes a +binding. If \fIcmdPrefix\fR is the empty string, it deletes any +existing binding for the \fIsubject\fR, \fIhook\fR, and +\fIobserver\fR; nothing is returned. Otherwise, \fIcmdPrefix\fR must +be a command prefix taking as many additional arguments as are +documented for the \fIsubject\fR and \fIhook\fR. The binding is added +or updated, and the observer is returned. +.sp +If the \fIobserver\fR is the empty string, "", it will create a +new binding using an automatically generated observer name of the form +\fB::hook::ob\fR<\fBnumber\fR>. 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. +.sp +It is possible to call \fBhook bind\fR to create or delete a +binding to a \fIsubject\fR and \fIhook\fR while in an observer binding +for that same \fIsubject\fR and \fIhook\fR. The following rules +determine what happens when +.CS + + + hook bind $s $h $o $binding + +.CE +.IP +is called during the execution of +.CS + + + hook call $s $h + +.CE +.RS +.IP [1] +No binding is ever called after it is deleted. +.IP [2] +When a binding is called, the most recently given command prefix is +always used. +.IP [3] +The set of observers whose bindings are to be called is determined +when this method begins to execute, and does not change thereafter, +except that deleted bindings are not called. +.RE +.IP +In particular: +.RS +.IP [1] +If \fB$o\fRs binding to \fB$s\fR and \fB$h\fR is deleted, and +\fB$o\fRs binding has not yet been called during this execution of +.CS + + + hook call $s $h + +.CE +.IP +it will not be called. (Note that it might already have been called; +and in all likelihood, it is probably deleting itself.) +.IP [2] +If \fB$o\fR changes the command prefix that's bound to \fB$s\fR and +\fB$h\fR, and if \fB$o\fRs binding has not yet been called during +this execution of +.CS + + + hook call $s $h + +.CE +.IP +the new binding will be called when the time comes. (But again, it is +probably \fB$o\fRs binding that is is making the change.) +.IP [3] +If a new observer is bound to \fB$s\fR and \fB$h\fR, its binding will +not be called until the next invocation of +.CS + + + hook call $s $h + +.CE +.RE +.TP +\fBhook\fR \fBcall\fR \fIsubject\fR \fIhook\fR ?\fIargs\fR...? +This command is called when the named \fIsubject\fR wishes to call the +named \fIhook\fR. 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 \fIargs\fR +to include references to entities that will be cleaned up as soon as +the hook has been called. +.sp +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. +.sp +Because the \fBhook\fR mechanism is intended to support loose +coupling, it is presumed that the \fIsubject\fR has no knowledge of +the observers, nor any expectation regarding return values. This has a +number of implications: +.RS +.IP [1] +\fBhook call\fR returns the empty string. +.IP [2] +Normal return values from observer bindings are ignored. +.IP [3] +Errors and other exceptional returns propagate normally by +default. This will rarely be what is wanted, because the subjects +usually have no knowledge of the observers and will therefore have no +particular competence at handling their errors. That makes it an +application issue, and so applications will usually want to define an +\fB-errorcommand\fR. +.RE +.IP +If the \fB-errorcommand\fR configuration option has a non-empty +value, its value will be invoked for all errors and other exceptional +returns in observer bindings. See \fBhook configure\fR, below, for +more information on configuration options. +.TP +\fBhook\fR \fBforget\fR \fIobject\fR +This command deletes any existing bindings in which the named +\fIobject\fR appears as either the \fIsubject\fR or the +\fIobserver\fR. +Bindings deleted by this method will never be called again. In +particular, +.RS +.IP [1] +If an observer is forgotten during a call to \fBhook call\fR, any +uncalled binding it might have had to the relevant subject and hook +will \fInot\fR be called subsequently. +.IP [2] +If a subject \fB$s\fR is forgotten during a call to +.CS + +hook call $s $h +.CE +.IP +then \fBhook call\fR will return as soon as the current binding +returns. No further bindings will be called. +.RE +.TP +\fBhook\fR \fBcget\fR \fIoption\fR +This command returns the value of one of the \fBhook\fR command's +configuration options. +.TP +\fBhook\fR \fBconfigure\fR \fBoption\fR \fIvalue\fR ... +This command sets the value of one or more of the \fBhook\fR command's +configuration options: +.RS +.TP +\fB-errorcommand\fR \fIcmdPrefix\fR +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: +.RS +.IP [1] +a 4-element list {subject hook arglist observer}, +.IP [2] +the result string, and +.IP [3] +the return options dictionary. +.RE +.IP +Given this information, the \fB-errorcommand\fR can choose to log +the error, call \fBinterp bgerror\fR, delete the errant binding +(thus preventing the error from arising a second time) and so forth. +.TP +\fB-tracecommand\fR \fIcmdPrefix\fR +The option's value should be a command prefix taking four +arguments: +.RS +.IP [1] +a \fIsubject\fR, +.IP [2] +a \fIhook\fR, +.IP [3] +a list of the hook's argument values, and +.IP [4] +a list of \fIobjects\fR the hook was called for. +.RE +.IP +The command will be called for each hook that is called. This allows +the application to trace hook execution for debugging purposes. +.RE +.PP +.SH EXAMPLE +The \fB::model\fR module calls the <Update> hook in response to +commands that change the model's data: +.CS + + + hook call ::model <Update> + +.CE +The \fB.view\fR megawidget displays the model state, and needs to +know about model updates. Consequently, it subscribes to the ::model's +<Update> hook. +.CS + + + hook bind ::model <Update> .view [list .view ModelUpdate] + +.CE +When the \fB::model\fR calls the hook, the \fB.view\fRs +ModelUpdate subcommand will be called. +.PP +Later the \fB.view\fR megawidget is destroyed. In its destructor, +it tells the \fIhook\fR that it no longer exists: +.CS + + + hook forget .view + +.CE +All bindings involving \fB.view\fR are deleted. +.SH CREDITS +Hook has been designed and implemented by William H. Duquette. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIhook\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +uevent(n) +.SH KEYWORDS +callback, event, hook, observer, producer, publisher, subject, subscriber, uevent +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2010, by William H. Duquette + +.fi ADDED embedded/man/files/modules/html/html.n Index: embedded/man/files/modules/html/html.n ================================================================== --- /dev/null +++ embedded/man/files/modules/html/html.n @@ -0,0 +1,691 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/html/html.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "html" n 1.4 tcllib "HTML Generation" +.BS +.SH NAME +html \- Procedures to generate HTML structures +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBhtml ?1.4?\fR +.sp +\fB::html::author\fR \fIauthor\fR +.sp +\fB::html::bodyTag\fR \fIargs\fR +.sp +\fB::html::cell\fR \fIparam value\fR ?\fItag\fR? +.sp +\fB::html::checkbox\fR \fIname value\fR +.sp +\fB::html::checkSet\fR \fIkey sep list\fR +.sp +\fB::html::checkValue\fR \fIname\fR ?\fIvalue\fR? +.sp +\fB::html::closeTag\fR +.sp +\fB::html::default\fR \fIkey\fR ?\fIparam\fR? +.sp +\fB::html::description\fR \fIdescription\fR +.sp +\fB::html::end\fR +.sp +\fB::html::eval\fR \fIarg\fR ?\fIargs\fR? +.sp +\fB::html::extractParam\fR \fIparam key\fR ?\fIvarName\fR? +.sp +\fB::html::font\fR \fIargs\fR +.sp +\fB::html::for\fR \fIstart test next body\fR +.sp +\fB::html::foreach\fR \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR +.sp +\fB::html::formValue\fR \fIname\fR ?\fIdefvalue\fR? +.sp +\fB::html::getFormInfo\fR \fIargs\fR +.sp +\fB::html::getTitle\fR +.sp +\fB::html::h\fR \fIlevel string\fR ?\fIparam\fR? +.sp +\fB::html::h1\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::h2\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::h3\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::h4\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::h5\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::h6\fR \fIstring\fR ?\fIparam\fR? +.sp +\fB::html::hdrRow\fR \fIargs\fR +.sp +\fB::html::head\fR \fItitle\fR +.sp +\fB::html::headTag\fR \fIstring\fR +.sp +\fB::html::html_entities\fR \fIstring\fR +.sp +\fB::html::if\fR \fIexpr1 body1\fR ?\fBelseif\fR \fIexpr2 body2 ...\fR? ?\fBelse\fR \fIbodyN\fR? +.sp +\fB::html::init\fR ?\fIlist\fR? +.sp +\fB::html::keywords\fR \fIargs\fR +.sp +\fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR? +.sp +\fB::html::meta\fR \fIargs\fR +.sp +\fB::html::minorList\fR \fIlist\fR ?\fIordered\fR? +.sp +\fB::html::minorMenu\fR \fIlist\fR ?\fIsep\fR? +.sp +\fB::html::nl2br\fR \fIstring\fR +.sp +\fB::html::openTag\fR \fItag\fR ?\fIparam\fR? +.sp +\fB::html::paramRow\fR \fIlist\fR ?\fIrparam\fR? ?\fIcparam\fR? +.sp +\fB::html::passwordInput\fR ?\fIname\fR? +.sp +\fB::html::passwordInputRow\fR \fIlabel\fR ?\fIname\fR? +.sp +\fB::html::quoteFormValue\fR \fIvalue\fR +.sp +\fB::html::radioSet\fR \fIkey sep list\fR +.sp +\fB::html::radioValue\fR \fIname value\fR +.sp +\fB::html::refresh\fR \fIseconds url\fR +.sp +\fB::html::row\fR \fIargs\fR +.sp +\fB::html::select\fR \fIname param choices\fR ?\fIcurrent\fR? +.sp +\fB::html::selectPlain\fR \fIname param choices\fR ?\fIcurrent\fR? +.sp +\fB::html::set\fR \fIvar val\fR +.sp +\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? +.sp +\fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR? +.sp +\fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR? +.sp +\fB::html::textarea\fR \fIname\fR ?\fIparam\fR? ?\fIcurrent\fR? +.sp +\fB::html::textInput\fR \fIname value args\fR +.sp +\fB::html::textInputRow\fR \fIlabel name value args\fR +.sp +\fB::html::varEmpty\fR \fIname\fR +.sp +\fB::html::while\fR \fItest body\fR +.sp +.BE +.SH DESCRIPTION +.PP +The package \fBhtml\fR provides commands that generate HTML. +These commands typically return an HTML string as their result. In +particular, they do not output their result to \fBstdout\fR. +.PP +The command \fB::html::init\fR should be called early to initialize +the module. You can also use this procedure to define default values +for HTML tag parameters. +.TP +\fB::html::author\fR \fIauthor\fR +\fISide effect only\fR. Call this before \fB::html::head\fR to +define an author for the page. The author is noted in a comment in +the HEAD section. +.TP +\fB::html::bodyTag\fR \fIargs\fR +Generate a \fIbody\fR tag. The tag parameters are taken from \fIargs\fR or +from the body.* attributes define with \fB::html::init\fR. +.TP +\fB::html::cell\fR \fIparam value\fR ?\fItag\fR? +Generate a \fItd\fR (or \fIth\fR) tag, a value, and a closing +\fItd\fR (or \fIth\fR) tag. The +tag parameters come from \fIparam\fR or TD.* attributes defined with +\fB::html::init\fR. This uses \fB::html::font\fR to insert a standard +\fIfont\fR tag into the table cell. The \fItag\fR argument defaults to "td". +.TP +\fB::html::checkbox\fR \fIname value\fR +Generate a \fIcheckbox\fR form element with the specified name and value. +This uses \fB::html::checkValue\fR. +.TP +\fB::html::checkSet\fR \fIkey sep list\fR +Generate a set of \fIcheckbox\fR form elements and associated labels. The +\fIlist\fR should contain an alternating list of labels and values. +This uses \fB::html::checkbox\fR. All the \fIcheckbox\fR buttons share the +same \fIkey\fR for their name. The \fIsep\fR is text used to separate +the elements. +.TP +\fB::html::checkValue\fR \fIname\fR ?\fIvalue\fR? +Generate the "name=\fIname\fR value=\fIvalue\fR for a \fIcheckbox\fR form +element. If the CGI variable \fIname\fR has the value \fIvalue\fR, +then SELECTED is added to the return value. \fIvalue\fR defaults to +"1". +.TP +\fB::html::closeTag\fR +Pop a tag off the stack created by \fB::html::openTag\fR and generate +the corresponding close tag (e.g., </body>). +.TP +\fB::html::default\fR \fIkey\fR ?\fIparam\fR? +This procedure is used by \fB::html::tagParam\fR to generate the name, +value list of parameters for a tag. The \fB::html::default\fR +procedure is used to generate default values for those items not +already in \fIparam\fR. If the value identified by \fIkey\fR matches +a value in \fIparam\fR then this procedure returns the empty string. +Otherwise, it returns a "parameter=value" string for a form element +identified by \fIkey\fR. The \fIkey\fR has the form "tag.parameter" +(e.g., body.bgcolor). Use \fB::html::init\fR to register default +values. \fIparam\fR defaults to the empty string. +.TP +\fB::html::description\fR \fIdescription\fR +\fISide effect only\fR. Call this before \fB::html::head\fR to +define a description \fImeta\fR tag for the page. This tag is generated +later in the call to \fB::html::head\fR. +.TP +\fB::html::end\fR +Pop all open tags from the stack and generate the corresponding close +HTML tags, (e.g., </body></html>). +.TP +\fB::html::eval\fR \fIarg\fR ?\fIargs\fR? +This procedure is similar to the built-in Tcl \fBeval\fR command. The +only difference is that it returns "" so it can be called from an HTML +template file without appending unwanted results. +.TP +\fB::html::extractParam\fR \fIparam key\fR ?\fIvarName\fR? +This is a parsing procedure that extracts the value of \fIkey\fR from +\fIparam\fR, which is a HTML-style "name=quotedvalue" list. +\fIvarName\fR 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 \fIparam\fR, otherwise it returns 0. If the +\fIvarName\fR is not specified, then \fIkey\fR is used as the variable +name. +.TP +\fB::html::font\fR \fIargs\fR +Generate a standard \fIfont\fR tag. The parameters to the tag are taken +from \fIargs\fR and the HTML defaults defined with \fB::html::init\fR. +.TP +\fB::html::for\fR \fIstart test next body\fR +This procedure is similar to the built-in Tcl \fBfor\fR control +structure. Rather than evaluating the body, it returns the subst'ed +\fIbody\fR. Each iteration of the loop causes another string to be +concatenated to the result value. +.TP +\fB::html::foreach\fR \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR +This procedure is similar to the built-in Tcl \fBforeach\fR control +structure. Rather than evaluating the body, it returns the subst'ed +\fIbody\fR. Each iteration of the loop causes another string to be +concatenated to the result value. +.TP +\fB::html::formValue\fR \fIname\fR ?\fIdefvalue\fR? +Return a name and value pair, where the value is initialized from +existing CGI data, if any. The result has this form: +.sp +.CS + + + name="fred" value="freds value" + +.CE +.TP +\fB::html::getFormInfo\fR \fIargs\fR +Generate hidden fields to capture form values. If \fIargs\fR is +empty, then hidden fields are generated for all CGI values. Otherwise +args is a list of string match patterns for form element names. +.TP +\fB::html::getTitle\fR +Return the title string, with out the surrounding \fItitle\fR tag, +set with a previous call to \fB::html::title\fR. +.TP +\fB::html::h\fR \fIlevel string\fR ?\fIparam\fR? +Generate a heading (e.g., \fIh\fBlevel\fR\fR) tag. The \fIstring\fR is nested in the +heading, and \fIparam\fR is used for the tag parameters. +.TP +\fB::html::h1\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh1\fR tag. See \fB::html::h\fR. +.TP +\fB::html::h2\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh2\fR tag. See \fB::html::h\fR. +.TP +\fB::html::h3\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh3\fR tag. See \fB::html::h\fR. +.TP +\fB::html::h4\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh4\fR tag. See \fB::html::h\fR. +.TP +\fB::html::h5\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh5\fR tag. See \fB::html::h\fR. +.TP +\fB::html::h6\fR \fIstring\fR ?\fIparam\fR? +Generate an \fIh6\fR tag. See \fB::html::h\fR. +.TP +\fB::html::hdrRow\fR \fIargs\fR +Generate a table row, including \fItr\fR and \fIth\fR tags. +Each value in \fIargs\fR is place into its own table cell. +This uses \fB::html::cell\fR. +.TP +\fB::html::head\fR \fItitle\fR +Generate the \fIhead\fR section that includes the page \fItitle\fR. +If previous calls have been made to +\fB::html::author\fR, +\fB::html::keywords\fR, +\fB::html::description\fR, +or +\fB::html::meta\fR +then additional tags are inserted into the \fIhead\fR section. +This leaves an open \fIhtml\fR tag pushed on the stack with +\fB::html::openTag\fR. +.TP +\fB::html::headTag\fR \fIstring\fR +Save a tag for inclusion in the \fIhead\fR section generated by +\fB::html::head\fR. The \fIstring\fR is everything in the tag except +the enclosing angle brackets, < >. +.TP +\fB::html::html_entities\fR \fIstring\fR +This command replaces all special characters in the \fIstring\fR with +their HTML entities and returns the modified text. +.TP +\fB::html::if\fR \fIexpr1 body1\fR ?\fBelseif\fR \fIexpr2 body2 ...\fR? ?\fBelse\fR \fIbodyN\fR? +This procedure is similar to the built-in Tcl \fBif\fR control +structure. Rather than evaluating the body of the branch that is +taken, it returns the subst'ed \fIbody\fR. Note that the syntax is +slightly more restrictive than that of the built-in Tcl \fBif\fR +control structure. +.TP +\fB::html::init\fR ?\fIlist\fR? +\fB::html::init\fR 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 \fIbody\fR tag. +.TP +\fB::html::keywords\fR \fIargs\fR +\fISide effect only\fR. Call this before \fB::html::head\fR to +define a keyword \fImeta\fR tag for the page. The \fImeta\fR tag +is included in the result of \fB::html::head\fR. +.TP +\fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR? +Generate a hypertext link to a mailto: URL. +.TP +\fB::html::meta\fR \fIargs\fR +\fISide effect only\fR. Call this before \fB::html::head\fR to +define a \fImeta\fR tag for the page. The \fIargs\fR is a Tcl-style name, +value list that is used for the name= and value= parameters for the +\fImeta\fR tag. The \fImeta\fR tag is included in the result of +\fB::html::head\fR. +.TP +\fB::html::minorList\fR \fIlist\fR ?\fIordered\fR? +Generate an ordered or unordered list of links. The \fIlist\fR is a +Tcl-style name, value list of labels and urls for the links. +\fIordered\fR is a boolean used to choose between an ordered or +unordered list. It defaults to \fBfalse\fR. +.TP +\fB::html::minorMenu\fR \fIlist\fR ?\fIsep\fR? +Generate a series of hypertext links. The \fIlist\fR is a Tcl-style +name, value list of labels and urls for the links. The \fIsep\fR is +the text to put between each link. It defaults to " | ". +.TP +\fB::html::nl2br\fR \fIstring\fR +This command replaces all line-endings in the \fIstring\fR with a +\fIbr\fR tag and returns the modified text. +.TP +\fB::html::openTag\fR \fItag\fR ?\fIparam\fR? +Push \fItag\fR onto a stack and generate the opening tag for +\fItag\fR. Use \fB::html::closeTag\fR 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 +"\fBkey\fR=\fBvalue\fR". +.TP +\fB::html::paramRow\fR \fIlist\fR ?\fIrparam\fR? ?\fIcparam\fR? +Generate a table row, including \fItr\fR and \fItd\fR tags. Each value in +\fIlist\fR is placed into its own table cell. This uses +\fB::html::cell\fR. The value of \fIrparam\fR is used as parameter for +the \fItr\fR tag. The value of \fIcparam\fR is passed to \fB::html::cell\fR +as parameter for the \fItd\fR tags. +.TP +\fB::html::passwordInput\fR ?\fIname\fR? +Generate an \fIinput\fR tag of type \fIpassword\fR. The \fIname\fR defaults to +"password". +.TP +\fB::html::passwordInputRow\fR \fIlabel\fR ?\fIname\fR? +Format a table row containing a label and an \fIinput\fR tag of type +\fIpassword\fR. The \fIname\fR defaults to "password". +.TP +\fB::html::quoteFormValue\fR \fIvalue\fR +Quote special characters in \fIvalue\fR by replacing them with HTML +entities for quotes, ampersand, and angle brackets. +.TP +\fB::html::radioSet\fR \fIkey sep list\fR +Generate a set of \fIinput\fR tags of type \fIradio\fR and an associated text +label. All the radio buttons share the same \fIkey\fR for their name. +The \fIsep\fR is text used to separate the elements. The \fIlist\fR +is a Tcl-style label, value list. +.TP +\fB::html::radioValue\fR \fIname value\fR +Generate the "name=\fIname\fR value=\fIvalue\fR for a \fIradio\fR form +element. If the CGI variable \fIname\fR has the value \fIvalue\fR, +then SELECTED is added to the return value. +.TP +\fB::html::refresh\fR \fIseconds url\fR +Set up a refresh \fImeta\fR tag. Call this before \fB::html::head\fR and the +HEAD section will contain a \fImeta\fR tag that causes the document to +refresh in \fIseconds\fR seconds. The \fIurl\fR is optional. If +specified, it specifies a new page to load after the refresh interval. +.TP +\fB::html::row\fR \fIargs\fR +Generate a table row, including \fItr\fR and \fItd\fR tags. Each value in +\fIargs\fR is place into its own table cell. This uses +\fB::html::cell\fR. Ignores any default information set up via +\fB::html::init\fR. +.TP +\fB::html::select\fR \fIname param choices\fR ?\fIcurrent\fR? +Generate a \fIselect\fR form element and nested \fIoption\fR tags. The \fIname\fR +and \fIparam\fR are used to generate the \fIselect\fR tag. The \fIchoices\fR +list is a Tcl-style name, value list. +.TP +\fB::html::selectPlain\fR \fIname param choices\fR ?\fIcurrent\fR? +Like \fB::html::select\fR except that \fIchoices\fR is a Tcl list of +values used for the \fIoption\fR tags. The label and the value for each +\fIoption\fR are the same. +.TP +\fB::html::set\fR \fIvar val\fR +This procedure is similar to the built-in Tcl \fBset\fR command. The +main difference is that it returns "" so it can be called from an HTML +template file without appending unwanted results. The other +difference is that it must take two arguments. +.TP +\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? +Generate an \fIinput\fR tag of type \fIsubmit\fR. \fIname\fR defaults to "submit". +.TP +\fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR? +Generate a two-column \fItable\fR and nested rows to display a Tcl array. The +table gets a heading that matches the array name, and each generated row +contains a name, value pair. The array names are sorted (\fBlsort\fR without +special options). The argument \fIparam\fR is for the \fItable\fR tag and has +to contain a pre-formatted string. The \fIpat\fR is a \fBstring match\fR +pattern used to select the array elements to show in the table. It defaults to +\fB*\fR, i.e. the whole array is shown. +.TP +\fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR? +Generate a two-column \fItable\fR and nested rows to display \fIquerylist\fR, +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 \fIparam\fR is for the \fItable\fR tag and has to contain a +pre-formatted string. +.TP +\fB::html::textarea\fR \fIname\fR ?\fIparam\fR? ?\fIcurrent\fR? +Generate a \fItextarea\fR tag wrapped around its current values. +.TP +\fB::html::textInput\fR \fIname value args\fR +Generate an \fIinput\fR form tag with type \fItext\fR. This uses +\fB::html::formValue\fR. The args is any additional tag attributes +you want to put into the \fIinput\fR tag. +.TP +\fB::html::textInputRow\fR \fIlabel name value args\fR +Generate an \fIinput\fR form tag with type \fItext\fR formatted into a table row +with an associated label. The args is any additional tag attributes +you want to put into the \fIinput\fR tag. +.TP +\fB::html::varEmpty\fR \fIname\fR +This returns 1 if the named variable either does not exist or has the +empty string for its value. +.TP +\fB::html::while\fR \fItest body\fR +This procedure is similar to the built-in Tcl \fBwhile\fR control +structure. Rather than evaluating the body, it returns the subst'ed +\fIbody\fR. Each iteration of the loop causes another string to be +concatenated to the result value. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIhtml\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +htmlparse, ncgi +.SH KEYWORDS +checkbox, checkbutton, form, html, radiobutton, table +.SH CATEGORY +CGI programming ADDED embedded/man/files/modules/htmlparse/htmlparse.n Index: embedded/man/files/modules/htmlparse/htmlparse.n ================================================================== --- /dev/null +++ embedded/man/files/modules/htmlparse/htmlparse.n @@ -0,0 +1,470 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/htmlparse/htmlparse.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "htmlparse" n 1.2.1 tcllib "HTML Parser" +.BS +.SH NAME +htmlparse \- Procedures to parse HTML strings +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::stack 1.3\fR +.sp +package require \fBcmdline 1.1\fR +.sp +package require \fBhtmlparse ?1.2.1?\fR +.sp +\fB::htmlparse::parse\fR ?-cmd \fIcmd\fR? ?-vroot \fItag\fR? ?-split \fIn\fR? ?-incvar \fIvar\fR? ?-queue \fIq\fR? \fIhtml\fR +.sp +\fB::htmlparse::debugCallback\fR ?\fIclientdata\fR? \fItag slash param textBehindTheTag\fR +.sp +\fB::htmlparse::mapEscapes\fR \fIhtml\fR +.sp +\fB::htmlparse::2tree\fR \fIhtml tree\fR +.sp +\fB::htmlparse::removeVisualFluff\fR \fItree\fR +.sp +\fB::htmlparse::removeFormDefs\fR \fItree\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBhtmlparse\fR package provides commands that allow libraries +and applications to parse HTML in a string into a representation of +their choice. +.PP +The following commands are available: +.TP +\fB::htmlparse::parse\fR ?-cmd \fIcmd\fR? ?-vroot \fItag\fR? ?-split \fIn\fR? ?-incvar \fIvar\fR? ?-queue \fIq\fR? \fIhtml\fR +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, \fB::htmlparse::mapEscapes\fR, to aid in +the handling of the latter. The parser \fIdoes\fR ignore leading +DOCTYPE declarations and all valid HTML comments it encounters. +.sp +All information beyond the HTML string itself is specified via +options, these are explained below. +.sp +To help understand the options, some more background information about +the parser. +.sp +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 \fI-incvar\fR 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. +.sp +Another feature of the parser are its two possible modes of +operation. The normal mode is activated if the option \fI-queue\fR is +not present on the command line invoking the parser. If it is present, +the parser will go into the incremental mode instead. +.sp +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. +.sp +\fINote\fR: 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. +.sp +In both modes the parser will return an empty string to the caller. +.sp +The \fI-split\fR 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. +.sp +The option \fI-vroot\fR 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: +.RS +.TP +\fB-cmd\fR \fIcmd\fR +The command prefix to invoke for every tag in the HTML +string. Defaults to \fI::htmlparse::debugCallback\fR. +.TP +\fB-vroot\fR \fItag\fR +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 +\fIhmstart\fR. +.TP +\fB-split\fR \fIn\fR +The size of the groups produced by an incremental mode parser. Ignored +when in normal mode. Defaults to 10. Values <= 0 are not allowed. +.TP +\fB-incvar\fR \fIvar\fR +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'. +.RE +.RS +.sp +.TP +\fIInterface to the command prefix\fR +In normal mode the parser will invoke the command prefix with four +arguments appended. See \fB::htmlparse::debugCallback\fR for a +description. +.sp +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 (\fB@win@\fR) 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. +.RE +.TP +\fB::htmlparse::debugCallback\fR ?\fIclientdata\fR? \fItag slash param textBehindTheTag\fR +This command is the standard callback used by the parser in +\fB::htmlparse::parse\fR 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. +.sp +The first argument, \fIclientdata\fR, 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. +.sp +The second argument, \fItag\fR, contains the name of the tag which is +currently processed by the parser. +.sp +The third argument, \fIslash\fR, 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). +.sp +The fourth argument, \fIparam\fR, contains the un-interpreted list of +parameters to the tag. +.sp +The fifth and last argument, \fItextBehindTheTag\fR, contains the text +found by the parser behind the tag named in \fItag\fR. +.TP +\fB::htmlparse::mapEscapes\fR \fIhtml\fR +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. +.TP +\fB::htmlparse::2tree\fR \fIhtml tree\fR +This command is a wrapper around \fB::htmlparse::parse\fR which takes +an HTML string (in \fIhtml\fR) 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 (\fItree\fR). The command +does \fBnot\fR 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. +.sp +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. +.sp +Each node in the generated tree represent one tag in the input. The +name of the tag is stored in the attribute \fItype\fR of the +node. Any html attributes coming with the tag are stored unmodified in +the attribute \fIdata\fR of the tag. In other words, the command does +\fInot\fR parse html attributes into their names and values. +.sp +If a tag contains text its node will have children of type +\fIPCDATA\fR containing this text. The text will be stored in the +attribute \fIdata\fR of these children. +.TP +\fB::htmlparse::removeVisualFluff\fR \fItree\fR +This command walks a tree as generated by \fB::htmlparse::2tree\fR 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. +.TP +\fB::htmlparse::removeFormDefs\fR \fItree\fR +Like \fB::htmlparse::removeVisualFluff\fR this command is here to cut +down on the size of the tree as generated by +\fB::htmlparse::2tree\fR. It removes all nodes representing forms and +form elements. Its only argument is the name of the tree to cut down. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIhtmlparse\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +struct::tree +.SH KEYWORDS +html, parsing, queue, tree +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/http/autoproxy.n Index: embedded/man/files/modules/http/autoproxy.n ================================================================== --- /dev/null +++ embedded/man/files/modules/http/autoproxy.n @@ -0,0 +1,433 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/http/autoproxy.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "autoproxy" n 1.5.3 tcllib "HTTP protocol helper modules" +.BS +.SH NAME +autoproxy \- Automatic HTTP proxy usage and authentication +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBhttp ?2.0?\fR +.sp +package require \fBautoproxy ?1.5.3?\fR +.sp +\fB::autoproxy::init\fR +.sp +\fB::autoproxy::cget\fR \fI-option\fR +.sp +\fB::autoproxy::configure\fR ?-option \fIvalue\fR? +.sp +\fB::autoproxy::tls_connect\fR \fIargs\fR +.sp +\fB::autoproxy::tunnel_connect\fR \fIargs\fR +.sp +\fB::autoproxy::tls_socket\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +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. +.PP +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. +.SH COMMANDS +.TP +\fB::autoproxy::init\fR +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. +.TP +\fB::autoproxy::cget\fR \fI-option\fR +Retrieve individual package configuration options. See \fBOPTIONS\fR. +.TP +\fB::autoproxy::configure\fR ?-option \fIvalue\fR? +Configure the autoproxy package. Calling \fBconfigure\fR with no +options will return a list of all option names and values. +See \fBOPTIONS\fR. +.TP +\fB::autoproxy::tls_connect\fR \fIargs\fR +Connect to a secure socket through a proxy. HTTP proxy servers permit +the use of the CONNECT HTTP command to open a link through the proxy +to the target machine. This function hides the details. For use with +the http package see \fBtls_socket\fR. +.sp +The \fIargs\fR list may contain any of the \fBtls\fR package options but +must end with the host and port as the last two items. +.TP +\fB::autoproxy::tunnel_connect\fR \fIargs\fR +Connect to a target host throught a proxy. This uses the same CONNECT +HTTP command as the \fBtls_connect\fR but does not promote the link +security once the connection is established. +.sp +The \fIargs\fR list may contain any of the \fBtls\fR package options but +must end with the host and port as the last two items. +.sp +Note that many proxy servers will permit CONNECT calls to a limited +set of ports - typically only port 443 (the secure HTTP port). +.TP +\fB::autoproxy::tls_socket\fR \fIargs\fR +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. +.PP +.SH OPTIONS +.TP +\fB-host\fR hostname +.TP +\fB-proxy_host\fR hostname +Set the proxy hostname. This is normally set up by \fBinit\fR but may +be configured here as well. +.TP +\fB-port\fR number +.TP +\fB-proxy_port\fR number +Set the proxy port number. This is normally set up by \fBinit\fR. +e.g. \fBconfigure\fR \fB-port\fR \fI3128\fR +.TP +\fB-no_proxy\fR list +You may manipulate the \fBno_proxy\fR list that was setup by +\fBinit\fR. The value of this option is a tcl list of +strings that are matched against the http request host using the tcl +\fBstring match\fR command. Therefore glob patterns are permitted. +For instance, \fBconfigure\fR \fB-no_proxy\fR \fI*.localdomain\fR +.TP +\fB-authProc\fR procedure +This option may be used to set an application defined procedure to be +called when \fBconfigure\fR \fB-basic\fR 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. +.TP +\fB-basic\fR +Following options are for configuring the Basic authentication +scheme parameters. See \fBBasic Authentication\fR. +.PP +.SH "BASIC AUTHENTICATION" +Basic is the simplest and most commonly use HTTP proxy authentication +scheme. It is described in (1 section 11) and also in (2). It offers +no privacy whatsoever and its use should be discouraged in favour of +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. +.PP +The following options exists for this scheme: +.TP +\fB-username\fR name +The username required to authenticate with the configured proxy. +.TP +\fB-password\fR password +The password required for the username specified. +.TP +\fB-realm\fR realm +This option is not used. +.PP +.SH EXAMPLES +.PP +.CS + + +package require autoproxy +autoproxy::init +autoproxy::configure -basic -username ME -password SEKRET +set tok [http::geturl http://wiki.tcl.tk/] +http::data $tok + +.CE +.CS + + +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/] + +.CE +.SH REFERENCES +.IP [1] +Berners-Lee, T., Fielding R. and Frystyk, H. +"Hypertext Transfer Protocol -- HTTP/1.0", +RFC 1945, May 1996, +(\fIhttp://www.rfc-editor.org/rfc/rfc1945.txt\fR) +.IP [2] +Franks, J. et al. +"HTTP Authentication: Basic and Digest Access Authentication", +RFC 2617, June 1999 +(\fIhttp://www.rfc-editor.org/rfc/rfc2617.txt\fR) +.PP +.SH 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. +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIhttp :: autoproxy\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +http(n) +.SH KEYWORDS +authentication, http, proxy +.SH CATEGORY +Networking ADDED embedded/man/files/modules/ident/ident.n Index: embedded/man/files/modules/ident/ident.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ident/ident.n @@ -0,0 +1,298 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ident/ident.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Reinhard Max <max@tclers.tk> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ident" n 0.42 tcllib "Identification protocol client" +.BS +.SH NAME +ident \- Ident protocol client +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBident ?0.42?\fR +.sp +\fB::ident::query\fR \fIsocket\fR ?\fIcallback\fR? +.sp +.BE +.SH DESCRIPTION +The \fBident\fR package provides a client implementation of the ident +protocol as defined in +RFC 1413 (\fIhttp://www.rfc-editor.org/rfc/rfc1413.txt\fR). +.TP +\fB::ident::query\fR \fIsocket\fR ?\fIcallback\fR? +This command queries the ident daemon on the remote side of the given +socket, and returns the result of the query as a dictionary. +Interpreting the dictionary as list the first key will always be +\fBresp-type\fR, and can have one of the values \fBUSERID\fR, +\fBERROR\fR, and \fBFATAL\fR. These \fIresponse types\fR have +the following meanings: +.RS +.TP +USERID +This indicates a successful response. Two more keys and associated +values are returned, \fBopsys\fR, and \fBuser-id\fR. +.TP +ERROR +This means the ident server has returned an error. A second key named +\fBerror\fR is present whose value contains the \fBerror-type\fR +field from the server response. +.TP +FATAL +Fatal errors happen when no ident server is listening on the remote +side, or when the ident server gives a response that does not conform +to the RFC. A detailed error message is returned under the +\fBerror\fR key. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIident\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ident, identification, rfc 1413 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2004 Reinhard Max <max@tclers.tk> + +.fi ADDED embedded/man/files/modules/imap4/imap4.n Index: embedded/man/files/modules/imap4/imap4.n ================================================================== --- /dev/null +++ embedded/man/files/modules/imap4/imap4.n @@ -0,0 +1,729 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/imap4/imap4.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "imap4" n 0.4 tcllib "imap client" +.BS +.SH NAME +imap4 \- imap client-side tcl implementation of imap protocol +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBimap4 ?0.4?\fR +.sp +\fB::imap4::open\fR \fIhostname\fR ?\fIport\fR? +.sp +\fB::imap4::login\fR \fIchan\fR \fIuser\fR \fIpass\fR +.sp +\fB::imap4::folders\fR \fIchan\fR ?\fI-inline\fR? ?\fImboxref\fR? ?\fImboxname\fR? +.sp +\fB::imap4::select\fR \fIchan\fR ?\fImailbox\fR? +.sp +\fB::imap4::examine\fR \fIchan\fR ?\fImailbox\fR? +.sp +\fB::imap4::fetch\fR \fIchan\fR \fIrange\fR ?\fI-inline\fR? ?\fIattr ...\fR? +.sp +\fB::imap4::noop\fR \fIchan\fR +.sp +\fB::imap4::check\fR \fIchan\fR +.sp +\fB::imap4::folderinfo\fR \fIchan\fR ?\fIinfo\fR? +.sp +\fB::imap4::msginfo\fR \fIchan\fR \fImsgid\fR ?\fIinfo\fR? ?\fIdefval\fR? +.sp +\fB::imap4::mboxinfo\fR \fIchan\fR ?\fIinfo\fR? +.sp +\fB::imap4::isableto\fR \fIchan\fR ?\fIcapability\fR? +.sp +\fB::imap4::create\fR \fIchan\fR \fImailbox\fR +.sp +\fB::imap4::delete\fR \fIchan\fR \fImailbox\fR +.sp +\fB::imap4::rename\fR \fIchan\fR \fIoldname\fR \fInewname\fR +.sp +\fB::imap4::subscribe\fR \fIchan\fR \fImailbox\fR +.sp +\fB::imap4::unsubscribe\fR \fIchan\fR \fImailbox\fR +.sp +\fB::imap4::search\fR \fIchan\fR \fIexpr\fR ?\fI...\fR? +.sp +\fB::imap4::close\fR \fIchan\fR +.sp +\fB::imap4::cleanup\fR \fIchan\fR +.sp +\fB::imap4::debugmode\fR \fIchan\fR ?\fIerrormsg\fR? +.sp +\fB::imap4::store\fR \fIchan\fR \fIrange\fR \fIdata\fR \fIflaglist\fR +.sp +\fB::imap4::expunge\fR \fIchan\fR +.sp +\fB::imap4::logout\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +The \fBimap4\fR library package provides the client side of the +\fIInternet Message Access Protocol\fR (IMAP) using standard +sockets or secure connection via TLS/SSL. +The package is fully implemented in Tcl. +.PP +This document describes the procedures and explains their usage. +.SH PROCEDURES +This package defines the following public procedures: +.TP +\fB::imap4::open\fR \fIhostname\fR ?\fIport\fR? +.sp +Open a new IMAP connection and initalize the handler, +the imap communication channel (handler) is returned. +.sp +\fIhostname\fR - mail server +.sp +\fIport\fR - connection port, defaults to 143 +.sp +The namespace variable \fB::imap4::use_ssl\fR +can be used to establish to a secure connection +via TSL/SSL if set to true. In this case default connection port +defaults to 993. +.sp +\fINote:\fR +For connecting via SSL the Tcl module \fItls\fR must be already +loaded otherwise an error is raised. +.CS + + + package require tls ; # must be loaded for TLS/SSL + set ::imap4::use_ssl 1 ; # request a secure connection + set chan [::imap4::open $server] ; # default port is now 993 +.CE +.TP +\fB::imap4::login\fR \fIchan\fR \fIuser\fR \fIpass\fR +.sp +Login using the IMAP LOGIN command, 0 is returned on successful login. +.sp +\fIchan\fR - imap channel +.sp +\fIuser\fR - username +.sp +\fIpass\fR - password +.TP +\fB::imap4::folders\fR \fIchan\fR ?\fI-inline\fR? ?\fImboxref\fR? ?\fImboxname\fR? +.sp +Get list of matching folders, 0 is returned on success. +.sp +Wildcards '*' as '%' are allowed for \fImboxref\fR and \fImboxname\fR, +command \fB::imap4::folderinfo\fR can be used to retrieve folder information. +.sp +\fIchan\fR - imap channel +.sp +\fImboxref\fR - mailbox reference, defaults to "" +.sp +\fImboxname\fR - mailbox name, defaults to "*" +.sp +If \fB-inline\fR is specified a compact folderlist is +returned instead of the result code. All flags are converted to +lowercase and leading special characters are removed. +.CS + +{{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}} +.CE +.TP +\fB::imap4::select\fR \fIchan\fR ?\fImailbox\fR? +.sp +Select a mailbox, 0 is returned on success. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - Path of the mailbox, defaults to \fIINBOX\fR +.sp +Prior to examine/select an open mailbox must be closed - see: \fB::imap4::close\fR. +.TP +\fB::imap4::examine\fR \fIchan\fR ?\fImailbox\fR? +.sp +"Examines" a mailbox, read-only equivalent of \fB::imap4::select\fR. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - mailbox name or path to mailbox, +defaults to \fIINBOX\fR +.sp +Prior to examine/select an open mailbox must be closed - see: \fB::imap4::close\fR. +.TP +\fB::imap4::fetch\fR \fIchan\fR \fIrange\fR ?\fI-inline\fR? ?\fIattr ...\fR? +.sp +Fetch attributes from messages. +.sp +The attributes are fetched and stored in the internal state +which can be retrieved with command \fB::imap4::msginfo\fR, 0 is returned +on success. +If \fB-inline\fR is specified, alle records are returned as list +in order as defined in the \fIattr\fR argument. +.sp +\fIchan\fR - imap channel +.sp +\fIrange\fR - message index in format \fIFROM\fR:\fITO\fR +.sp +\fIattr\fR - imap attributes to fetch +.sp +\fINote:\fR +If \fIFROM\fR is omitted, the 1st message is assumed, +if \fITO\fR is ommitted the last message is assumed. +All message index ranges are 1-based. +.TP +\fB::imap4::noop\fR \fIchan\fR +Send NOOP command to server. May get information as untagged data. +.sp +\fIchan\fR - imap channel +.TP +\fB::imap4::check\fR \fIchan\fR +Send CHECK command to server. Flush to disk. +.sp +\fIchan\fR - imap channel +.TP +\fB::imap4::folderinfo\fR \fIchan\fR ?\fIinfo\fR? +.sp +Get information on the recently selected folderlist. +If the \fIinfo\fR argument is omitted or a null string, the full list +of information available for the mailbox is returned. +.sp +If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not. +.sp +\fIchan\fR - imap channel +.sp +\fIinfo\fR - folderlist options to retrieve +.sp +Currently supported options: +\fIdelim\fR - hierarchy delimiter only, +\fImatch\fR - ref and mbox search patterns (see \fB::imap4::folders\fR), +\fInames\fR - list of folder names only, +\fIflags\fR - list of folder names with flags in format +\fI{ {name {flags}} ... }\fR (see also compact format in function +\fB::imap4::folders\fR). +.CS + + +{{Arc08 {{\\NoSelect}}} {Arc08/Private {{\\NoInferiors} {\\UnMarked}}} {INBOX {\\NoInferiors}}} + +.CE +.TP +\fB::imap4::msginfo\fR \fIchan\fR \fImsgid\fR ?\fIinfo\fR? ?\fIdefval\fR? +.sp +Get information (from previously collected using fetch) from a given +\fImsgid\fR. If the 'info' argument is omitted or a null string, +the list of available information options for the given message is +returned. +.sp +If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not. +.sp +\fIchan\fR - imap channel +.sp +\fImsgid\fR - message number +.sp +\fIinfo\fR - imap keyword to retrieve +.sp +\fIdefval\fR - default value, returned if info is empty +.sp +\fINote:\fR +All message index ranges are 1-based. +.TP +\fB::imap4::mboxinfo\fR \fIchan\fR ?\fIinfo\fR? +.sp +Get information on the currently selected mailbox. +If the \fIinfo\fR argument is omitted or a null string, the list +of available information options for the mailbox is returned. +.sp +If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not. +.sp +\fIchan\fR - imap channel +.sp +\fIopt\fR - mailbox option to retrieve +.sp +Currently supported options: +\fIEXISTS\fR (noof msgs), +\fIRECENT\fR (noof 'recent' flagged msgs), +\fIFLAGS\fR +.sp +In conjunction with OK: +\fIPERMFLAGS\fR, \fIUIDNEXT\fR, \fIUIDVAL\fR, \fIUNSEEN\fR +.sp +Div. states: +\fICURRENT\fR, \fIFOUND\fR, \fIPERM\fR. +.CS + + + ::imap4::select $chan INBOX + puts "[::imap4::mboxinfo $chan exists] mails in INBOX" +.CE +.TP +\fB::imap4::isableto\fR \fIchan\fR ?\fIcapability\fR? +.sp +Test for capability. +It returns 1 if requested capability is supported, 0 otherwise. +If \fIcapability\fR is omitted all capability imap +codes are retured as list. +.sp +\fIchan\fR - imap channel +.sp +\fIinfo\fR - imap keyword to retrieve +.sp +\fINote:\fR +Use the capability command to ask the server if not +already done by the user. +.TP +\fB::imap4::create\fR \fIchan\fR \fImailbox\fR +.sp +Create a new mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - mailbox name +.TP +\fB::imap4::delete\fR \fIchan\fR \fImailbox\fR +.sp +Delete a new mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - mailbox name +.TP +\fB::imap4::rename\fR \fIchan\fR \fIoldname\fR \fInewname\fR +.sp +Rename a new mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - old mailbox name +.sp +\fImailbox\fR - new mailbox name +.TP +\fB::imap4::subscribe\fR \fIchan\fR \fImailbox\fR +.sp +Subscribe a new mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - mailbox name +.TP +\fB::imap4::unsubscribe\fR \fIchan\fR \fImailbox\fR +.sp +Unsubscribe a new mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fImailbox\fR - mailbox name +.TP +\fB::imap4::search\fR \fIchan\fR \fIexpr\fR ?\fI...\fR? +.sp +Search for mails matching search criterions, 0 is returned on success. +.sp +\fIchan\fR - imap channel +.sp +\fIexpr\fR - imap search expression +.sp +\fINotes:\fR +Currently the following search expressions are handled: +.sp +\fIMail header flags:\fR +all mail header entries (ending with a colon ":"), like "From:", "Bcc:", ... +.sp +\fIImap message search flags:\fR +ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, +SEEN, NEW, OLD, UNANSWERED, UNDELETED, +UNDRAFT, UNFLAGGED, UNSEEN, ALL +.sp +\fIImap header search flags:\fR +BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC +.sp +\fIImap conditional search flags:\fR +SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE, SINCE, +BEFORE (not implemented), +UID (not implemented) +.sp +\fILogical search conditions:\fR +OR, NOT +.CS + +::imap4::search $chan larger 4000 seen +puts "Found messages: [::imap4::mboxinfo $chan found]" +Found messages: 1 3 6 7 8 9 13 14 15 19 20 +.CE +.TP +\fB::imap4::close\fR \fIchan\fR +.sp +Close the mailbox. Permanently removes \\Deleted messages and +return to the AUTH state. +.sp +\fIchan\fR - imap channel +.TP +\fB::imap4::cleanup\fR \fIchan\fR +.sp +Destroy an IMAP connection and free the used space. +Close the mailbox. Permanently removes \\Deleted messages +and return to the AUTH state. +.sp +\fIchan\fR - imap channel +.TP +\fB::imap4::debugmode\fR \fIchan\fR ?\fIerrormsg\fR? +Switch client into command line debug mode. +.sp +This is a developers mode only that pass the control to the +programmer. Every line entered is sent verbatim to the +server (after the addition of the request identifier). +The ::imap4::debug variable is automatically set to '1' on enter. +.sp +It's possible to execute Tcl commands starting the line +with a slash. +.sp +\fIchan\fR - imap channel +.sp +\fIerrormsg\fR - optional error message to display +.TP +\fB::imap4::store\fR \fIchan\fR \fIrange\fR \fIdata\fR \fIflaglist\fR +.sp +Alters data associated with a message in the selected +mailbox. +.sp +\fIchan\fR - imap channel +.sp +\fIrange\fR - message index in format \fIFROM\fR:\fITO\fR +.sp +\fIflaglist\fR - Flags the \fIdata\fR operates on. +.sp +\fIdata\fR - The currently defined \fIdata\fR items that can be +stored are shown below. \fINote\fR that all of these data types may +also be suffixed with ".SILENT" to suppress the untagged FETCH +response. +.RS +.TP +FLAGS +Replace the flags for the message (other than \\Recent) with the +\fIflaglist\fR. +.TP ++FLAGS +Add the flags in \fIflaglist\fR to the existing flags for the message. +.TP +-FLAGS +Remove the flags in \fIflaglist\fR to the existing flags for the +message. +.RE +.IP +For example: +.CS + + + ::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted" + +.CE +.TP +\fB::imap4::expunge\fR \fIchan\fR +.sp +Permanently removes all messages that have the \\Deleted flag +set from the currently selected mailbox, without the need to close the +connection. +.sp +\fIchan\fR - imap channel +.TP +\fB::imap4::logout\fR \fIchan\fR +.sp +Informs the server that the client is done with the connection +and closes the network connection. Permanently removes \\Deleted +messages. +.sp +A new connection will need to be established to login once +more. +.sp +\fIchan\fR - imap channel +.PP +.SH EXAMPLES +.CS + + + set user myusername + set pass xtremescrt + set server imap.test.tld + set FOLDER INBOX + # Connect to server + set imap [::imap4::open $server] + ::imap4::login $imap $user $pass + ::imap4::select $imap $FOLDER + # Output all the information about that mailbox + foreach info [::imap4::mboxinfo $imap] { + puts "$info -> [::imap4::mboxinfo $imap $info]" + } + # fetch 3 records inline + set fields {from: to: subject: size} + foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] { + puts -nonewline "#[incr idx])" + for {set j 0} {$j<[llength $fields]} {incr j} { + puts "\\t[lindex $fields $j] [lindex $rec $j]" + } + } + + # Show all the information available about the message ID 1 + puts "Available info about message 1: [::imap4::msginfo $imap 1]" + + # Use the capability stuff + puts "Capabilities: [::imap4::isableto $imap]" + puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]" + + # Cleanup + ::imap4::cleanup $imap + +.CE +.SH REFERENCES +Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", +RFC 3501, March 2003, \fIhttp://www.rfc-editor.org/rfc/rfc3501.txt\fR +.PP +OpenSSL, \fIhttp://www.openssl.org/\fR +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Only a small part of rfc3501 implemented. +.PP +Please report such in the category \fIimap4\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ftp, http, imap, mime, pop3, tls +.SH KEYWORDS +email, imap, internet, mail, net, rfc3501, ssl, tls ADDED embedded/man/files/modules/inifile/ini.n Index: embedded/man/files/modules/inifile/ini.n ================================================================== --- /dev/null +++ embedded/man/files/modules/inifile/ini.n @@ -0,0 +1,352 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/inifile/ini.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "inifile" n 0.2.5 tcllib "Parsing of Windows INI files" +.BS +.SH NAME +inifile \- Parsing of Windows INI files +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBinifile ?0.2.4?\fR +.sp +\fB::ini::open\fR \fIfile\fR ?\fIaccess\fR? +.sp +\fB::ini::close\fR \fIini\fR +.sp +\fB::ini::commit\fR \fIini\fR +.sp +\fB::ini::revert\fR \fIini\fR +.sp +\fB::ini::filename\fR \fIini\fR +.sp +\fB::ini::sections\fR \fIini\fR +.sp +\fB::ini::keys\fR \fIini\fR \fIsection\fR +.sp +\fB::ini::get\fR \fIini\fR \fIsection\fR +.sp +\fB::ini::exists\fR \fIini\fR \fIsection\fR ?\fIkey\fR? +.sp +\fB::ini::value\fR \fIini\fR \fIsection\fR \fIkey\fR ?\fIdefault\fR? +.sp +\fB::ini::set\fR \fIini\fR \fIsection\fR \fIkey\fR \fIvalue\fR +.sp +\fB::ini::delete\fR \fIini\fR \fIsection\fR ?\fIkey\fR? +.sp +\fB::ini::comment\fR \fIini\fR \fIsection\fR ?\fIkey\fR? ?\fItext\fR? +.sp +\fB::ini::commentchar\fR ?char? +.sp +.BE +.SH DESCRIPTION +This package provides an interface for easy manipulation of Windows INI files. +.PP +.TP +\fB::ini::open\fR \fIfile\fR ?\fIaccess\fR? +Opens an INI file and returns a handle that is used by other commands. +\fIaccess\fR is the same as the first form (non POSIX) of the \fBopen\fR +command, with the exception that mode \fBa\fR is not supported. The +default mode is \fBr+\fR. +.TP +\fB::ini::close\fR \fIini\fR +Close the specified handle. If any changes were made and not written by +\fBcommit\fR they are lost. +.TP +\fB::ini::commit\fR \fIini\fR +Writes the file and all changes to disk. The sections are written in +arbitrary order. The keys in a section are written in alphabetical +order. If the ini was opened in read only mode an error will be thrown. +.TP +\fB::ini::revert\fR \fIini\fR +Rolls all changes made to the inifile object back to the last +committed state. +.TP +\fB::ini::filename\fR \fIini\fR +Returns the name of the file the \fIini\fR object is associated with. +.TP +\fB::ini::sections\fR \fIini\fR +Returns a list of all the names of the existing sections in the file handle +specified. +.TP +\fB::ini::keys\fR \fIini\fR \fIsection\fR +Returns a list of all they key names in the section and file specified. +.TP +\fB::ini::get\fR \fIini\fR \fIsection\fR +Returns a list of key value pairs that exist in the section and file specified. +.TP +\fB::ini::exists\fR \fIini\fR \fIsection\fR ?\fIkey\fR? +Returns a boolean value indicating the existance of the specified section as a +whole or the specified key within that section. +.TP +\fB::ini::value\fR \fIini\fR \fIsection\fR \fIkey\fR ?\fIdefault\fR? +Returns the value of the named key and section. If specified, +the default value will be returned if the key does not exist. If the key does +not exist and no default is specified an error will be thrown. +.TP +\fB::ini::set\fR \fIini\fR \fIsection\fR \fIkey\fR \fIvalue\fR +Sets the value of the key in the specified section. If the section does not +exist then a new one is created. +.TP +\fB::ini::delete\fR \fIini\fR \fIsection\fR ?\fIkey\fR? +Removes the key or the entire section and all its keys. A section is not +automatically deleted when it has no remaining keys. +.TP +\fB::ini::comment\fR \fIini\fR \fIsection\fR ?\fIkey\fR? ?\fItext\fR? +Reads and modifies comments for sections and keys. To write a section comment use an +empty string for the \fIkey\fR. To remove all comments use an empty string for \fItext\fR. +\fItext\fR may consist of a list of lines or one single line. Any embedded newlines in +\fItext\fR are properly handled. Comments may be written to nonexistant +sections or keys and will not return an error. Reading a comment from a nonexistant +section or key will return an empty string. +.TP +\fB::ini::commentchar\fR ?char? +Reads and sets the comment character. Lines that begin with this character are treated as +comments. When comments are written out each line is preceded by this character. The default +is \fB;\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIinifile\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/interp/deleg_method.n Index: embedded/man/files/modules/interp/deleg_method.n ================================================================== --- /dev/null +++ embedded/man/files/modules/interp/deleg_method.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/interp/deleg_method.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "deleg_method" n 0.2 tcllib "Interpreter utilities" +.BS +.SH NAME +deleg_method \- Creation of comm delegates (snit methods) +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBsnit ?1.1?\fR +.sp +package require \fBinterp::delegate::method ?0.2?\fR +.sp +\fB::interp::delegate::method\fR ?\fB-async\fR? \fIname\fR \fIarguments\fR \fIcomm\fR \fIid\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a single command for use within \fBsnit\fR +type definition (i.e. actually a \fBsnit::macro\fR) for the convenient +creation of methods which delegate the actual work to a remote +location via a "channel" created by the package \fBcomm\fR. +.SH API +.TP +\fB::interp::delegate::method\fR ?\fB-async\fR? \fIname\fR \fIarguments\fR \fIcomm\fR \fIid\fR +This commands creates a method which is named by \fIname\fR. All +invokations of this method will delegate the actual work to the remote +location identified by the comm channel \fIcomm\fR and the endpoint +\fIid\fR. +.sp +The name of the remote method invoked by the delegator is identical to +the name of the method itself. +.sp +Normally the generated method marshalls the \fIarguments\fR, and +returns the result from the remote method as its own result. If +however the option \fB-async\fR was specified then the generated +method will not wait for a result and return immediately. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIinterp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +comm, delegation, interpreter, method, snit +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/interp/deleg_proc.n Index: embedded/man/files/modules/interp/deleg_proc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/interp/deleg_proc.n @@ -0,0 +1,290 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/interp/deleg_proc.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "deleg_proc" n 0.2 tcllib "Interpreter utilities" +.BS +.SH NAME +deleg_proc \- Creation of comm delegates (procedures) +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBinterp::delegate::proc ?0.2?\fR +.sp +\fB::interp::delegate::proc\fR ?\fB-async\fR? \fIname\fR \fIarguments\fR \fIcomm\fR \fIid\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a single command for the convenient creation of +procedures which delegate the actual work to a remote location via a +"channel" created by the package \fBcomm\fR. +.SH API +.TP +\fB::interp::delegate::proc\fR ?\fB-async\fR? \fIname\fR \fIarguments\fR \fIcomm\fR \fIid\fR +This commands creates a procedure which is named by \fIname\fR and +returns its fully-qualified name. All invokations of this procedure +will delegate the actual work to the remote location identified by the +comm channel \fIcomm\fR and the endpoint \fIid\fR. +.sp +The name of the remote procedure invoked by the delegator is +[namespace tail \fIname\fR]. I.e., namespace information is +stripped from the call. +.sp +Normally the generated procedure marshalls the \fIarguments\fR, and +returns the result from the remote procedure as its own result. If +however the option \fB-async\fR was specified then the generated +procedure will not wait for a result and return immediately. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIinterp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +comm, delegation, interpreter, procedure +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/interp/tcllib_interp.n Index: embedded/man/files/modules/interp/tcllib_interp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/interp/tcllib_interp.n @@ -0,0 +1,311 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/interp/tcllib_interp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "interp" n 0.1.2 tcllib "Interpreter utilities" +.BS +.SH NAME +interp \- Interp creation and aliasing +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBinterp ?0.1.2?\fR +.sp +\fB::interp::createEmpty\fR ?\fIpath\fR? +.sp +\fB::interp::snitLink\fR \fIpath\fR \fImethodlist\fR +.sp +\fB::interp::snitDictLink\fR \fIpath\fR \fImethoddict\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a number of commands for the convenient creation +of Tcl interpreters for highly restricted execution. +.SH API +.TP +\fB::interp::createEmpty\fR ?\fIpath\fR? +This commands creates an empty Tcl interpreter and returns it +name. Empty means that the new interpreter has neither namespaces, nor +any commands. It is useful only for the creation of aliases. +.sp +If a \fIpath\fR is specified then it is taken as the name of the new +interpreter. +.TP +\fB::interp::snitLink\fR \fIpath\fR \fImethodlist\fR +This command assumes that it was called from within a method of a snit +object, and that the command \fBmymethod\fR is available. +.sp +It extends the interpreter specified by \fIpath\fR with aliases for +all methods found in the \fImethodlist\fR, with the alias directing +execution to the same-named method of the snit object invoking this +command. +Each element of \fImethodlist\fR is actually interpreted as a command +prefix, with the first word of each prefix the name of the method to +link to. +.sp +The result of the command is the empty string. +.TP +\fB::interp::snitDictLink\fR \fIpath\fR \fImethoddict\fR +This command behaves like \fB::interp::snitLink\fR, except that it +takes a dictionary mapping from commands to methods as its input, and +not a list of methods. +Like for \fB::interp::snitLink\fR the method references are actually +command prefixes. +This command allows the creation of more complex command-method +mappings than \fB::interp::snitLink\fR. +.sp +The result of the command is the empty string. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIinterp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +alias, empty interpreter, interpreter, method, snit +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/irc/irc.n Index: embedded/man/files/modules/irc/irc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/irc/irc.n @@ -0,0 +1,503 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/irc/irc.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "irc" n 0.6.1 tcllib "Low Level Tcl IRC Interface" +.BS +.SH NAME +irc \- Create IRC connection and interface. +.SH SYNOPSIS +package require \fBTcl \fR +.sp +package require \fBirc ?0.6.1?\fR +.sp +\fB::irc::config\fR ?key? ?value? +.sp +\fB::irc::connection\fR +.sp +\fB::irc::connections\fR +.sp +\fInet\fR \fBregisterevent\fR \fIevent\fR \fIscript\fR +.sp +\fInet\fR \fBgetevent\fR \fIevent\fR \fIscript\fR +.sp +\fInet\fR \fBeventexists\fR \fIevent\fR \fIscript\fR +.sp +\fInet\fR \fBconnect\fR \fIhostname\fR ?port? +.sp +\fInet\fR \fBconfig\fR ?key? ?value? +.sp +\fInet\fR \fBlog\fR \fIlevel\fR \fImessage\fR +.sp +\fInet\fR \fBlogname\fR +.sp +\fInet\fR \fBconnected\fR +.sp +\fInet\fR \fBsockname\fR +.sp +\fInet\fR \fBpeername\fR +.sp +\fInet\fR \fBsocket\fR +.sp +\fInet\fR \fBuser\fR \fIusername\fR \fIlocalhostname\fR \fIlocaldomainname\fR \fIuserinfo\fR +.sp +\fInet\fR \fBnick\fR \fInick\fR +.sp +\fInet\fR \fBping\fR \fItarget\fR +.sp +\fInet\fR \fBserverping\fR +.sp +\fInet\fR \fBjoin\fR \fIchannel\fR ?\fIkey\fR? +.sp +\fInet\fR \fBpart\fR \fIchannel\fR ?\fImessage\fR? +.sp +\fInet\fR \fBquit\fR ?\fImessage\fR? +.sp +\fInet\fR \fBprivmsg\fR \fItarget\fR \fImessage\fR +.sp +\fInet\fR \fBnotice\fR \fItarget\fR \fImessage\fR +.sp +\fInet\fR \fBctcp\fR \fItarget\fR \fImessage\fR +.sp +\fInet\fR \fBkick\fR \fIchannel\fR \fItarget\fR ?\fImessage\fR? +.sp +\fInet\fR \fBmode\fR \fItarget\fR \fIargs\fR +.sp +\fInet\fR \fBtopic\fR \fIchannel\fR \fImessage\fR +.sp +\fInet\fR \fBinvite\fR \fIchannel\fR \fItarget\fR +.sp +\fInet\fR \fBsend\fR \fItext\fR +.sp +\fInet\fR \fBdestroy\fR +.sp +\fBwho\fR ?\fBaddress\fR? +.sp +\fBaction\fR +.sp +\fBtarget\fR +.sp +\fBadditional\fR +.sp +\fBheader\fR +.sp +\fBmsg\fR +.sp +.BE +.SH DESCRIPTION +This package provides low-level commands to deal with the IRC protocol +(Internet Relay Chat) for immediate and interactive multi-cast +communication. +.PP +.TP +\fB::irc::config\fR ?key? ?value? +Sets configuration ?key? to ?value?. The configuration keys +currently defined are the boolean flags \fBlogger\fR and \fBdebug\fR. +\fBlogger\fR makes \fBirc\fR use the logger package for printing +error. \fBdebug\fR requires \fBlogger\fR and prints extra debug output. +If no ?key? or ?value? is given the current values are returned. +.TP +\fB::irc::connection\fR +The command creates a new object to deal with an IRC connection. +Creating this IRC object does not automatically create the network +connection. It returns a new irc namespace command which can be used +to interact with the new IRC connection. NOTE: the old form of the +connection command, which took a hostname and port as arguments, is +deprecated. Use \fBconnect\fR instead to specify this information. +.TP +\fB::irc::connections\fR +Returns a list of all the current connections that were created with +\fBconnection\fR +.PP +.SH "PER-CONNECTION COMMANDS" +.PP +In the following list of available connection methods \fInet\fR +represents a connection command as returned by +\fB::irc::connection\fR. +.TP +\fInet\fR \fBregisterevent\fR \fIevent\fR \fIscript\fR +Registers a callback handler for the specific event. Events available +are those described in RFC 1459 +\fIhttp://www.rfc-editor.org/rfc/rfc1459.txt\fR. +In addition, there are several other events defined. +\fBdefaultcmd\fR adds a command that is called if no other callback +is present. \fBEOF\fR is called if the connection signals an End of +File condition. The events \fBdefaultcmd\fR, \fBdefaultnumeric\fR, +\fBdefaultevent\fR, and \fBEOF\fR are required. +\fIscript\fR is executed in the connection namespace, which can take +advantage of several commands (see \fBCallback Commands\fR +below) to aid in the parsing of data. +.TP +\fInet\fR \fBgetevent\fR \fIevent\fR \fIscript\fR +Returns the current handler for the event if one exists. Otherwise an +empty string is returned. +.TP +\fInet\fR \fBeventexists\fR \fIevent\fR \fIscript\fR +Returns a boolean value indicating the existence of the event handler. +.TP +\fInet\fR \fBconnect\fR \fIhostname\fR ?port? +This causes the socket to be established. \fB::irc::connection\fR +created the namespace and the commands to be used, but did not +actually open the socket. This is done here. NOTE: the older form of +\'connect' did not require the user to specify a hostname and port, +which were specified with 'connection'. That form is deprecated. +.TP +\fInet\fR \fBconfig\fR ?key? ?value? +The same as \fB::irc::config\fR but sets and gets options for the \fInet\fR +connection only. +.TP +\fInet\fR \fBlog\fR \fIlevel\fR \fImessage\fR +If logger is turned on by \fBconfig\fR this will write a log \fImessage\fR +at \fIlevel\fR. +.TP +\fInet\fR \fBlogname\fR +Returns the name of the logger instance if logger is turned on. +.TP +\fInet\fR \fBconnected\fR +Returns a boolean value indicating if this connection is connected to a server. +.TP +\fInet\fR \fBsockname\fR +Returns a 3 element list consisting of the ip address, the hostname, and the port +of the local end of the connection, if currently connected. +.TP +\fInet\fR \fBpeername\fR +Returns a 3 element list consisting of the ip address, the hostname, and the port +of the remote end of the connection, if currently connected. +.TP +\fInet\fR \fBsocket\fR +Return the Tcl channel for the socket used by the connection. +.TP +\fInet\fR \fBuser\fR \fIusername\fR \fIlocalhostname\fR \fIlocaldomainname\fR \fIuserinfo\fR +Sends USER command to server. \fIusername\fR is the username you want +to appear. \fIlocalhostname\fR is the host portion of your hostname, \fIlocaldomainname\fR +is your domain name, and \fIuserinfo\fR is a short description of who you are. The 2nd and 3rd +arguments are normally ignored by the IRC server. +.TP +\fInet\fR \fBnick\fR \fInick\fR +NICK command. \fInick\fR is the nickname you wish to use for the +particular connection. +.TP +\fInet\fR \fBping\fR \fItarget\fR +Send a CTCP PING to \fItarget\fR. +.TP +\fInet\fR \fBserverping\fR +PING the server. +.TP +\fInet\fR \fBjoin\fR \fIchannel\fR ?\fIkey\fR? +\fIchannel\fR is the IRC channel to join. IRC channels typically +begin with a hashmark ("#") or ampersand ("&"). +.TP +\fInet\fR \fBpart\fR \fIchannel\fR ?\fImessage\fR? +Makes the client leave \fIchannel\fR. Some networks may support the optional +argument \fImessage\fR +.TP +\fInet\fR \fBquit\fR ?\fImessage\fR? +Instructs the IRC server to close the current connection. The package +will use a generic default if no \fImessage\fR was specified. +.TP +\fInet\fR \fBprivmsg\fR \fItarget\fR \fImessage\fR +Sends \fImessage\fR to \fItarget\fR, which can be either a channel, or +another user, in which case their nick is used. +.TP +\fInet\fR \fBnotice\fR \fItarget\fR \fImessage\fR +Sends a \fBnotice\fR with message \fImessage\fR to \fItarget\fR, +which can be either a channel, or another user, in which case their nick is used. +.TP +\fInet\fR \fBctcp\fR \fItarget\fR \fImessage\fR +Sends a CTCP of type \fImessage\fR to \fItarget\fR +.TP +\fInet\fR \fBkick\fR \fIchannel\fR \fItarget\fR ?\fImessage\fR? +Kicks the user \fItarget\fR from the channel \fIchannel\fR with a \fImessage\fR. +The latter can be left out. +.TP +\fInet\fR \fBmode\fR \fItarget\fR \fIargs\fR +Sets the mode \fIargs\fR on the target \fItarget\fR. \fItarget\fR may be a channel, +a channel user, or yourself. +.TP +\fInet\fR \fBtopic\fR \fIchannel\fR \fImessage\fR +Sets the topic on \fIchannel\fR to \fImessage\fR specifying an empty string +will remove the topic. +.TP +\fInet\fR \fBinvite\fR \fIchannel\fR \fItarget\fR +Invites \fItarget\fR to join the channel \fIchannel\fR +.TP +\fInet\fR \fBsend\fR \fItext\fR +Sends \fItext\fR to the IRC server. +.TP +\fInet\fR \fBdestroy\fR +Deletes the connection and its associated namespace and information. +.PP +.SH "CALLBACK COMMANDS" +.PP +These commands can be used within callbacks +.TP +\fBwho\fR ?\fBaddress\fR? +Returns the nick of the user who performed a command. The optional +keyword \fBaddress\fR causes the command to return the user in the +format "username@address". +.TP +\fBaction\fR +Returns the action performed, such as KICK, PRIVMSG, MODE, etc... +Normally not useful, as callbacks are bound to a particular event. +.TP +\fBtarget\fR +Returns the target of a particular command, such as the channel or +user to whom a PRIVMSG is sent. +.TP +\fBadditional\fR +Returns a list of any additional arguments after the target. +.TP +\fBheader\fR +Returns the entire event header (everything up to the :) as a proper list. +.TP +\fBmsg\fR +Returns the message portion of the command (the part after the :). +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIirc\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +rfc 1459 +.SH KEYWORDS +chat, irc +.SH CATEGORY +Networking ADDED embedded/man/files/modules/irc/picoirc.n Index: embedded/man/files/modules/irc/picoirc.n ================================================================== --- /dev/null +++ embedded/man/files/modules/irc/picoirc.n @@ -0,0 +1,385 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/irc/picoirc.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "picoirc" n 0.5 tcllib "Simple embeddable IRC interface" +.BS +.SH NAME +picoirc \- Small and simple embeddable IRC client. +.SH SYNOPSIS +package require \fBTcl \fR +.sp +package require \fBpicoirc ?0.5?\fR +.sp +\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR \fIurl\fR +.sp +\fB::picoirc::post\fR \fIcontext\fR \fIchannel\fR \fImessage\fR +.sp +\fB::picoirc::splituri\fR \fIuri\fR +.sp +\fB::picoirc::send\fR \fIcontext\fR \fIline\fR +.sp +.BE +.SH DESCRIPTION +This package provides a general purpose minimal IRC client suitable for +embedding in other applications. All communication with the parent +application is done via an application provided callback procedure. +Each connection has its own state so you can hook up multiple servers +in a single application instance. +.PP +To initiate an IRC connection you must call \fBpicoirc::connect\fR +with a callback procedure, a nick-name to use on IRC and the IRC URL +that describes the connection. This will return a variable name that +is the irc connection context. See \fBCALLBACK\fR for details. +.PP +This package is a fairly simple IRC client. If you need something with +more capability investigate the \fBirc\fR package. +.PP +.SH COMMANDS +.TP +\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR \fIurl\fR +Create a new irc connection to the server specified by \fIurl\fR and +login using the \fInick\fR as the username. The \fIcallback\fR must be +as specified in \fBCALLBACK\fR. Returns a package-specific variable +that is used when calling other commands in this package. +.TP +\fB::picoirc::post\fR \fIcontext\fR \fIchannel\fR \fImessage\fR +This should be called to process user input and send it to the +server. A number of commands are recognised when prefixed with a +forward-slash (/). Such commands are converted to IRC command +sequences and then sent. +.TP +\fB::picoirc::splituri\fR \fIuri\fR +Splits an IRC scheme uniform resource indicator into its component +parts. Returns a list of server, port and channel. The default port is +6667 and there is no default channel. +.TP +\fB::picoirc::send\fR \fIcontext\fR \fIline\fR +This command is where all raw output to the server is handled. The +default action is to write the \fIline\fR to the irc socket. However, +before this happens the callback is called with "debug write". This +permits the application author to inspect the raw IRC data and if +desired to return a break error code to halt further processing. In +this way the application can override the default send via the +callback procedure. +.PP +.SH CALLBACK +The callback must look like: +.CS + + +proc Callback {context state args} { +} + +.CE +where context is the irc context variable name (in case you need to pass +it back to a picoirc procedure). state is one of a number of states as +described below. +.TP +\fBinit\fR +called just before the socket is created +.TP +\fBconnect\fR +called once we have connected, before we join any channels +.TP +\fBclose\fR +called when the socket gets closed, before the context is deleted. If +an error occurs before we get connected the only argument will be the +socket error message. +.TP +\fBuserlist\fR \fIchannel\fR \fInicklist\fR +called to notify the application of an updated userlist. This is +generated when the output of the NAMES irc command is seen. The +package collects the entire output which can span a number of output +lines from the server and calls this callback when they have all been +received. +.TP +\fBchat\fR \fItarget\fR \fInick\fR \fImessage\fR \fItype\fR +called when a message arrives. \fItarget\fR is the identity that the +message was targetted for. This can be the logged in nick or a channel +name. \fInick\fR is the name of the sender of the message. +\fImessage\fR is the message text. \fItype\fR is set to "ACTION" if the +message was sent as a CTCP ACTION +.TP +\fBsystem\fR \fIchannel\fR \fImessage\fR +called when a system message is received +.TP +\fBtopic\fR \fIchannel\fR \fItopic\fR +called when the channel topic string is seen. \fItopic\fR is the text +of the channel topic. +.TP +\fBtraffic\fR \fIaction\fR \fIchannel\fR \fInick\fR ?\fInewnick\fR? +called when users join, leave or change names. +\fIaction\fR is either entered, left or nickchange and \fInick\fR +is the user doing the action. \fInewnick\fR is +the new name if \fIaction\fR is nickchange. +.sp +\fINOTE\fR: \fIchannel\fR is often empty for these messages as nick +activities are global for the irc server. You will have +to manage the nick for all connected channels yourself. +.TP +\fBversion\fR +This is called to request a version string to use to +override the internal version. If implemented, you should +return as colon delimited string as +.sp +Appname:Appversion:LibraryVersion +.sp +For example, the default is +.sp +PicoIRC:[package provide picoirc]:Tcl [info patchlevel] +.TP +\fBdebug\fR \fItype\fR \fIraw\fR +called when data is either being read or written to the network +socket. \fItype\fR is set to \fBread\fR when reading data and +\fBwrite\fR if the data is to be written. \fIraw\fR is the +unprocessed IRC protocol data. +.sp +In both cases the application can return a break error code to +interrupt further processing of the raw data. If this is a +\fBread\fR operation then the package will not handle this line. If +the operation is \fBwrite\fR then the package will not send the +data. This callback is intended for debugging protocol issues but +could be used to redirect all input and output if desired. +.PP +.SH "SEE ALSO" +rfc 1459 +.SH KEYWORDS +chat, irc +.SH CATEGORY +Networking ADDED embedded/man/files/modules/javascript/javascript.n Index: embedded/man/files/modules/javascript/javascript.n ================================================================== --- /dev/null +++ embedded/man/files/modules/javascript/javascript.n @@ -0,0 +1,339 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/javascript/javascript.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "javascript" n 1.0.2 tcllib "HTML and Java Script Generation" +.BS +.SH NAME +javascript \- Procedures to generate HTML and Java Script structures. +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBjavascript ?1.0.2?\fR +.sp +\fB::javascript::makeSelectorWidget\fR \fIid leftLabel leftValueList rightLabel rightValueList rightNameList\fR ?\fIlength\fR? ?\fIminWidth\fR? +.sp +\fB::javascript::makeSubmitButton\fR \fIname value\fR +.sp +\fB::javascript::makeProtectedSubmitButton\fR \fIname value msg\fR +.sp +\fB::javascript::makeMasterButton\fR \fImaster value slavePattern boolean\fR +.sp +\fB::javascript::makeParentCheckbox\fR \fIparentName childName\fR +.sp +\fB::javascript::makeChildCheckbox\fR \fIparentName childName\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::javascript\fR package provides commands that generate +HTML and Java Script code. These commands typically return an HTML +string as their result. In particular, they do not output their +result to \fBstdout\fR. +.PP +.TP +\fB::javascript::makeSelectorWidget\fR \fIid leftLabel leftValueList rightLabel rightValueList rightNameList\fR ?\fIlength\fR? ?\fIminWidth\fR? +Construct HTML code to create a dual-multi-selection megawidget. This +megawidget consists of two side-by-side multi-selection boxes +separated by a left arrow and a right arrow button. The right arrow +button moves all items selected in the left box to the right box. The +left arrow button moves all items selected in the right box to the +left box. The \fIid\fR argument is the suffix of all HTML objects in +this megawidget. The \fIleftLabel\fR argument is the text that +appears above the left selection box. The \fIleftValueList\fR +argument is the values of items in the left selection box. The +\fIleftNameList\fR argument is the names to appear in the left +selection box. The \fIrightLabel\fR argument is the text that appears +above the right selection box. The \fIrightValueList\fR argument is +the values of items in the right selection box. The +\fIrightNameList\fR argument is the names to appear in the right +selection box. The \fIlength\fR argument (optional) determines the +number of elts to show before adding a vertical scrollbar; it defaults +to 8. The \fIminWidth\fR argument (optional) is the number of spaces +to determine the minimum box width; it defaults to 32. +.TP +\fB::javascript::makeSubmitButton\fR \fIname value\fR +Create an HTML submit button that resets a hidden field for each +registered multi-selection box. The \fIname\fR argument is the name +of the HTML button object to create. The \fIvalue\fR argument is the +label of the HTML button object to create. +.TP +\fB::javascript::makeProtectedSubmitButton\fR \fIname value msg\fR +Create an HTML submit button that prompts the user with a +continue/cancel shutdown warning before the form is submitted. The +\fIname\fR argument is the name of the HTML button object to create. +The \fIvalue\fR argument is the label of the HTML button object to +create. The \fImsg\fR argument is the message to display when the +button is pressed. +.TP +\fB::javascript::makeMasterButton\fR \fImaster value slavePattern boolean\fR +Create an HTML button that sets its slave checkboxs to the boolean +value. The \fImaster\fR argument is the name of the child's parent +html checkbox object. The \fIvalue\fR argument is the value of the +master. The \fIslaves\fR argument is the name of child html checkbox +object to create. The \fIboolean\fR argument is the java script +boolean value that will be given to all the slaves; it must be "true" +or "false". +.TP +\fB::javascript::makeParentCheckbox\fR \fIparentName childName\fR +Create an HTML checkbox and tie its value to that of its child +checkbox. If the parent is unchecked, the child is automatically +unchecked. The \fIparentName\fR argument is the name of parent html +checkbox object to create. The \fIchildName\fR argument is the name of +the parent's child html checkbox object. +.TP +\fB::javascript::makeChildCheckbox\fR \fIparentName childName\fR +Create an HTML checkbox and tie its value to that of its parent +checkbox. If the child is checked, the parent is automatically +checked. The \fIparentName\fR argument is the name of the child's +parent html checkbox object. The \fIchildName\fR argument is the name +of child html checkbox object to create. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIjavascript\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +html, ncgi +.SH KEYWORDS +checkbox, html, javascript, selectionbox, submitbutton +.SH CATEGORY +CGI programming ADDED embedded/man/files/modules/jpeg/jpeg.n Index: embedded/man/files/modules/jpeg/jpeg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/jpeg/jpeg.n @@ -0,0 +1,451 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/jpeg/jpeg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2005, Code: Aaron Faupell <afaupell@users.sourceforge.net> +'\" Copyright (c) 2007, Code: Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2004-2009, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2011, Code: Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "jpeg" n 0.4.0 tcllib "JPEG image manipulation" +.BS +.SH NAME +jpeg \- JPEG querying and manipulation of meta data +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBjpeg ?0.4.0?\fR +.sp +\fB::jpeg::isJPEG\fR \fIfile\fR +.sp +\fB::jpeg::imageInfo\fR \fIfile\fR +.sp +\fB::jpeg::dimensions\fR \fIfile\fR +.sp +\fB::jpeg::getThumbnail\fR \fIfile\fR +.sp +\fB::jpeg::getExif\fR \fIfile\fR ?\fIsection\fR? +.sp +\fB::jpeg::getExifFromChannel\fR \fIchannel\fR ?\fIsection\fR? +.sp +\fB::jpeg::formatExif\fR \fIkeys\fR +.sp +\fB::jpeg::exifKeys\fR +.sp +\fB::jpeg::removeExif\fR \fIfile\fR +.sp +\fB::jpeg::stripJPEG\fR \fIfile\fR +.sp +\fB::jpeg::getComments\fR \fIfile\fR +.sp +\fB::jpeg::addComment\fR \fIfile\fR \fItext\fR... +.sp +\fB::jpeg::removeComments\fR \fIfile\fR +.sp +\fB::jpeg::replaceComment\fR \fIfile\fR \fItext\fR +.sp +\fB::jpeg::debug\fR \fIfile\fR +.sp +\fB::jpeg::markers\fR \fIchannel\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides commands to query and modify JPEG images. JPEG +stands for \fIJoint Photography Experts Group\fR and is a standard +for the lossy compression of photographical images. It is specified at +\fILINK_HERE\fR. +.SH COMMANDS +.TP +\fB::jpeg::isJPEG\fR \fIfile\fR +Returns a boolean value indicating if \fIfile\fR is a +JPEG image. +.TP +\fB::jpeg::imageInfo\fR \fIfile\fR +Returns a dictionary with keys \fBversion\fR, \fBunits\fR, +\fBxdensity\fR, \fBydensity\fR, \fBxthumb\fR, and +\fBythumb\fR. The values are the associated properties of the JPEG +image in \fIfile\fR. +Throws an error if \fIfile\fR is not a JPEG image. +.TP +\fB::jpeg::dimensions\fR \fIfile\fR +Returns the dimensions of the JPEG \fIfile\fR as a list of the +horizontal and vertical pixel count. +Throws an error if \fIfile\fR is not a JPEG image. +.TP +\fB::jpeg::getThumbnail\fR \fIfile\fR +This procedure will return the binary thumbnail image data, if a JPEG +thumbnail is included in \fIfile\fR, and the empty string +otherwise. Note that it is possible to include thumbnails in formats +other than JPEG although that is not common. The command finds +thumbnails that are encoded in either the JFXX or EXIF segments of the +JPEG information. If both are present the EXIF thumbnail will take precedence. +Throws an error if \fIfile\fR is not a JPEG image. +.CS + + + set fh [open thumbnail.jpg w+] + fconfigure $fh -translation binary -encoding binary + puts -nonewline $fh [::jpeg::getThumbnail photo.jpg] + close $fh + +.CE +.TP +\fB::jpeg::getExif\fR \fIfile\fR ?\fIsection\fR? +\fIsection\fR must be one of \fBmain\fR or \fBthumbnail\fR. +The default is \fBmain\fR. +Returns a dictionary containing the EXIF information for the specified section. +For example: +.sp +.CS + + + set exif { + Make Canon + Model {Canon DIGITAL IXUS} + DateTime {2001:06:09 15:17:32} + } + +.CE +.IP +Throws an error if \fIfile\fR is not a JPEG image. +.TP +\fB::jpeg::getExifFromChannel\fR \fIchannel\fR ?\fIsection\fR? +This command is as per \fB::jpeg::getExif\fR except that it uses a +previously opened channel. \fIchannel\fR should be a seekable channel +and \fIsection\fR is as described in the documentation of +\fB::jpeg::getExif\fR +Note: the jpeg parser expects that the start of the channel is the +start of the image data. If working with an image embedded in a +container file format it may be necessary to read the jpeg data into +a temporary container: either a temporary file or a memory channel. +.TP +\fB::jpeg::formatExif\fR \fIkeys\fR +Takes a list of key-value pairs as returned by \fBgetExif\fR and formats +many of the values into a more human readable form. As few as one key-value +may be passed in, the entire exif is not required. +.CS + + + foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] { + puts "$key: $val" + } + +.CE +.sp +.CS + + + array set exif [::jpeg::getExif photo.jpg] + puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]] + +.CE +.TP +\fB::jpeg::exifKeys\fR +Returns a list of the EXIF keys which are currently understood. +There may be keys present in \fBgetExif\fR data that are not understood. +Those keys will appear in a 4 digit hexadecimal format. +.TP +\fB::jpeg::removeExif\fR \fIfile\fR +Removes the Exif data segment from the specified file and replaces +it with a standard JFIF segment. +Throws an error if \fIfile\fR is not a JPEG image. +.TP +\fB::jpeg::stripJPEG\fR \fIfile\fR +Removes all metadata from the JPEG file leaving only +the image. This includes comments, EXIF segments, JFXX +segments, and application specific segments. +Throws an error if \fIfile\fR is not a JPEG image. +.TP +\fB::jpeg::getComments\fR \fIfile\fR +Returns a list containing all the JPEG comments found in +the \fIfile\fR. +Throws an error if \fIfile\fR is not a valid JPEG image. +.TP +\fB::jpeg::addComment\fR \fIfile\fR \fItext\fR... +Adds one or more plain \fItext\fR comments to the JPEG image +in \fIfile\fR. +Throws an error if \fIfile\fR is not a valid JPEG image. +.TP +\fB::jpeg::removeComments\fR \fIfile\fR +Removes all comments from the file specified. +Throws an error if \fIfile\fR is not a valid JPEG image. +.TP +\fB::jpeg::replaceComment\fR \fIfile\fR \fItext\fR +Replaces the first comment in the file with the new \fItext\fR. +This is merely a shortcut for \fB::jpeg::removeComments\fR +and \fB::jpeg::addComment\fR +Throws an error if \fIfile\fR is not a valid JPEG image. +.TP +\fB::jpeg::debug\fR \fIfile\fR +Prints everything we know about the given file in a nice format. +.TP +\fB::jpeg::markers\fR \fIchannel\fR +This is an internal helper command, we document it for use by advanced +users of the package. The argument \fIchannel\fR is an open file +handle positioned at the start of the first marker (usually 2 +bytes). The command returns a list with one element for each JFIF +marker found in the file. Each element consists of a list of the +marker name, its offset in the file, and its length. The offset points +to the beginning of the sections data, not the marker itself. The +length is the length of the data from the offset listed to the start +of the next marker. +.PP +.SH LIMITATIONS +can only work with files +cant write exif data +gps exif data not parsed +makernote data not yet implemented +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIjpeg\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +comment, exif, image, jfif, jpeg, thumbnail +.SH CATEGORY +File formats +.SH COPYRIGHT +.nf +Copyright (c) 2004-2005, Code: Aaron Faupell <afaupell@users.sourceforge.net> +Copyright (c) 2007, Code: Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2004-2009, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2011, Code: Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/json/json.n Index: embedded/man/files/modules/json/json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/json/json.n @@ -0,0 +1,341 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/json/json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 ActiveState Software Inc. +'\" Copyright (c) 2009 Thomas Maeder, Glue Software Engineering AG +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "json" n 1.1.2 tcllib "JSON" +.BS +.SH NAME +json \- JSON parser +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBjson ?1.1.2?\fR +.sp +\fB::json::json2dict\fR \fItxt\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBjson\fR package provides a simple Tcl-only library for parsing the +JSON \fIhttp://www.json.org/\fR data exchange format as specified in RFC 4627 +\fIhttp://www.ietf.org/rfc/rfc4627.txt\fR. +There is some ambiguity in parsing JSON because JSON has type information that +is not maintained by the Tcl conversion. The \fBjson\fR package returns +data as a Tcl \fBdict\fR. Either the \fBdict\fR package or Tcl 8.5 is +required for use. +.SH COMMANDS +.TP +\fB::json::json2dict\fR \fItxt\fR +Parse JSON formatted text \fItxt\fR into a Tcl dict and return the value. +.PP +.PP +.SH EXAMPLES +.PP +An example of a JSON array converted to Tcl. A JSON array is returned as a +single item with multiple elements. +.PP +.CS + +[ + { + "precision": "zip", + "Latitude": 37.7668, + "Longitude": -122.3959, + "Address": "", + "City": "SAN FRANCISCO", + "State": "CA", + "Zip": "94107", + "Country": "US" + }, + { + "precision": "zip", + "Latitude": 37.371991, + "Longitude": -122.026020, + "Address": "", + "City": "SUNNYVALE", + "State": "CA", + "Zip": "94085", + "Country": "US" + } +] +=> +{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020} + +.CE +.PP +An example of a JSON object converted to Tcl. A JSON object is returned as a +multi-element list (a dict). +.PP +.CS + +{ + "Image": { + "Width": 800, + "Height": 600, + "Title": "View from 15th Floor", + "Thumbnail": { + "Url": "http://www.example.com/image/481989943", + "Height": 125, + "Width": "100" + }, + "IDs": [116, 943, 234, 38793] + } +} +=> +Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIjson\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +data exchange, exchange format, javascript, json +.SH CATEGORY +CGI programming +.SH COPYRIGHT +.nf +Copyright (c) 2006 ActiveState Software Inc. +Copyright (c) 2009 Thomas Maeder, Glue Software Engineering AG + +.fi ADDED embedded/man/files/modules/json/json_write.n Index: embedded/man/files/modules/json/json_write.n ================================================================== --- /dev/null +++ embedded/man/files/modules/json/json_write.n @@ -0,0 +1,331 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/json/json_write.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009-2013 Andreas Kupries <andreas_kupries@sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "json::write" n 1.0.2 tcllib "JSON" +.BS +.SH NAME +json::write \- JSON generation +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBjson::write ?1.0.2?\fR +.sp +\fB::json::write\fR \fBindented\fR +.sp +\fB::json::write\fR \fBindented\fR \fIflag\fR +.sp +\fB::json::write\fR \fBaligned\fR +.sp +\fB::json::write\fR \fBaligned\fR \fIflag\fR +.sp +\fB::json::write\fR \fBstring\fR \fIs\fR +.sp +\fB::json::write\fR \fBarray\fR \fIarg\fR... +.sp +\fB::json::write\fR \fBobject\fR \fIkey\fR \fIvalue\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBjson::write\fR package provides a simple Tcl-only library +for generation of text in the JSON \fIhttp://www.json.org/\fR data +exchange format as specified in +RFC 4627 \fIhttp://www.ietf.org/rfc/rfc4627.txt\fR. +.SH COMMANDS +.TP +\fB::json::write\fR \fBindented\fR +This method returns the current state of the indentation setting. +.TP +\fB::json::write\fR \fBindented\fR \fIflag\fR +This and the method \fBaligned\fR configure the layout of the JSON +generated by the package. +.sp +If this \fIflag\fR is set (default) the package will break the +generated JSON code across lines and indent it according to its inner +structure, with each key of an object on a separate line. +.sp +If this flag is not set, the whole JSON object will be written on a +single line, with minimum spacing between all elements. +.TP +\fB::json::write\fR \fBaligned\fR +This method returns the current state of the alignment setting. +.TP +\fB::json::write\fR \fBaligned\fR \fIflag\fR +This and the method \fBindented\fR configure the layout of the JSON +generated by the package. +.sp +If this \fIflag\fR is set (default) the package ensures that the +values for the keys in an object are vertically aligned with each +other, for a nice table effect. To make this work this also implies +that \fBindented\fR is set as well. +.sp +If this flag is not set, the output is formatted as per the value of +\fBindented\fR, without trying to align the values for object keys. +.TP +\fB::json::write\fR \fBstring\fR \fIs\fR +This method takes the string \fIs\fR and returns it properly quoted +for JSON as its result. +.TP +\fB::json::write\fR \fBarray\fR \fIarg\fR... +This method takes a series of JSON formatted arguments and returns +them as a properly formatted JSON array as its result. +.TP +\fB::json::write\fR \fBobject\fR \fIkey\fR \fIvalue\fR... +This method takes a series of key/value arguments, the values already +formatted for JSON, and returns them as a properly formatted JSON +object as its result, with the keys formatted as JSON strings. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIjson\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +data exchange, exchange format, javascript, json +.SH CATEGORY +CGI programming +.SH COPYRIGHT +.nf +Copyright (c) 2009-2013 Andreas Kupries <andreas_kupries@sourceforge.net> + +.fi ADDED embedded/man/files/modules/lambda/lambda.n Index: embedded/man/files/modules/lambda/lambda.n ================================================================== --- /dev/null +++ embedded/man/files/modules/lambda/lambda.n @@ -0,0 +1,336 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/lambda/lambda.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011 Andreas Kupries, BSD licensed +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "lambda" n 1 tcllib "Utility commands for anonymous procedures" +.BS +.SH NAME +lambda \- Utility commands for anonymous procedures +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBlambda ?1?\fR +.sp +\fB::lambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...? +.sp +\fB::lambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides two convenience commands to make the writing of +anonymous procedures, i.e. lambdas more \fBproc\fR-like. Instead of, +for example, to write +.CS + + + set f {::apply {{x} { + .... + }}} + +.CE +with its deep nesting of braces, or +.CS + + + set f [list ::apply {{x y} { + .... + }} $value_for_x] + +.CE +with a list command to insert some of the arguments of a partial +application, just write +.CS + + + set f [lambda {x} { + .... + }] + +.CE +and +.CS + + + set f [lambda {x y} { + .... + } $value_for_x] + +.CE +.SH COMMANDS +.TP +\fB::lambda\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...? +The command constructs an anonymous procedure from the list of +arguments, body script and (optional) predefined argument values and +returns a command prefix representing this anonymous procedure. +.sp +When invoked the \fIbody\fR is run in a new procedure scope +just underneath the global scope, with the arguments set to the values +supplied at both construction and invokation time. +.TP +\fB::lambda@\fR \fInamespace\fR \fIarguments\fR \fIbody\fR ?\fIarg\fR...? +The command constructs an anonymous procedure from the namespace name, +list of arguments, body script and (optional) predefined argument +values and returns a command prefix representing this anonymous +procedure. +.sp +When invoked the \fIbody\fR is run in a new procedure scope in +the \fInamespace\fR, with the arguments set to the values supplied at +both construction and invokation time. +.PP +.SH AUTHORS +Andreas Kupries +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIlambda\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +apply(n), proc(n) +.SH KEYWORDS +anonymous procedure, callback, command prefix, currying, lambda, partial application, proc +.SH CATEGORY +Utility +.SH COPYRIGHT +.nf +Copyright (c) 2011 Andreas Kupries, BSD licensed + +.fi ADDED embedded/man/files/modules/ldap/ldap.n Index: embedded/man/files/modules/ldap/ldap.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ldap/ldap.n @@ -0,0 +1,747 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ldap/ldap.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2004 Jochen Loewer <loewerj@web.de> +'\" Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ldap" n 1.6.9 tcllib "LDAP client" +.BS +.SH NAME +ldap \- LDAP client +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBldap ?1.8?\fR +.sp +\fB::ldap::connect\fR \fIhost\fR ?\fIport\fR? +.sp +\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? +.sp +\fB::ldap::disconnect\fR \fIhandle\fR +.sp +\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? +.sp +\fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? +.sp +\fB::ldap::bindSASL\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? +.sp +\fB::ldap::unbind\fR \fIhandle\fR +.sp +\fB::ldap::search\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR +.sp +\fB::ldap::searchInit\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR +.sp +\fB::ldap::searchNext\fR \fIhandle\fR +.sp +\fB::ldap::searchEnd\fR \fIhandle\fR +.sp +\fB::ldap::modify\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrToDelete\fR? ?\fIattrValToAdd\fR? +.sp +\fB::ldap::modifyMulti\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrValToDelete\fR? ?\fIattrValToAdd\fR? +.sp +\fB::ldap::add\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR +.sp +\fB::ldap::addMulti\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR +.sp +\fB::ldap::delete\fR \fIhandle\fR \fIdn\fR +.sp +\fB::ldap::modifyDN\fR \fIhandle\fR \fIdn\fR \fInewrdn\fR ?\fIdeleteOld\fR? ?\fInewSuperior\fR? +.sp +\fB::ldap::info\fR \fBip\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBbound\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBbounduser\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBconnections\fR +.sp +\fB::ldap::info\fR \fBtls\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR +.sp +\fB::ldap::info\fR \fBextensions\fR \fIextensions\fR +.sp +\fB::ldap::info\fR \fBwhoami\fR \fIhandle\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBldap\fR package provides a Tcl-only client library +for the LDAPv3 protocol as specified in +RFC 4511 (\fIhttp://www.rfc-editor.org/rfc/rfc4511.txt\fR). +It works by opening the standard (or secure) LDAP socket on the +server, and then providing a Tcl API to access the LDAP protocol +commands. All server errors are returned as Tcl errors (thrown) which +must be caught with the Tcl \fBcatch\fR command. +.SH COMMANDS +.TP +\fB::ldap::connect\fR \fIhost\fR ?\fIport\fR? +Opens a LDAPv3 connection to the specified \fIhost\fR, at the given +\fIport\fR, and returns a token for the connection. This token is the +\fIhandle\fR argument for all other commands. If no \fIport\fR is +specified it will default to \fB389\fR. +.sp +The command blocks until the connection has been established, or +establishment definitely failed. +.TP +\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? +Like \fB::ldap::connect\fR, except that the created connection is +secured by SSL. The port defaults to \fB636\fR. This command +depends on the availability of the package \fBTLS\fR, which is a +SSL binding for Tcl. If \fBTLS\fR is not available, then this +command will fail. +.sp +The command blocks until the connection has been established, or +establishment definitely failed. +.TP +\fB::ldap::disconnect\fR \fIhandle\fR +Closes the ldap connection refered to by the token +\fIhandle\fR. Returns the empty string as its result. +.TP +\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? +Start TLS negotiation on the connection denoted by \fIhandle\fR. +This is currently experimental and subject to change, more control over the TLS details +will probably be exposed later, to allow users to fine tune the negotiation according +to their security needs. +.TP +\fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? +This command authenticates the ldap connection refered to by the token +in \fIhandle\fR, with a user name and associated password. It blocks +until a response from the ldap server arrives. Its result is the empty +string. +Both \fIname\fR and \fIpasswd\fR default to the empty string if they +are not specified. +By leaving out \fIname\fR and \fIpasswd\fR you can make an anonymous bind to +the ldap server. +You can issue \fB::ldap::bind\fR again to bind with different credentials. +.TP +\fB::ldap::bindSASL\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? +This command uses SASL authentication mechanisms to do a multistage bind. +Its otherwise identical to the standard \fB::ldap::bind\fR. +This feature is currently experimental and subject to change. See the documentation +for the \fBSASL\fR and the "\fISASL.txt\fR" in the tcllib CVS repository for +details how to setup and use SASL with openldap. +.TP +\fB::ldap::unbind\fR \fIhandle\fR +This command asks the ldap server to release the last bind done for +the connection refered to by the token in \fIhandle\fR. +The \fIhandle\fR is invalid after the unbind, as the server closes the connection. +So this is effectivly just a more polite disconnect operation. +.TP +\fB::ldap::search\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR +This command performs a LDAP search below the \fIbaseObject\fR tree +using a complex LDAP search expression \fIfilterString\fR and returns +the specified \fIattributes\fR of all matching objects (DNs). If the +list of \fIattributes\fR was empty all attributes are returned. The +command blocks until it has received all results. +The valid \fIoptions\fR are identical to the options listed for \fB::ldap::searchInit\fR. +.sp +An example of a search expression is +.sp +.CS + + + set filterString "|(cn=Linus*)(sn=Torvalds*)" + +.CE +.sp +The return value of the command is a list of nested dictionaries. The +first level keys are object identifiers (DNs), second levels keys are +attribute names. In other words, it is in the form +.sp +.CS + + + {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ... + +.CE +.sp +.TP +\fB::ldap::searchInit\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR +This command initiates a LDAP search below the \fIbaseObject\fR tree +using a complex LDAP search expression \fIfilterString\fR. +The search gets the specified \fIattributes\fR of all matching objects (DNs). +The command itself just starts the search, to retrieve the actual results, use +\fB::ldap::searchNext\fR. +A search can be terminated at any time by +\fB::ldap::searchEnd\fR. This informs the server that no further results should be sent by sending and ABANDON message +and cleans up the internal state of the search. +Only one \fB::ldap::search\fR can be active at a given time, this +includes the introspection commands \fB::ldap::info saslmechanisms\fR, \fBldap::info control\fR and +\fBldap::info extensions\fR, which invoke a search internally. +Error responses from the server due to wrong arguments or similar things are returned +with the first \fB::ldap::searchNext\fR call and should be checked and dealed with there. +If the list of requested \fIattributes\fR is empty all attributes will be returned. +The parameter \fIoptions\fR specifies the options to be used in the search, +and has the following format: +.sp +.CS + + + {-option1 value1 -option2 value2 ... } + +.CE +.sp +Following options are available: +.RS +.TP +\fB-scope\fR base one sub +Control the scope of the search to be one of \fBbase\fR, \fBone\fR, or \fBsub\fR, to specify a base +object, one-level or subtree search. The default is \fBsub\fR. +.TP +\fB-derefaliases\fR never search find always +Control how aliases dereferencing is done. Should be one of \fBnever\fR, \fBalways\fR, \fBsearch\fR, or \fBfind\fR to +specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or +dereferenced only when locating the base object for the search. +The default is to never dereference aliases. +.TP +\fB-sizelimit\fR num +Determines the maximum number of entries to return in a search. If specified as +0 no limit is enforced. The server may enforce a configuration dependent sizelimit, +which may be lower than the one given by this option. The default is 0, no limit. +.TP +\fB-timelimit\fR seconds +Asks the server to use a timelimit of \fIseconds\fR for the search. Zero means no +limit. The default is 0, no limit. +.TP +\fB-attrsonly\fR boolean +If set to 1 only the attribute names but not the values will be present in the search result. +The default is to retrieve attribute names and values. +.TP +\fB-referencevar\fR varname +If set the search result reference LDAPURIs, if any, are returned in the given variable. +The caller can than decide to follow those references and query other LDAP servers for +further results. +.RE +.sp +.TP +\fB::ldap::searchNext\fR \fIhandle\fR +This command returns the next entry from a LDAP search initiated +by \fB::ldap::searchInit\fR. It returns only after a new result is received +or when no further results are available, but takes care to keep +the event loop alive. +The returned entry is a list with +two elements: the first is the DN of the entry, the second is the +list of attributes and values, under the format: +.sp +.CS + + + dn {attr1 {val11 val12 ...} attr2 {val21...} ...} + +.CE +.sp +The \fB::ldap::searchNext\fR command returns an empty list at the +end of the search. +.sp +.TP +\fB::ldap::searchEnd\fR \fIhandle\fR +This command terminates a LDAP search initiated +by \fB::ldap::searchInit\fR. It also cleans up +the internal state so a new search can be initiated. +If the client has not yet received all results, the client +sends an ABANDON message to inform the server that no +further results for the previous search should to be sent. +.sp +.TP +\fB::ldap::modify\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrToDelete\fR? ?\fIattrValToAdd\fR? +This command modifies the object \fIdn\fR on the ldap server we are +connected to via \fIhandle\fR. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are dictionaries mapping attribute names to values. The +optional arguments default to the empty dictionary, which means that +no attributes will be deleted nor added. +.RS +.TP +dictionary \fIattrValToReplace\fR (in) +No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +\fIreplace all\fR attributes known to the object. +.TP +dictionary \fIattrToDelete\fR (in) +No attributes will be deleted if this argument is empty. The +dictionary values are restrictions on the deletion. An attribute +listed here will be deleted if and only if its current value at the +server matches the value specified in the dictionary, or if the value +in the dictionary is the empty string. +.TP +dictionary \fIattrValToAdd\fR (in) +No attributes will be added if this argument is empty. The dictionary +values are the values for the new attributes. +.RE +.sp +The command blocks until all modifications have completed. Its result +is the empty string. +.TP +\fB::ldap::modifyMulti\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrValToDelete\fR? ?\fIattrValToAdd\fR? +This command modifies the object \fIdn\fR on the ldap server we are +connected to via \fIhandle\fR. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are lists with the format: +.sp +.CS + + + attr1 {val11 val12 ...} attr2 {val21...} ... + +.CE +.sp +where each value list may be empty for deleting all attributes. +The optional arguments default to empty lists of attributes to +delete and to add. +.RS +.TP +list \fIattrValToReplace\fR (in) +No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +\fIreplace all\fR attributes known to the object. +.TP +list \fIattrValToDelete\fR (in) +No attributes will be deleted if this argument is empty. If no +value is specified, the whole set of values for an attribute +will be deleted. +.TP +list \fIattrValToAdd\fR (in) +No attributes will be added if this argument is empty. +.RE +.sp +The command blocks until all modifications have completed. Its result +is the empty string. +.TP +\fB::ldap::add\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR +This command creates a new object using the specified \fIdn\fR. The +attributes of the new object are set to the values in the list +\fIattrValueTuples\fR. +Multiple valuated attributes may be specified using multiple tuples. +The command blocks until the operation has completed. Its result +is the empty string. +.TP +\fB::ldap::addMulti\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR +This command is the preferred one to create +a new object using the specified \fIdn\fR. The +attributes of the new object are set to the values in the dictionary +\fIattrValueTuples\fR (which is keyed by the attribute names). +Each tuple is a list containing multiple values. +The command blocks until the operation has completed. Its result +is the empty string. +.TP +\fB::ldap::delete\fR \fIhandle\fR \fIdn\fR +This command removes the object specified by \fIdn\fR, and all its +attributes from the server. +The command blocks until the operation has completed. Its result +is the empty string. +.TP +\fB::ldap::modifyDN\fR \fIhandle\fR \fIdn\fR \fInewrdn\fR ?\fIdeleteOld\fR? ?\fInewSuperior\fR? +] +This command moves or copies the object specified by \fIdn\fR +to a new location in the tree of object. This location is +specified by \fInewrdn\fR, a \fIrelative\fR designation, +or by \fInewrdn\fR and \fInewSuperior\fR, a \fIabsolute\fR designation. +The optional argument \fIdeleteOld\fR defaults to \fBtrue\fR, +i.e. a move operation. If \fIdeleteOld\fR is not set, then the +operation will create a copy of \fIdn\fR in the new location. +The optional argument \fInewSuperior\fR defaults an empty string, +meaning that the object must not be relocated in another branch of +the tree. If this argument is given, the argument \fIdeleteOld\fR +must be specified also. +The command blocks until the operation has completed. Its result +is the empty string. +.TP +\fB::ldap::info\fR \fBip\fR \fIhandle\fR +This command returns the IP address of the remote LDAP server the handle is connected to. +.TP +\fB::ldap::info\fR \fBbound\fR \fIhandle\fR +This command returns 1 if a handle has successfully completed a \fB::ldap::bind\fR. +If no bind was done or it failed, a 0 is returned. +.TP +\fB::ldap::info\fR \fBbounduser\fR \fIhandle\fR +This command returns the username used in the bind operation if a handle has successfully completed a \fB::ldap::bind\fR. +If no bound was done or it failed, an empty string is returned. +.TP +\fB::ldap::info\fR \fBconnections\fR +This command returns all currently existing ldap connection handles. +.TP +\fB::ldap::info\fR \fBtls\fR \fIhandle\fR +This command returns 1 if the ldap connection \fIhandle\fR used TLS/SSL for +connection via \fBldap::secure_connect\fR or completed \fBldap::starttls\fR, 0 otherwise. +.TP +\fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR +Return the supported SASL mechanisms advertised by the server. Only valid in a +bound state (anonymous or other). +.TP +\fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR +Return the supported controls advertised by the server as a list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change. +.TP +\fB::ldap::info\fR \fBextensions\fR \fIextensions\fR +Returns the supported LDAP extensions as list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change. +.TP +\fB::ldap::info\fR \fBwhoami\fR \fIhandle\fR +Returns authzId for the current connection. This implements the RFC 4532 +protocol extension. +.PP +.PP +.SH EXAMPLES +.PP +A small example, extracted from the test application coming with this +code. +.PP +.CS + + + package require ldap + + # Connect, bind, add a new object, modify it in various ways + + set handle [ldap::connect localhost 9009] + + set dn "cn=Manager, o=University of Michigan, c=US" + set pw secret + + ldap::bind $handle $dn $pw + + set dn "cn=Test User,ou=People,o=University of Michigan,c=US" + + ldap::add $handle $dn { + objectClass OpenLDAPperson + cn {Test User} + mail test.user@google.com + uid testuid + sn User + telephoneNumber +31415926535 + telephoneNumber +27182818285 + } + + set dn "cn=Another User,ou=People,o=University of Michigan,c=US" + + ldap::addMulti $handle $dn { + objectClass {OpenLDAPperson} + cn {{Anotther User}} + mail {test.user@google.com} + uid {testuid} + sn {User} + telephoneNumber {+31415926535 +27182818285} + } + + # Replace all attributes + ldap::modify $handle $dn [list drink icetea uid JOLO] + + # Add some more + ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"] + + # Delete + ldap::modify $handle $dn {} [list drink water pager ""] + + # Move + ldap::modifyDN $handle $dn "cn=Tester" + + # Kill the test object, and shut the connection down. + set dn "cn=Tester,ou=People,o=University of Michigan,c=US" + ldap::delete $handle $dn + + ldap::unbind $handle + ldap::disconnect $handle + +.CE +.PP +And a another example, a simple query, and processing the +results. +.PP +.CS + + + package require ldap + set handle [ldap::connect ldap.acme.com 389] + ldap::bind $handle + set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}] + foreach result $results { + foreach {object attributes} $result break + + # The processing here is similar to what 'parray' does. + # I.e. finding the longest attribute name and then + # generating properly aligned output listing all attributes + # and their values. + + set width 0 + set sortedAttribs {} + foreach {type values} $attributes { + if {[string length $type] > $width} { + set width [string length $type] + } + lappend sortedAttribs [list $type $values] + } + + puts "object='$object'" + + foreach sortedAttrib $sortedAttribs { + foreach {type values} $sortedAttrib break + foreach value $values { + regsub -all "\\[\\x01-\\x1f\\]" $value ? value + puts [format " %-${width}s %s" $type $value] + } + } + puts "" + } + ldap::unbind $handle + ldap::disconnect $handle + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIldap\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +One know bug is the usage of \fBvwait\fR inside the dispatch mechanism, which makes +it currently unsafe to use this code in code that also enters the event loop. +.SH KEYWORDS +directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc 4511, x.500 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2004 Jochen Loewer <loewerj@web.de> +Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/ldap/ldapx.n Index: embedded/man/files/modules/ldap/ldapx.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ldap/ldapx.n @@ -0,0 +1,952 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ldap/ldapx.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Pierre David <pdav@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ldapx" n 0.2.5 tcllib "LDAP extended object interface" +.BS +.SH NAME +ldapx \- LDAP extended object interface +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBldapx ?1.0?\fR +.sp +\fIe\fR \fBreset\fR +.sp +\fIe\fR \fBdn\fR ?\fInewdn\fR? +.sp +\fIe\fR \fBrdn\fR +.sp +\fIe\fR \fBsuperior\fR +.sp +\fIe\fR \fBprint\fR +.sp +\fIse\fR \fBisempty\fR +.sp +\fIse\fR \fBget\fR \fIattr\fR +.sp +\fIse\fR \fBget1\fR \fIattr\fR +.sp +\fIse\fR \fBset\fR \fIattr\fR \fIvalues\fR +.sp +\fIse\fR \fBset1\fR \fIattr\fR \fIvalue\fR +.sp +\fIse\fR \fBadd\fR \fIattr\fR \fIvalues\fR +.sp +\fIse\fR \fBadd1\fR \fIattr\fR \fIvalue\fR +.sp +\fIse\fR \fBdel\fR \fIattr\fR ?\fIvalues\fR? +.sp +\fIse\fR \fBdel1\fR \fIattr\fR \fIvalue\fR +.sp +\fIse\fR \fBgetattr\fR +.sp +\fIse\fR \fBgetall\fR +.sp +\fIse\fR \fBsetall\fR \fIavpairs\fR +.sp +\fIse\fR \fBbackup\fR ?\fIother\fR? +.sp +\fIse\fR \fBswap\fR +.sp +\fIse\fR \fBrestore\fR ?\fIother\fR? +.sp +\fIse\fR \fBapply\fR \fIcentry\fR +.sp +\fIce\fR \fBchange\fR ?\fInew\fR? +.sp +\fIce\fR \fBdiff\fR \fInew\fR ?\fIold\fR? +.sp +\fIla\fR \fBerror\fR ?\fInewmsg\fR? +.sp +\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? +.sp +\fIla\fR \fBdisconnect\fR +.sp +\fIla\fR \fBtraverse\fR \fIbase\fR \fIfilter\fR \fIattrs\fR \fIentry\fR \fIbody\fR +.sp +\fIla\fR \fBsearch\fR \fIbase\fR \fIfilter\fR \fIattrs\fR +.sp +\fIla\fR \fBread\fR \fIbase\fR \fIfilter\fR \fIentry\fR ... \fIentry\fR +.sp +\fIla\fR \fBcommit\fR \fIentry\fR ... \fIentry\fR +.sp +\fIli\fR \fBchannel\fR \fIchan\fR +.sp +\fIli\fR \fBerror\fR ?\fInewmsg\fR? +.sp +\fIli\fR \fBread\fR \fIentry\fR +.sp +\fIli\fR \fBwrite\fR \fIentry\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBldapx\fR package provides an extended Tcl interface to +LDAP directores and LDIF files. The \fBldapx\fR package is built +upon the \fBldap\fR package in order to get low level LDAP access. +.PP +LDAP access is compatible with RFC 2251 +(\fIhttp://www.rfc-editor.org/rfc/rfc2251.txt\fR). +LDIF access is compatible with RFC 2849 +(\fIhttp://www.rfc-editor.org/rfc/rfc2849.txt\fR). +.SH OVERVIEW +The \fBldapx\fR package provides objects to interact with LDAP +directories and LDIF files with an easy to use programming interface. +It implements three \fBsnit\fR::type classes. +.PP +The first class, \fBentry\fR, is used to store individual entries. +Two different formats are available: the first one is the +\fIstandard\fR format, which represents an entry as read from the +directory. The second format is the \fIchange\fR format, which +stores differences between two standard entries. +.PP +With these entries, an application which wants to modify an entry +in a directory needs to read a (standard) entry from the directory, +create a fresh copy into a new (standard) entry, modify the new +copy, and then compute the differences between the two entries into +a new (change) entry, which may be commited to the directory. +.PP +Such kinds of modifications are so heavily used that standard entries +may contain their own copy of the original data. With such a copy, +the application described above reads a (standard) entry from the +directory, backs-up the original data, modifies the entry, and +computes the differences between the entry and its backup. These +differences are then commited to the directory. +.PP +Methods are provided to compute differences between two entries, +to apply differences to an entry in order to get a new entry, and +to get or set attributes in standard entries. +.PP +The second class is the \fBldap\fR class. It provides a method +to \fBconnect\fR and bind to the directory with a uniform access +to LDAP and LDAPS through an URL (ldap:// or ldaps://). The +\fBtraverse\fR control structure executes a body for each entry +found in the directory. The \fBcommit\fR method applies some +changes (represented as \fBentry\fR objects) to the directory. +Since some attributes are represented as UTF-8 strings, the option +\fB-utf8\fR controls which attributes must be converted and +which attributes must not be converted. +.PP +The last class is the \fBldif\fR class. It provides a method to +associate a standard Tcl \fIchannel\fR to an LDIF object. Then, +methods \fBread\fR and \fBwrite\fR read or write entries from +or to this channel. This class can make use of standard or change +entries, according to the type of the LDIF file which may contain +either standard entries or change entries (but not both at the same +time). The option \fB-utf8\fR works exactly as with the +\fBldap\fR class. +.SH "ENTRY CLASS" +.SS "ENTRY INSTANCE DATA" +An instance of the \fBentry\fR class keeps the following data: +.TP +dn +This is the DN of the entry, which includes (in LDAP +terminology) the RDN (relative DN) and the Superior parts. +.TP +format +The format may be \fIuninitialized\fR (entry not yet used), +\fIstandard\fR or \fIchange\fR. Most methods check the +format of the entry, which can be reset with the +\fBreset\fR method. +.TP +attrvals +In a \fIstandard\fR entry, this is where the attributes +and associated values are stored. Many methods provide +access to these informations. Attribute names are always +converted into lower case. +.TP +backup +In a \fIstandard\fR entry, the backup may contain a copy +of the dn and all attributes and values. Methods +\fBbackup\fR and \fBrestore\fR manipulate these data, +and method \fBdiff\fR may use this backup. +.TP +change +In a \fIchange\fR entry, these data represent the +modifications. Such modifications are handled by specialized +methods such as \fBapply\fR or \fBcommit\fR. +Detailed format should not be used directly by programs. +.sp +Internally, modifications are represented as a list of +elements, each element has one of the following formats +(which match the corresponding LDAP operations): +.RS +.IP [1] +{\fBadd\fR {attr1 {val1...valn} attr2 {...} ...}} +.sp +Addition of a new entry. +.IP [2] +{\fBmod\fR {modop {attr1 ?val1...valn?} attr2 ...} {modop ...} ...} +.sp +Modification of one or more attributes and/or values, +where <modop> can be \fBmodadd\fR, \fBmoddel\fR +or \fBmodrepl\fR (see the LDAP modify operation). +.IP [3] +{\fBdel\fR} +.sp +Deletion of an old entry. +.IP [4] +{\fBmodrdn\fR newrdn deleteoldrdn ?newsuperior?} +.sp +Renaming of an entry. +.RE +.PP +.SS "ENTRY OPTIONS" +No option is defined by this class. +.SS "METHODS FOR ALL KINDS OF ENTRIES" +.TP +\fIe\fR \fBreset\fR +This method resets the entry to an uninitialized state. +.TP +\fIe\fR \fBdn\fR ?\fInewdn\fR? +This method returns the current DN of the entry. If the +optional \fInewdn\fR is specified, it replaces the current +DN of the entry. +.TP +\fIe\fR \fBrdn\fR +This method returns the RDN part of the DN of the entry. +.TP +\fIe\fR \fBsuperior\fR +This method returns the superior part of the DN of the entry. +.TP +\fIe\fR \fBprint\fR +This method returns the entry as a string ready to be printed. +.PP +.PP +.SS "METHODS FOR STANDARD ENTRIES ONLY" +In all methods, attribute names are converted in lower case. +.TP +\fIse\fR \fBisempty\fR +This method returns 1 if the entry is empty (i.e. without +any attribute). +.TP +\fIse\fR \fBget\fR \fIattr\fR +This method returns all values of the attribute \fIattr\fR, +or the empty list if the attribute is not fond. +.TP +\fIse\fR \fBget1\fR \fIattr\fR +This method returns the first value of the attribute. +.TP +\fIse\fR \fBset\fR \fIattr\fR \fIvalues\fR +This method sets the values (list \fIvalues\fR) of the +attribute \fIattr\fR. If the list is empty, this method +deletes all +.TP +\fIse\fR \fBset1\fR \fIattr\fR \fIvalue\fR +This method sets the values of the attribute \fIattr\fR to +be an unique value \fIvalue\fR. Previous values, if any, +are replaced by the new value. +.TP +\fIse\fR \fBadd\fR \fIattr\fR \fIvalues\fR +This method adds all elements the list \fIvalues\fR to the +values of the attribute \fIattr\fR. +.TP +\fIse\fR \fBadd1\fR \fIattr\fR \fIvalue\fR +This method adds a single value given by the parameter +\fIvalue\fR to the attribute \fIattr\fR. +.TP +\fIse\fR \fBdel\fR \fIattr\fR ?\fIvalues\fR? +If the optional list \fIvalues\fR is specified, this method +deletes all specified values from the attribute \fIattr\fR. +If the argument \fIvalues\fR is not specified, this method +deletes all values. +.TP +\fIse\fR \fBdel1\fR \fIattr\fR \fIvalue\fR +This method deletes a unique \fIvalue\fR from the attribute +\fIattr\fR. +.TP +\fIse\fR \fBgetattr\fR +This method returns all attributes names. +.TP +\fIse\fR \fBgetall\fR +This method returns all attributes and values from the +entry, packed in a list of pairs <attribute, list of values>. +.TP +\fIse\fR \fBsetall\fR \fIavpairs\fR +This method sets at once all attributes and values. The +format of the \fIavpairs\fR argument is the same as the one +returned by method \fBgetall\fR. +.TP +\fIse\fR \fBbackup\fR ?\fIother\fR? +This method stores in an \fIother\fR standard entry object +a copy of the current DN and attributes/values. If the +optional \fIother\fR argument is not specified, copy is +done in the current entry (in a specific place, see section +\fBOVERVIEW\fR). +.TP +\fIse\fR \fBswap\fR +This method swaps the current and backup contexts of the +entry. +.TP +\fIse\fR \fBrestore\fR ?\fIother\fR? +If the optional argument \fIother\fR is given, which must +then be a \fIstandard\fR entry, this method restores the +current entry into the \fIother\fR entry. If the argument +\fIother\fR argument is not specified, this methods restores +the current entry from its internal backup (see section +\fBOVERVIEW\fR). +.TP +\fIse\fR \fBapply\fR \fIcentry\fR +This method applies changes defined in the \fIcentry\fR +argument, which must be a \fIchange\fR entry. +.PP +.SS "METHODS FOR CHANGE ENTRIES ONLY" +.TP +\fIce\fR \fBchange\fR ?\fInew\fR? +If the optional argument \fInew\fR is specified, this method +modifies the change list (see subsection \fBEntry Instance Data\fR for +the exact format). In both cases, current change list is +returned. +Warning: values returned by this method should only be used +by specialized methods such as \fBapply\fR or +\fBcommit\fR. +.TP +\fIce\fR \fBdiff\fR \fInew\fR ?\fIold\fR? +This method computes the differences between the \fInew\fR +and \fIold\fR entries under the form of a change list, and +stores this list into the current \fIchange\fR entry. If +the optional argument \fIold\fR is not specified, difference +is computed from the entry and its internal backup (see +section \fBOVERVIEW\fR). Return value is the computed +change list. +.PP +.SS "ENTRY EXAMPLE" +.CS + + + package require ldapx + + # + # Create an entry and fill it as a standard entry with + # attributes and values + # + ::ldapx::entry create e + e dn "uid=joe,ou=people,o=mycomp" + e set1 "uid" "joe" + e set "objectClass" {person anotherObjectClass} + e set1 "givenName" "Joe" + e set1 "sn" "User" + e set "telephoneNumber" {+31415926535 +2182818} + e set1 "anotherAttr" "This is a beautiful day, isn't it?" + + puts stdout "e\\n[e print]" + + # + # Create a second entry as a backup of the first, and + # make some changes on it. + # Entry is named automatically by snit. + # + + set b [::ldapx::entry create %AUTO%] + e backup $b + + puts stdout "$b\\n[$b print]" + + $b del "anotherAttr" + $b del1 "objectClass" "anotherObjectClass" + + # + # Create a change entry, a compute differences between first + # and second entry. + # + + ::ldapx::entry create c + c diff e $b + + puts stdout "$c\\n[$c print]" + + # + # Apply changes to first entry. It should be the same as the + # second entry, now. + # + + e apply c + + ::ldapx::entry create nc + nc diff e $b + + puts stdout "nc\\n[nc print]" + + # + # Clean-up + # + + e destroy + $b destroy + c destroy + nc destroy + +.CE +.SH "LDAP CLASS" +.SS "LDAP INSTANCE DATA" +An instance of the \fBldap\fR class keeps the following data: +.TP +channel +This is the channel used by the \fBldap\fR package for +communication with the LDAP server. +.TP +lastError +This variable contains the error message which appeared in +the last method of the \fBldap\fR class (this string is +modified in nearly all methods). The \fBerror\fR method +may be used to fetch this message. +.PP +.SS "LDAP OPTIONS" +A first set of options of the \fBldap\fR class is used during +search operations (methods \fBtraverse\fR, \fBsearch\fR and +\fBread\fR, see below). +.TP +\fB-scope\fR \fBbase\fR|\fBone\fR|\fBsub\fR +Specify the scope of the LDAP search to be one of +\fBbase\fR, \fBone\fR or \fBsub\fR to specify +a base object, one-level or subtree search. +.sp +The default is \fBsub\fR. +.TP +\fB-derefaliases\fR \fBnever\fR|\fBseach\fR|\fBfind\fR|\fBalways\fR +Specify how aliases dereferencing is handled: +\fBnever\fR is used to specify that aliases are never derefenced, +\fBalways\fR that aliases are always derefenced, +\fBsearch\fR that aliases are dereferenced when searching, +or \fBfind\fR that aliases are dereferenced only when +locating the base object for the search. +.sp +The default is \fBnever\fR. +.TP +\fB-sizelimit\fR integer +Specify the maximum number of entries to be retreived +during a search. A value of \fB0\fR means no limit. +.sp +Default is \fB0\fR. +.TP +\fB-timelimit\fR integer +Specify the time limit for a search to complete. +A value of \fB0\fR means no limit. +.sp +Default is \fB0\fR. +.TP +\fB-attrsonly\fR \fB0\fR|\fB1\fR +Specify if only attribute names are to be retrieved (value +\fB1\fR). Normally (value \fB0\fR), attribute values +are also retrieved. +.sp +Default is \fB0\fR. +.PP +.PP +The last option is used when getting entries or committing changes +in the directory: +.TP +\fB-utf8\fR pattern-yes pattern-no +Specify which attribute values are encoded in UTF-8. This +information is specific to the LDAP schema in use by the +application, since some attributes such as jpegPhoto, for +example, are not encoded in UTF-8. This option takes the +form of a list with two regular expressions suitable for +the \fBregexp\fR command (anchored by ^ and $). +The first specifies which attribute names are to be UTF-8 +encoded, and the second selects, among those, the attribute +names which will not be UTF-8 encoded. It is thus possible +to say: convert all attributes, except jpegPhoto. +.sp +Default is {{.*} {}}, meaning: all attributes are converted, +without exception. +.PP +.SS "LDAP METHODS" +.TP +\fIla\fR \fBerror\fR ?\fInewmsg\fR? +This method returns the error message that occurred in the +last call to a \fBldap\fR class method. If the optional +argument \fInewmsg\fR is supplied, it becomes the last +error message. +.TP +\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? +This method connects to the LDAP server using given URL +(which can be of the form \fIldap://host:port\fR or +\fIldaps://host:port\fR). If an optional \fIbinddn\fR +argument is given together with the \fIbindpw\fR argument, +the \fBconnect\fR binds to the LDAP server using the +specified DN and password. +.TP +\fIla\fR \fBdisconnect\fR +This method disconnects (and unbinds, if necessary) from +the LDAP server. +.TP +\fIla\fR \fBtraverse\fR \fIbase\fR \fIfilter\fR \fIattrs\fR \fIentry\fR \fIbody\fR +This method is a new control structure. It searches the +LDAP directory from the specified base DN (given by the +\fIbase\fR argument) and selects entries based on the +argument \fIfilter\fR. For each entry found, this method +fetches attributes specified by the \fIattrs\fR argument +(or all attributes if it is an empty list), stores them in +the \fIentry\fR instance of class \fBentry\fR and executes +the script defined by the argument \fIbody\fR. Options are +used to refine the search. +.sp +Caution: when this method is used, the script \fIbody\fR +cannot perform another LDAP search (methods \fBtraverse\fR, +\fBsearch\fR or \fBread\fR). +.TP +\fIla\fR \fBsearch\fR \fIbase\fR \fIfilter\fR \fIattrs\fR +This method searches the directory using the same way as +method \fBtraverse\fR. All found entries are stored in +newly created instances of class \fBentry\fR, which are +returned in a list. The newly created instances should be +destroyed when they are no longer used. +.TP +\fIla\fR \fBread\fR \fIbase\fR \fIfilter\fR \fIentry\fR ... \fIentry\fR +This method reads one or more entries, using the same search +criteria as methods \fBtraverse\fR and \fBsearch\fR. +All attributes are stored in the entries. This method +provides a quick way to read some entries. It returns the +number of entries found in the directory (which may be more +than the number of read entries). If called without any +\fIentry\fR argument, this method just returns the number +of entries found, without returning any data. +.TP +\fIla\fR \fBcommit\fR \fIentry\fR ... \fIentry\fR +This method commits the changes stored in the \fIentry\fR +arguments. Each \fIentry\fR may be either a \fIchange\fR +entry, or a \fIstandard\fR entry with a backup. +.sp +Note: in the future, this method should use the LDAP +transaction extension provided by OpenLDAP 2.3 and later. +.PP +.SS "LDAP EXAMPLE" +.CS + + + package require ldapx + + # + # Connects to the LDAP directory + # + + ::ldapx::ldap create l + set url "ldap://server.mycomp.com" + if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then { + puts stderr "error: [l error]" + exit 1 + } + + # + # Search all entries matching some criterion + # + + l configure -scope one + ::ldapx::ldap create e + set n 0 + l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e { + puts "dn: [e dn]" + puts " sn: [e get1 sn]" + puts " givenName: [e get1 givenName]" + incr n + } + puts "$n entries found" + e destroy + + # + # Add a telephone number to some entries + # Note this modification cannot be done in the "traverse" operation. + # + + set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}] + ::ldapx::ldap create c + foreach e $lent { + $e backup + $e add1 "telephoneNumber" "+31415926535" + c diff $e + if {! [l commit c]} then { + puts stderr "error: [l error]" + exit 1 + } + $e destroy + } + + l disconnect + l destroy + +.CE +.SH "LDIF CLASS" +.SS "LDIF INSTANCE DATA" +An instance of the \fBldif\fR class keeps the following data: +.TP +channel +This is the Tcl channel used to retrieve or store LDIF file +contents. The association between an instance and a channel +is made by the method \fBchannel\fR. There is no need +to disrupt this association when the LDIF file operation +has ended. +.TP +format +LDIF files may contain \fIstandard\fR entries or +\fIchange\fR entries, but not both. This variable contains +the detected format of the file (when reading) or the format +of entries written to the file (when writing). +.TP +lastError +This variable contains the error message which appeared in +the last method of the \fBldif\fR class (this string is +modified in nearly all methods). The \fBerror\fR method +may be used to fetch this message. +.TP +version +This is the version of the LDIF file. Only version 1 is +supported: the method \fBread\fR can only read from +version 1 files, and method \fBwrite\fR only creates +version 1 files. +.PP +.SS "LDIF OPTIONS" +This class defines two options: +.TP +\fB-ignore\fR list-of-attributes +This option is used to ignore certain attribute names on +reading. For example, to read OpenLDAP replica files (replog), +one must ignore \fBreplica\fR and \fBtime\fR attributes +since they do not conform to the RFC 2849 standard for LDIF +files. +.sp +Default is empty list: no attribute is ignored. +.TP +\fB-utf8\fR pattern-yes pattern-no +Specify which attribute values are encoded in UTF-8. This +information is specific to the LDAP schema in use by the +application, since some attributes such as jpegPhoto, for +example, are not encoded in UTF-8. This option takes the +form of a list with two regular expressions suitable for +the \fBregexp\fR command (anchored by ^ and $). +The first specifies which attribute names are to be UTF-8 +encoded, and the second selects, among those, the attribute +names which will not be UTF-8 encoded. It is thus possible +to say: convert all attributes, except jpegPhoto. +.sp +Default is {{.*} {}}, meaning: all attributes are converted, +without exception. +.PP +.SS "LDIF METHODS" +.TP +\fIli\fR \fBchannel\fR \fIchan\fR +This method associates the Tcl channel named \fIchan\fR +with the LDIF instance. It resets the type of LDIF object +to \fIuninitialized\fR. +.TP +\fIli\fR \fBerror\fR ?\fInewmsg\fR? +This method returns the error message that occurred in the +last call to a \fBldif\fR class method. If the optional +argument \fInewmsg\fR is supplied, it becomes the last +error message. +.TP +\fIli\fR \fBread\fR \fIentry\fR +This method reads the next entry from the LDIF file and +stores it in the \fIentry\fR object of class \fBentry\fR. +The entry may be a \fIstandard\fR or \fIchange\fR entry. +.TP +\fIli\fR \fBwrite\fR \fIentry\fR +This method writes the entry given in the argument +\fIentry\fR to the LDIF file. +.PP +.SS "LDIF EXAMPLE" +.CS + + + package require ldapx + + # This examples reads a LDIF file containing entries, + # compare them to a LDAP directory, and writes on standard + # output an LDIF file containing changes to apply to the + # LDAP directory to match exactly the LDIF file. + + ::ldapx::ldif create liin + liin channel stdin + + ::ldapx::ldif create liout + liout channel stdout + + ::ldapx::ldap create la + if {! [la connect "ldap://server.mycomp.com"]} then { + puts stderr "error: [la error]" + exit 1 + } + la configure -scope one + + # Reads LDIF file + + ::ldapx::entry create e1 + ::ldapx::entry create e2 + ::ldapx::entry create c + + while {[liin read e1] != 0} { + set base [e1 superior] + set id [e1 rdn] + if {[la read $base "($id)" e2] == 0} then { + e2 reset + } + + c diff e1 e2 + if {[llength [c change]] != 0} then { + liout write c + } + } + + la disconnect + la destroy + e1 destroy + e2 destroy + c destroy + liout destroy + liin destroy + +.CE +.SH REFERENCES +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIldap\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +directory access, internet, ldap, ldap client, ldif, protocol, rfc 2251, rfc 2849 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2006 Pierre David <pdav@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/log/log.n Index: embedded/man/files/modules/log/log.n ================================================================== --- /dev/null +++ embedded/man/files/modules/log/log.n @@ -0,0 +1,533 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/log/log.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "log" n 1.3 tcllib "Logging facility" +.BS +.SH NAME +log \- Procedures to log messages of libraries and applications. +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBlog ?1.3?\fR +.sp +\fB::log::levels\fR +.sp +\fB::log::lv2longform\fR \fIlevel\fR +.sp +\fB::log::lv2color\fR \fIlevel\fR +.sp +\fB::log::lv2priority\fR \fIlevel\fR +.sp +\fB::log::lv2cmd\fR \fIlevel\fR +.sp +\fB::log::lv2channel\fR \fIlevel\fR +.sp +\fB::log::lvCompare\fR \fIlevel1\fR \fIlevel2\fR +.sp +\fB::log::lvSuppress\fR \fIlevel\fR {\fIsuppress\fR 1} +.sp +\fB::log::lvSuppressLE\fR \fIlevel\fR {\fIsuppress\fR 1} +.sp +\fB::log::lvIsSuppressed\fR \fIlevel\fR +.sp +\fB::log::lvCmd\fR \fIlevel\fR \fIcmd\fR +.sp +\fB::log::lvCmdForall\fR \fIcmd\fR +.sp +\fB::log::lvChannel\fR \fIlevel\fR \fIchan\fR +.sp +\fB::log::lvChannelForall\fR \fIchan\fR +.sp +\fB::log::lvColor\fR \fIlevel\fR \fIcolor\fR +.sp +\fB::log::lvColorForall\fR \fIcolor\fR +.sp +\fB::log::log\fR \fIlevel\fR \fItext\fR +.sp +\fB::log::logarray\fR \fIlevel\fR \fIarrayvar\fR ?\fIpattern\fR? +.sp +\fB::log::loghex\fR \fIlevel\fR \fItext\fR \fIdata\fR +.sp +\fB::log::logMsg\fR \fItext\fR +.sp +\fB::log::logError\fR \fItext\fR +.sp +\fB::log::Puts\fR \fIlevel\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBlog\fR package provides commands that allow libraries and +applications to selectively log information about their internal +operation and state. +.PP +To use the package just execute +.PP +.CS + + + package require log + log::log notice "Some message" + +.CE +.PP +As can be seen above, each message given to the log facility is +associated with a \fIlevel\fR determining the importance of the +message. The user can then select which levels to log, what commands +to use for the logging of each level and the channel to write the +message to. In the following example the logging of all message with +level \fBdebug\fR is deactivated. +.PP +.CS + + + package require log + log::lvSuppress debug + log::log debug "Unseen message" ; # No output + +.CE +.PP +By default all messages associated with an error-level +(\fBemergency\fR, \fBalert\fR, \fBcritical\fR, and +\fBerror\fR) are written to \fBstderr\fR. Messages with any +other level are written to \fBstdout\fR. In the following example +the log module is reconfigured to write \fBdebug\fR messages to +\fBstderr\fR too. +.PP +.CS + + + package require log + log::lvChannel debug stderr + log::log debug "Written to stderr" + +.CE +.PP +Each message level is also associated with a command to use when +logging a message with that level. The behaviour above for example +relies on the fact that all message levels use by default the standard +command \fB::log::Puts\fR to log any message. In the following example +all messages of level \fBnotice\fR are given to the non-standard +command \fBtoText\fR for logging. This disables the channel setting +for such messages, assuming that \fBtoText\fR does not use it by +itself. +.PP +.CS + + + package require log + log::lvCmd notice toText + log::log notice "Handled by \\"toText\\"" + +.CE +.PP +Another database maintained by this facility is a map from message +levels to colors. The information in this database has \fIno\fR +influence on the behaviour of the module. It is merely provided as a +convenience and in anticipation of the usage of this facility in +\fBtk\fR-based application which may want to colorize message +logs. +.SH API +.PP +The following commands are available: +.TP +\fB::log::levels\fR +Returns the names of all known levels, in alphabetical order. +.TP +\fB::log::lv2longform\fR \fIlevel\fR +Converts any unique abbreviation of a level name to the full level +name. +.TP +\fB::log::lv2color\fR \fIlevel\fR +Converts any level name including unique abbreviations to the +corresponding color. +.TP +\fB::log::lv2priority\fR \fIlevel\fR +Converts any level name including unique abbreviations to the +corresponding priority. +.TP +\fB::log::lv2cmd\fR \fIlevel\fR +Converts any level name including unique abbreviations to the command +prefix used to write messages with that level. +.TP +\fB::log::lv2channel\fR \fIlevel\fR +Converts any level name including unique abbreviations to the channel +used by \fB::log::Puts\fR to write messages with that level. +.TP +\fB::log::lvCompare\fR \fIlevel1\fR \fIlevel2\fR +Compares two levels (including unique abbreviations) with respect to +their priority. This command can be used by the -command option of +lsort. The result is one of -1, 0 or 1 or an error. A result of -1 +signals that level1 is of less priority than level2. 0 signals that +both levels have the same priority. 1 signals that level1 has higher +priority than level2. +.TP +\fB::log::lvSuppress\fR \fIlevel\fR {\fIsuppress\fR 1} +] +(Un)suppresses the output of messages having the specified +level. Unique abbreviations for the level are allowed here too. +.TP +\fB::log::lvSuppressLE\fR \fIlevel\fR {\fIsuppress\fR 1} +] +(Un)suppresses the output of messages having the specified level or +one of lesser priority. Unique abbreviations for the level are allowed +here too. +.TP +\fB::log::lvIsSuppressed\fR \fIlevel\fR +Asks the package whether the specified level is currently +suppressed. Unique abbreviations of level names are allowed. +.TP +\fB::log::lvCmd\fR \fIlevel\fR \fIcmd\fR +Defines for the specified level with which command to write the +messages having this level. Unique abbreviations of level names are +allowed. The command is actually a command prefix and this facility +will append 2 arguments before calling it, the level of the message +and the message itself, in this order. +.TP +\fB::log::lvCmdForall\fR \fIcmd\fR +Defines for all known levels with which command to write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order. +.TP +\fB::log::lvChannel\fR \fIlevel\fR \fIchan\fR +Defines for the specified level into which channel \fB::log::Puts\fR +(the standard command) shall write the messages having this +level. Unique abbreviations of level names are allowed. The command is +actually a command prefix and this facility will append 2 arguments +before calling it, the level of the message and the message itself, in +this order. +.TP +\fB::log::lvChannelForall\fR \fIchan\fR +Defines for all known levels with which which channel +\fB::log::Puts\fR (the standard command) shall write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order. +.TP +\fB::log::lvColor\fR \fIlevel\fR \fIcolor\fR +Defines for the specified level the color to return for it in a call +to \fB::log::lv2color\fR. Unique abbreviations of level names are +allowed. +.TP +\fB::log::lvColorForall\fR \fIcolor\fR +Defines for all known levels the color to return for it in a call to +\fB::log::lv2color\fR. Unique abbreviations of level names are +allowed. +.TP +\fB::log::log\fR \fIlevel\fR \fItext\fR +Log a message according to the specifications for commands, channels +and suppression. In other words: The command will do nothing if the +specified level is suppressed. If it is not suppressed the actual +logging is delegated to the specified command. If there is no command +specified for the level the message won't be logged. The standard +command \fB::log::Puts\fR will write the message to the channel +specified for the given level. If no channel is specified for the +level the message won't be logged. Unique abbreviations of level names +are allowed. Errors in the actual logging command are \fInot\fR +caught, but propagated to the caller, as they may indicate +misconfigurations of the log facility or errors in the callers code +itself. +.TP +\fB::log::logarray\fR \fIlevel\fR \fIarrayvar\fR ?\fIpattern\fR? +Like \fB::log::log\fR, but logs the contents of the specified array +variable \fIarrayvar\fR, possibly restricted to entries matching the +\fIpattern\fR. The pattern defaults to \fB*\fR (i.e. all entries) if +none was specified. +.TP +\fB::log::loghex\fR \fIlevel\fR \fItext\fR \fIdata\fR +Like \fB::log::log\fR, but assumes that \fIdata\fR contains binary +data. It converts this into a mixed hex/ascii representation before +writing them to the log. +.TP +\fB::log::logMsg\fR \fItext\fR +Convenience wrapper around \fB::log::log\fR. +Equivalent to \fB::log::log info text\fR. +.TP +\fB::log::logError\fR \fItext\fR +Convenience wrapper around \fB::log::log\fR. +Equivalent to \fB::log::log error text\fR. +.TP +\fB::log::Puts\fR \fIlevel\fR \fItext\fR +The standard log command, it writes messages and their levels to +user-specified channels. Assumes that the suppression checks were done +by the caller. Expects full level names, abbreviations are +\fInot allowed\fR. +.PP +.SH LEVELS +The package currently defines the following log levels, the level of +highest importance listed first. +.IP \(bu +emergency +.IP \(bu +alert +.IP \(bu +critical +.IP \(bu +error +.IP \(bu +warning +.IP \(bu +notice +.IP \(bu +info +.IP \(bu +debug +.PP +\fINote\fR that by default all messages with levels \fBwarning\fR down to +\fBdebug\fR are suppressed. This is done intentionally, because (we believe +that) in most situations debugging output is not wanted. Most people wish to +have such output only when actually debugging an application. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIlog\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +log, log level, message, message level +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/log/logger.n Index: embedded/man/files/modules/log/logger.n ================================================================== --- /dev/null +++ embedded/man/files/modules/log/logger.n @@ -0,0 +1,686 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/log/logger.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "logger" n 0.9.3 tcllib "Object Oriented logging facility" +.BS +.SH NAME +logger \- System to control logging of events. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBlogger ?0.9.3?\fR +.sp +\fBlogger::init\fR \fIservice\fR +.sp +\fBlogger::import\fR ?\fB-all\fR? ?\fB-force\fR? ?\fB-prefix\fR \fIprefix\fR? ?\fB-namespace\fR \fInamespace\fR? \fIservice\fR +.sp +\fBlogger::initNamespace\fR \fIns\fR ?\fIlevel\fR? +.sp +\fBlogger::services\fR +.sp +\fBlogger::enable\fR \fIlevel\fR +.sp +\fBlogger::disable\fR \fIlevel\fR +.sp +\fBlogger::setlevel\fR \fIlevel\fR +.sp +\fBlogger::levels\fR +.sp +\fBlogger::servicecmd\fR \fIservice\fR +.sp +\fB${log}::debug\fR \fImessage\fR +.sp +\fB${log}::info\fR \fImessage\fR +.sp +\fB${log}::notice\fR \fImessage\fR +.sp +\fB${log}::warn\fR \fImessage\fR +.sp +\fB${log}::error\fR \fImessage\fR +.sp +\fB${log}::critical\fR \fImessage\fR +.sp +\fB${log}::alert\fR \fImessage\fR +.sp +\fB${log}::emergency\fR \fImessage\fR +.sp +\fB${log}::setlevel\fR \fIlevel\fR +.sp +\fB${log}::enable\fR \fIlevel\fR +.sp +\fB${log}::disable\fR \fIlevel\fR +.sp +\fB${log}::lvlchangeproc\fR \fIcommand\fR +.sp +\fB${log}::lvlchangeproc\fR +.sp +\fB${log}::logproc\fR \fIlevel\fR +.sp +\fB${log}::logproc\fR \fIlevel\fR \fIcommand\fR +.sp +\fB${log}::logproc\fR \fIlevel\fR \fIargname\fR \fIbody\fR +.sp +\fB${log}::services\fR +.sp +\fB${log}::servicename\fR +.sp +\fB${log}::currentloglevel\fR +.sp +\fB${log}::delproc\fR \fIcommand\fR +.sp +\fB${log}::delproc\fR +.sp +\fB${log}::delete\fR +.sp +\fB${log}::trace\fR \fIcommand\fR +.sp +\fB${log}::trace\fR \fBon\fR +.sp +\fB${log}::trace\fR \fBoff\fR +.sp +\fB${log}::trace\fR \fBstatus\fR ?procName? ?...? +.sp +\fB${log}::trace\fR \fBadd\fR \fIprocName\fR ?...? +.sp +\fB${log}::trace\fR \fBadd\fR ?-ns? \fInsName\fR ?...? +.sp +\fB${log}::trace\fR \fBremove\fR \fIprocName\fR ?...? +.sp +\fB${log}::trace\fR \fBremove\fR ?-ns? \fInsName\fR ?...? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBlogger\fR package provides a flexible system for logging messages +from different services, at priority levels, with different commands. +.PP +To begin using the logger package, we do the following: +.PP +.CS + + + package require logger + set log [logger::init myservice] + ${log}::notice "Initialized myservice logging" + + ... code ... + + ${log}::notice "Ending myservice logging" + ${log}::delete + +.CE +.PP +In the above code, after the package is loaded, the following things +happen: +.TP +\fBlogger::init\fR \fIservice\fR +Initializes the service \fIservice\fR for logging. The service names +are actually Tcl namespace names, so they are separated with '::'. +The service name may not be the empty string or only ':'s. +When a logger service is initialized, it "inherits" properties from its +parents. For instance, if there were a service \fIfoo\fR, and +we did a \fBlogger::init\fR \fIfoo::bar\fR (to create a \fIbar\fR +service underneath \fIfoo\fR), \fIbar\fR would copy the current +configuration of the \fIfoo\fR service, although it would of +course, also be possible to then separately configure \fIbar\fR. +If a logger service is initialized and the parent does not yet exist, the +parent is also created. +The new logger service is initialized with the default loglevel set +with \fBlogger::setlevel\fR. +.TP +\fBlogger::import\fR ?\fB-all\fR? ?\fB-force\fR? ?\fB-prefix\fR \fIprefix\fR? ?\fB-namespace\fR \fInamespace\fR? \fIservice\fR +Import the logger service commands into the current namespace. Without the \fB-all\fR option +only the commands corresponding to the log levels are imported. If \fB-all\fR is given, +all the \fB${log}::cmd\fR style commands are imported. If the import would overwrite a command +an error is returned and no command is imported. Use the \fB-force\fR option to force the import +and overwrite existing commands without complaining. +If the \fB-prefix\fR option is given, the commands are imported with the given \fIprefix\fR +prepended to their names. +If the \fB-namespace\fR option is given, the commands are imported into the given namespace. If the +namespace does not exist, it is created. If a namespace without a leading :: is given, it is interpreted as +a child namespace to the current namespace. +.TP +\fBlogger::initNamespace\fR \fIns\fR ?\fIlevel\fR? +Convenience command for setting up a namespace for logging. Creates a +logger service named after the namespace \fIns\fR (a :: prefix is +stripped), imports all the log commands into the namespace, and sets +the default logging level, either to the specified \fIlevel\fR, or the +default level, "warn". +.TP +\fBlogger::services\fR +Returns a list of all the available services. +.TP +\fBlogger::enable\fR \fIlevel\fR +Globally enables logging at and "above" the given level. Levels are +\fBdebug\fR, \fBinfo\fR, \fBnotice\fR, \fBwarn\fR, \fBerror\fR, +\fBcritical\fR, \fBalert\fR, \fBemergency\fR. +.TP +\fBlogger::disable\fR \fIlevel\fR +Globally disables logging at and "below" the given level. Levels are +those listed above. +.TP +\fBlogger::setlevel\fR \fIlevel\fR +Globally enable logging at and "above" the given level. Levels are those +listed above. This command changes the default loglevel for new loggers +created with \fBlogger::init\fR. +.TP +\fBlogger::levels\fR +Returns a list of the available log levels (also listed above under \fBenable\fR). +.TP +\fBlogger::servicecmd\fR \fIservice\fR +Returns the \fB${log}\fR token created by \fBlogger::init\fR for this service. +.TP +\fB${log}::debug\fR \fImessage\fR +.TP +\fB${log}::info\fR \fImessage\fR +.TP +\fB${log}::notice\fR \fImessage\fR +.TP +\fB${log}::warn\fR \fImessage\fR +.TP +\fB${log}::error\fR \fImessage\fR +.TP +\fB${log}::critical\fR \fImessage\fR +.TP +\fB${log}::alert\fR \fImessage\fR +.TP +\fB${log}::emergency\fR \fImessage\fR +These are the commands called to actually log a message about an +event. \fB${log}\fR is the variable obtained from \fBlogger::init\fR. +.TP +\fB${log}::setlevel\fR \fIlevel\fR +Enable logging, in the service referenced by \fB${log}\fR, and its +children, at and above the level specified, and disable logging below +it. +.TP +\fB${log}::enable\fR \fIlevel\fR +Enable logging, in the service referenced by \fB${log}\fR, and its +children, at and above the level specified. Note that this does \fInot\fR disable logging below this level, so you should probably use +\fBsetlevel\fR instead. +.TP +\fB${log}::disable\fR \fIlevel\fR +Disable logging, in the service referenced by \fB${log}\fR, and its +children, at and below the level specified. Note that this does \fInot\fR enable logging above this level, +so you should probably use \fBsetlevel\fR instead. +Disabling the loglevel \fBemergency\fR switches logging off for the service and its children. +.TP +\fB${log}::lvlchangeproc\fR \fIcommand\fR +.TP +\fB${log}::lvlchangeproc\fR +Set the script to call when the log instance in question changes its log level. +If called without a command it returns the currently registered command. The command gets two arguments +appended, the old and the new loglevel. The callback is invoked after all changes have been done. +If child loggers are affected, their callbacks are called before their parents callback. +.CS + + + proc lvlcallback {old new} { + puts "Loglevel changed from $old to $new" + } + ${log}::lvlchangeproc lvlcallback + +.CE +.TP +\fB${log}::logproc\fR \fIlevel\fR +.TP +\fB${log}::logproc\fR \fIlevel\fR \fIcommand\fR +.TP +\fB${log}::logproc\fR \fIlevel\fR \fIargname\fR \fIbody\fR +This command comes in three forms - the third, older one is deprecated +and may be removed from future versions of the logger package. +The current set version takes one argument, a command to be executed when the +level is called. The callback command takes on argument, the text to +be logged. If called only with a valid level \fBlogproc\fR returns the name of the command +currently registered as callback command. +\fBlogproc\fR specifies which command will perform the actual logging +for a given level. The logger package ships with default commands for +all log levels, but with \fBlogproc\fR it is possible to replace them +with custom code. This would let you send your logs over the network, +to a database, or anything else. For example: +.CS + + + proc logtoserver {txt} { + variable socket + puts $socket "Notice: $txt" + } + + ${log}::logproc notice logtoserver + +.CE +.IP +Trace logs are slightly different: instead of a plain text argument, +the argument provided to the logproc is a dictionary consisting of the +\fBenter\fR or \fBleave\fR keyword along with another dictionary of +details about the trace. These include: +.RS +.IP \(bu +\fBproc\fR - Name of the procedure being traced. +.IP \(bu +\fBlevel\fR - The stack level for the procedure invocation +(from \fBinfo\fR \fBlevel\fR). +.IP \(bu +\fBscript\fR - The name of the file in which the procedure is +defined, or an empty string if defined in interactive mode. +.IP \(bu +\fBcaller\fR - The name of the procedure calling the procedure +being traced, or an empty string if the procedure was called from the +global scope (stack level 0). +.IP \(bu +\fBprocargs\fR - A dictionary consisting of the names of arguments +to the procedure paired with values given for those arguments (\fBenter\fR +traces only). +.IP \(bu +\fBstatus\fR - The Tcl return code (e.g. \fBok\fR, +\fBcontinue\fR, etc.) (\fBleave\fR traces only). +.IP \(bu +\fBresult\fR - The value returned by the procedure (\fBleave\fR +traces only). +.RE +.TP +\fB${log}::services\fR +Returns a list of the registered logging services which are children of this service. +.TP +\fB${log}::servicename\fR +Returns the name of this service. +.TP +\fB${log}::currentloglevel\fR +Returns the currently enabled log level for this service. If no logging is enabled returns \fBnone\fR. +.TP +\fB${log}::delproc\fR \fIcommand\fR +.TP +\fB${log}::delproc\fR +Set the script to call when the log instance in question is deleted. +If called without a command it returns the currently registered command. +For example: +.CS + + + ${log}::delproc [list closesock $logsock] + +.CE +.TP +\fB${log}::delete\fR +This command deletes a particular logging service, and its children. +You must call this to clean up the resources used by a service. +.TP +\fB${log}::trace\fR \fIcommand\fR +This command controls logging of enter/leave traces for specified procedures. +It is used to enable and disable tracing, query tracing status, and +specify procedures are to be traced. Trace handlers are unregistered when +tracing is disabled. As a result, there is not performance impact to a +library when tracing is disabled, just as with other log level commands. +.CS + + + proc tracecmd { dict } { + puts $dict + } + + set log [::logger::init example] + ${log}::logproc trace tracecmd + + proc foo { args } { + puts "In foo" + bar 1 + return "foo_result" + } + + proc bar { x } { + puts "In bar" + return "bar_result" + } + + ${log}::trace add foo bar + ${log}::trace on + + foo + +# Output: +enter {proc ::foo level 1 script {} caller {} procargs {args {}}} +In foo +enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}} +In bar +leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result} +leave {proc ::foo level 1 script {} caller {} status ok result foo_result} + +.CE +.TP +\fB${log}::trace\fR \fBon\fR +Turns on trace logging for procedures registered through the \fBtrace\fR +\fBadd\fR command. This is similar to the \fBenable\fR command for other +logging levels, but allows trace logging to take place at any level. +The trace logging mechanism takes advantage of the execution trace feature +of Tcl 8.4 and later. The \fBtrace\fR \fBon\fR command will return an +error if called from earlier versions of Tcl. +.TP +\fB${log}::trace\fR \fBoff\fR +Turns off trace logging for procedures registered for trace logging +through the \fBtrace\fR \fBadd\fR command. This is similar to the +\fBdisable\fR command for other logging levels, but allows trace logging +to take place at any level. +Procedures are not unregistered, so logging for them can be turned back +on with the \fBtrace\fR \fBon\fR command. There is no overhead imposed +by trace registration when trace logging is disabled. +.TP +\fB${log}::trace\fR \fBstatus\fR ?procName? ?...? +This command returns a list of the procedures currently registered for +trace logging, or a flag indicating whether or not a trace is registered +for one or more specified procedures. +.TP +\fB${log}::trace\fR \fBadd\fR \fIprocName\fR ?...? +.TP +\fB${log}::trace\fR \fBadd\fR ?-ns? \fInsName\fR ?...? +This command registers one or more procedures for logging of entry/exit +traces. Procedures can be specified via a list of procedure names or +namespace names (in which case all procedure within the namespace +are targeted by the operation). By default, each name is first +interpreted as a procedure name or glob-style search pattern, and if +not found its interpreted as a namespace name. The \fI-ns\fR option can +be used to force interpretation of all provided arguments as namespace names. +Procedures must be defined prior to registering them for tracing +through the \fBtrace\fR \fBadd\fR command. Any procedure or namespace +names/patterns that don't match any existing procedures will be +silently ignored. +.TP +\fB${log}::trace\fR \fBremove\fR \fIprocName\fR ?...? +.TP +\fB${log}::trace\fR \fBremove\fR ?-ns? \fInsName\fR ?...? +This command unregisters one or more procedures so that they will no +longer have trace logging performed, with the same matching rules as +that of the \fBtrace\fR \fBadd\fR command. +.PP +.SH IMPLEMENTATION +The logger package is implemented in such a way as to optimize (for +Tcl 8.4 and newer) log procedures which are disabled. They are +aliased to a proc which has no body, which is compiled to a no op in +bytecode. This should make the peformance hit minimal. If you really +want to pull out all the stops, you can replace the ${log} token in +your code with the actual namespace and command (${log}::warn becomes +::logger::tree::myservice::warn), so that no variable lookup is done. +This puts the performance of disabled logger commands very close to no +logging at all. +.PP +The "object orientation" is done through a hierarchy of namespaces. +Using an actual object oriented system would probably be a better way +of doing things, or at least provide for a cleaner implementation. +.PP +The service "object orientation" is done with namespaces. +.SH "LOGPROCS AND CALLSTACK" +The logger package takes extra care to keep the logproc out of the call stack. +This enables logprocs to execute code in the callers scope by using uplevel or +linking to local variables by using upvar. This may fire traces with all usual +side effects. +.CS + + + # Print caller and current vars in the calling proc + proc log_local_var {txt} { + set caller [info level -1] + set vars [uplevel 1 info vars] + foreach var [lsort $vars] { + if {[uplevel 1 [list array exists $var]] == 1} { + lappend val $var <Array> + } else { + lappend val $var [uplevel 1 [list set $var]] + } + } + puts "$txt" + puts "Caller: $caller" + puts "Variables in callers scope:" + foreach {var value} $val { + puts "$var = $value" + } + } + + # install as logproc + ${log}::logproc debug log_local_var + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIlogger\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +log, log level, logger, service +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/log/loggerAppender.n Index: embedded/man/files/modules/log/loggerAppender.n ================================================================== --- /dev/null +++ embedded/man/files/modules/log/loggerAppender.n @@ -0,0 +1,301 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/log/loggerAppender.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "logger::appender" n 1.2 tcllib "Object Oriented logging facility" +.BS +.SH NAME +logger::appender \- Collection of predefined appenders for logger +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBlogger::appender ?1.2?\fR +.sp +\fB::logger::appender::console\fR \fB-level\fR \fIlevel\fR \fB-service\fR \fIservice\fR ?\fIoptions\fR...? +.sp +\fB::logger::appender::colorConsole\fR \fB-level\fR \fIlevel\fR \fB-service\fR \fIservice\fR ?\fIoptions\fR...? +.sp +.BE +.SH DESCRIPTION +This package provides a predefined set of logger templates. +.TP +\fB::logger::appender::console\fR \fB-level\fR \fIlevel\fR \fB-service\fR \fIservice\fR ?\fIoptions\fR...? +.RS +.TP +\fB-level\fR level +Name of the level to fill in as "priority" in the log procedure. +.TP +\fB-service\fR service +Name of the service to fill in as "category" in the log procedure. +.TP +\fB-appenderArgs\fR appenderArgs +Any additional arguments for the log procedure in list form +.TP +\fB-conversionPattern\fR conversionPattern +The log pattern to use (see \fBlogger::utils::createLogProc\fR for the +allowed substitutions). +.TP +\fB-procName\fR procName +Explicitly set the name of the created procedure. +.TP +\fB-procNameVar\fR procNameVar +Name of the variable to set in the calling context. This variable will +contain the name of the procedure. +.RE +.TP +\fB::logger::appender::colorConsole\fR \fB-level\fR \fIlevel\fR \fB-service\fR \fIservice\fR ?\fIoptions\fR...? +See \fB::logger::appender::colorConsole\fR for a description of the +applicable options. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIlogger\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +appender, logger +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com> + +.fi ADDED embedded/man/files/modules/log/loggerUtils.n Index: embedded/man/files/modules/log/loggerUtils.n ================================================================== --- /dev/null +++ embedded/man/files/modules/log/loggerUtils.n @@ -0,0 +1,395 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/log/loggerUtils.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "logger::utils" n 1.3 tcllib "Object Oriented logging facility" +.BS +.SH NAME +logger::utils \- Utilities for logger +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBlogger::utils ?1.3?\fR +.sp +\fB::logger::utils::createFormatCmd\fR \fIformatString\fR +.sp +\fB::logger::utils::createLogProc\fR \fB-procName\fR \fIprocName\fR ?\fIoptions\fR...? +.sp +\fB::logger::utils::applyAppender\fR \fB-appender\fR \fIappenderType\fR ?\fIoptions\fR...? +.sp +\fB::logger::utils::autoApplyAppender\fR \fIcommand\fR \fIcommand-string\fR \fIlog\fR \fIop\fR \fIargs\fR... +.sp +.BE +.SH DESCRIPTION +This package adds template based \fIappenders\fR. +.TP +\fB::logger::utils::createFormatCmd\fR \fIformatString\fR +This command translates \fIformatString\fR into an expandable command +string. +The following strings are the known substitutions (from log4perl) +allowed to occur in the \fIformatString\fR: +.RS +.TP +%c +Category of the logging event +.TP +%C +Fully qualified name of logging event +.TP +%d +Current date in yyyy/MM/dd hh:mm:ss +.TP +%H +Hostname +.TP +%m +Message to be logged +.TP +%M +Method where logging event was issued +.TP +%p +Priority of logging event +.TP +%P +Pid of current process +.RE +.TP +\fB::logger::utils::createLogProc\fR \fB-procName\fR \fIprocName\fR ?\fIoptions\fR...? +This command ... +.RS +.TP +\fB-procName\fR procName +The name of the procedure to create. +.TP +\fB-conversionPattern\fR pattern +See \fB::logger::utils::createFormatCmd\fR for the substitutions +allowed in the \fIpattern\fR. +.TP +\fB-category\fR category +The category (service). +.TP +\fB-priority\fR priority +The priority (level). +.TP +\fB-outputChannel\fR channel +channel to output on (default stdout) +.RE +.TP +\fB::logger::utils::applyAppender\fR \fB-appender\fR \fIappenderType\fR ?\fIoptions\fR...? +This command will create an appender for the specified logger +services. If no service is specified then the appender will be added +as the default appender for the specified levels. If no levels are +specified, then all levels are assumed. +.sp +.RS +.TP +\fB-service\fR loggerservices +.TP +\fB-serviceCmd\fR loggerserviceCmds +Name of the logger instance to modify. \fB-serviceCmd\fR takes as +input the return of \fBlogger::init\fR. +.TP +\fB-appender\fR appenderType +Type of the appender to use. +One of \fBconsole\fR, \fBcolorConsole\fR. +.TP +\fB-conversionPattern\fR pattern +See \fB::logger::utils::createFormatCmd\fR for the +format of the pattern. If this option is not provided +the default pattern +.CS + +[%d] [%c] [%M] [%p] %m +.CE +.IP +is used. +.TP +\fB-levels\fR levelList +The list of levels to apply this appender to. If not specified all +levels are assumed. +.RE +.sp +Example of usage: +.sp +.CS + + + % set log [logger::init testLog] + ::logger::tree::testLog + % logger::utils::applyAppender -appender console -serviceCmd $log + % ${log}::error "this is an error" + [2005/08/22 10:14:13] [testLog] [global] [error] this is an error + +.CE +.TP +\fB::logger::utils::autoApplyAppender\fR \fIcommand\fR \fIcommand-string\fR \fIlog\fR \fIop\fR \fIargs\fR... +This command is designed to be added via \fBtrace leave\fR to calls +of \fBlogger::init\fR. It will look at preconfigured state (via +\fB::logger::utils::applyAppender\fR) to autocreate appenders for +newly created logger instances. +It will return its argument \fIlog\fR. +.sp +Example of usage: +.sp +.CS + + + logger::utils::applyAppender -appender console + set log [logger::init applyAppender-3] + ${log}::error "this is an error" + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIlogger\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +appender, logger +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com> + +.fi ADDED embedded/man/files/modules/map/map_geocode_nominatim.n Index: embedded/man/files/modules/map/map_geocode_nominatim.n ================================================================== --- /dev/null +++ embedded/man/files/modules/map/map_geocode_nominatim.n @@ -0,0 +1,358 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/map/map_geocode_nominatim.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "map::geocode::nominatim" n 0.1 tcllib "Mapping utilities" +.BS +.SH NAME +map::geocode::nominatim \- Resolving geographical names with a Nominatim service +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBhttp \fR +.sp +package require \fBjson \fR +.sp +package require \fBuri \fR +.sp +package require \fBsnit \fR +.sp +package require \fBmap::geocode::nominatim ?0.1?\fR +.sp +\fB::map::geocode::nominatim\fR \fIrequestor\fR ?\fB-baseurl\fR \fIurl\fR? ?\fB-callback\fR \fIcallback\fR? ?\fB-error\fR \fIerror callback\fR? +.sp +\fB$cmdprefix\fR \fIresult\fR +.sp +\fB$cmdprefix\fR \fIerrorstring\fR +.sp +\fIrequestor\fR \fBsearch\fR \fIquery\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for accessing geocoding services which implement +the \fINominatim\fR interface (see \fBReferences\fR) +.SH API +.TP +\fB::map::geocode::nominatim\fR \fIrequestor\fR ?\fB-baseurl\fR \fIurl\fR? ?\fB-callback\fR \fIcallback\fR? ?\fB-error\fR \fIerror callback\fR? +Creates a geocoding request object \fIrequestor\fR, which will send its requests to +the \fINominatim\fR server. +.sp +The result of the command is \fIname\fR. +.PP +.SS OPTIONS +.TP +\fB-baseurl\fR \fIurl\fR +The base URL of the \fINominatim\fR service. Default value is \fIOpenStreetMap's\fR service at +\fIhttp://nominatim.openstreetmap.org/search\fR A possible free alternative is at +\fIhttp://open.mapquestapi.com//nominatim/v1/search\fR +.TP +\fB-callback\fR \fIcmdprefix\fR +A command prefix to be invoked when search result become available. +The default setting, active when nothing was specified on object creation, is to print +the \fIresult\fR (see below) to \fIstdout\fR. The result of the command prefix is +ignored. Errors thrown by the command prefix are caught and cause the invokation of +the error callback (see option \fB-error\fR below), with the error message as argument. +.sp +The signature of the command prefix is: +.RS +.TP +\fB$cmdprefix\fR \fIresult\fR +The \fIresult\fR is a list of dictionaries, containing one item per hit. +Each dictionary will have the following entries: +.RS +.TP +place_id +The place ID (FIXME: what's this?) +.TP +licence +The data licence string +.TP +osm_type +The OSM type of the location +.TP +osm_id +FIXME +.TP +boundingbox +The coordinates of the bounding box (min and max latitude, min and max longitude) +.TP +lat +The location's latitude +.TP +lon +The location's longitude +.TP +display_name +the location's human readable name +.TP +class +FIXME +.TP +type +FIXME +.TP +icon +FIXME +.RE +.RE +.TP +\fB-error\fR \fIcmdprefix\fR +A command prefix to be invoked when encountering errors. Typically these are HTTP errors. +The default setting, active when nothing was specified on object creation, is to print +the \fIerrorstring\fR (see below) to \fIstderr\fR. The result of the command prefix is +ignored. Errors thrown by the command prefix are passed to higher levels. +.sp +The signature of the command prefix is: +.RS +.TP +\fB$cmdprefix\fR \fIerrorstring\fR +.RE +.PP +.SS METHODS +.TP +\fIrequestor\fR \fBsearch\fR \fIquery\fR +This method returns a list of dictionaries, one item per hit for the specified \fIquery\fR. +.PP +.SH REFERENCES +.IP [1] +\fIhttp://wiki.openstreetmap.org/wiki/Nominatim\fR +.IP [2] +\fIhttp://open.mapquestapi.com/nominatim/\fR +.PP +.SH KEYWORDS +geocoding, http, location, map, nominatim, server, url ADDED embedded/man/files/modules/map/map_slippy.n Index: embedded/man/files/modules/map/map_slippy.n ================================================================== --- /dev/null +++ embedded/man/files/modules/map/map_slippy.n @@ -0,0 +1,421 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/map/map_slippy.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "map::slippy" n 0.5 tcllib "Mapping utilities" +.BS +.SH NAME +map::slippy \- Common code for slippy based map packages +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBTk 8.4\fR +.sp +package require \fBmap::slippy ?0.5?\fR +.sp +\fB::map::slippy\fR \fBlength\fR \fIlevel\fR +.sp +\fB::map::slippy\fR \fBtiles\fR \fIlevel\fR +.sp +\fB::map::slippy\fR \fBtile size\fR +.sp +\fB::map::slippy\fR \fBtile valid\fR \fItile\fR \fIlevels\fR ?\fImsgvar\fR? +.sp +\fB::map::slippy\fR \fBgeo 2tile\fR \fIgeo\fR +.sp +\fB::map::slippy\fR \fBgeo 2tile.float\fR \fIgeo\fR +.sp +\fB::map::slippy\fR \fBgeo 2point\fR \fIgeo\fR +.sp +\fB::map::slippy\fR \fBtile 2geo\fR \fItile\fR +.sp +\fB::map::slippy\fR \fBtile 2point\fR \fItile\fR +.sp +\fB::map::slippy\fR \fBpoint 2geo\fR \fIpoint\fR +.sp +\fB::map::slippy\fR \fBpoint 2tile\fR \fIpoint\fR +.sp +\fB::map::slippy\fR \fBfit geobox\fR \fIcanvdim\fR \fIgeobox\fR \fIzmin\fR \fIzmax\fR +.sp +.BE +.SH DESCRIPTION +This package provides a number of methods doing things needed by all +types of slippy-based map packages. +.SH API +.TP +\fB::map::slippy\fR \fBlength\fR \fIlevel\fR +This method returns the width/height of a slippy-based map at the +specified zoom \fIlevel\fR, in pixels. This is, in essence, the result +of +.CS + + + expr { [tiles $level] * [tile size] } + +.CE +.TP +\fB::map::slippy\fR \fBtiles\fR \fIlevel\fR +This method returns the width/height of a slippy-based map at the +specified zoom \fIlevel\fR, in \fItiles\fR. +.TP +\fB::map::slippy\fR \fBtile size\fR +This method returns the width/height of a tile in a slippy-based map, +in pixels. +.TP +\fB::map::slippy\fR \fBtile valid\fR \fItile\fR \fIlevels\fR ?\fImsgvar\fR? +This method checks whether \fItile\fR described a valid tile in a +slippy-based map containing that many zoom \fIlevels\fR. The result is +a boolean value, \fBtrue\fR if the tile is valid, and \fBfalse\fR +otherwise. For the latter a message is left in the variable named by +\fImsgvar\fR, should it be specified. +.sp +A tile identifier as stored in \fItile\fR is a list containing zoom +level, tile row, and tile column, in this order. The command +essentially checks this, i.e. the syntax, that the zoom level is +between 0 and "\fIlevels\fR-1", and that the row/col information is +within the boundaries for the zoom level, i.e. 0 ... +"[tiles $zoom]-1". +.TP +\fB::map::slippy\fR \fBgeo 2tile\fR \fIgeo\fR +Converts a geographical location at a zoom level (\fIgeo\fR, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses pure integer numbers for the tile +coordinates, for all geographic coordinates mapping to that tile. +.TP +\fB::map::slippy\fR \fBgeo 2tile.float\fR \fIgeo\fR +Converts a geographical location at a zoom level (\fIgeo\fR, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses floating point numbers for the tile +coordinates, representing not only the tile the geographic coordinates +map to, but also the fractional location inside of that tile. +.TP +\fB::map::slippy\fR \fBgeo 2point\fR \fIgeo\fR +Converts a geographical location at a zoom level (\fIgeo\fR, a list +containing zoom level, latitude, and longitude, in this order) to a +pixel position (list containing zoom level, y, and x) at that level. +.TP +\fB::map::slippy\fR \fBtile 2geo\fR \fItile\fR +Converts a tile identifier at a zoom level (\fItile\fR, list +containing zoom level, row, and column) to a geographical location +(list containing zoom level, latitude, and longitude, in this order) +at that level. +.TP +\fB::map::slippy\fR \fBtile 2point\fR \fItile\fR +Converts a tile identifier at a zoom level (\fItile\fR, a list +containing zoom level, row, and column, in this order) to a pixel +position (list containing zoom level, y, and x) at that level. +.TP +\fB::map::slippy\fR \fBpoint 2geo\fR \fIpoint\fR +Converts a pixel position at a zoom level (\fIpoint\fR, list +containing zoom level, y, and x) to a geographical location (list +containing zoom level, latitude, and longitude, in this order) at that +level. +.TP +\fB::map::slippy\fR \fBpoint 2tile\fR \fIpoint\fR +Converts a pixel position at a zoom level (\fIpoint\fR, a list +containing zoom level, y, and x, in this order) to a tile identifier +(list containing zoom level, row, and column) at that level. +.TP +\fB::map::slippy\fR \fBfit geobox\fR \fIcanvdim\fR \fIgeobox\fR \fIzmin\fR \fIzmax\fR +Calculates the zoom level (whithin the bounds \fIzmin\fR and +\fIzmax\fR) such that \fIgeobox\fR (a 4-element list containing the +latitudes and longitudes lat0, lat1, lon0 and lon1 of a geo box, +in this order) fits into a viewport given by \fIcanvdim\fR, a +2-element list containing the width and height of the viewport, in +this order. +.PP +.SH "COORDINATE SYSTEMS" +The commands of this package operate on three distinct coordinate +systems, which are explained below. +.SS GEOGRAPHIC +\fIGeographic\fRal coordinates are represented by \fILatitude\fR and +\fILongitude\fR, each of which is measured in degrees, as they are +essentially angles. +.PP +\fBZero\fR longitude is the \fIGreenwich meridian\fR, with +positive values going \fIeast\fR, and negative values going +\fIwest\fR, for a total range of +/- 180 degrees. Note that +180 and +-180 longitude are the same \fImeridian\fR, opposite to greenwich. +.PP +\fBzero\fR latitude the \fIEquator\fR, with positive values +going \fInorth\fR and negative values going \fIsouth\fR. While the +true range is +/- 90 degrees the projection used by the package +requires us to cap the range at +/- 85.05112877983284 degrees. This +means that north and south pole are not representable and not part of +any map. +.SS TILES +While \fBGeographic\fRal coordinates of the previous section are +independent of zoom level the \fItile coordinates\fR are not. +.PP +Generally the integer part of tile coordinates represent the +row and column number of the tile in question, wheras the fractional +parts signal how far inside the tile the location in question is, with +pure integer coordinates (no fractional part) representing the upper +left corner of the tile. +.PP +The zero point of the map is at the upper left corner, +regardless of zoom level, with larger coordinates going right (east) +and down (south), and smaller coordinates going left (west) and up +(north). Again regardless of zxoom level. +.PP +Negative tile coordinates are not allowed. +.PP +At zoom level 0 the whole map is represented by a single, +putting the geographic zero at 1/2, 1/2 of tile coordinates, and the +range of tile coordinates as [0...1]. +.PP +To go from a zoom level N to the next deeper level N+1 each +tile of level N is split into its four quadrants, which then are the +tiles of level N+1. +.PP +This means that at zoom level N the map is sliced (horizontally +and vertically) into 2^N stripes, for a total of 4^N tiles, with tile +coordinates ranging from 0 to 2^N+1. +.SS PIXELS/POINTS +\fIpixel coordinates\fR, also called \fIpoint coordinates\fR are +in essence \fBtile coordinates\fR scaled by the size of +the image representing a tile. This tile size currently has a fixed +value, \fB256\fR. +.SH REFERENCES +.IP [1] +\fIhttp://wiki.openstreetmap.org/wiki/Main_Page\fR +.PP +.SH KEYWORDS +geodesy, geography, latitute, location, longitude, map, slippy, zoom ADDED embedded/man/files/modules/map/map_slippy_cache.n Index: embedded/man/files/modules/map/map_slippy_cache.n ================================================================== --- /dev/null +++ embedded/man/files/modules/map/map_slippy_cache.n @@ -0,0 +1,325 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/map/map_slippy_cache.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "map::slippy::cache" n 0.2 tcllib "Mapping utilities" +.BS +.SH NAME +map::slippy::cache \- Management of a tile cache in the local filesystem +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBTk 8.4\fR +.sp +package require \fBimg::png \fR +.sp +package require \fBmap::slippy \fR +.sp +package require \fBmap::slippy::cache ?0.2?\fR +.sp +\fB::map::slippy::cache\fR \fIcacheName\fR \fIcachedir\fR \fIprovider\fR +.sp +\fIcacheName\fR \fBvalid\fR \fItile\fR ?\fImsgvar\fR? +.sp +\fIcacheName\fR \fBexists\fR \fItile\fR +.sp +\fIcacheName\fR \fBget\fR \fItile\fR \fIdonecmd\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for managing a cache of tiles for +slippy-based maps in the local filesystem. +.SH API +.TP +\fB::map::slippy::cache\fR \fIcacheName\fR \fIcachedir\fR \fIprovider\fR +Creates the cache \fIcacheName\fR and configures it with both the path +to the directory contaiing the locally cached tiles (\fIcachedir\fR), +and the command prefix from which it will pull tiles asked for and not +yet known to the cache itself (\fIprovider\fR). +.sp +The result of the command is \fIcacheName\fR. +.PP +.SS METHODS +.TP +\fIcacheName\fR \fBvalid\fR \fItile\fR ?\fImsgvar\fR? +This method checks the validity of a the given \fItile\fR identifier. +This is a convenience wrapper to \fB::map::slippy tile valid\fR and +has the same interface. +.TP +\fIcacheName\fR \fBexists\fR \fItile\fR +This methods tests whether the cache contains the specified \fItile\fR +or not. The result is a boolean value, \fBtrue\fR if the tile is +known, and \fBfalse\fR otherwise. The tile is identified by a list +containing three elements, zoom level, row, and column number, in this +order. +.TP +\fIcacheName\fR \fBget\fR \fItile\fR \fIdonecmd\fR +This is the main method of the cache, retrieving the image for the +specified \fItile\fR from the cache. The tile identifier is a list +containing three elements, the zoom level, row, and column number of +the tile, in this order. +.sp +The command refix \fIdonecmd\fR will be invoked when the cache +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e. +.RS +.IP [1] +The string \fBset\fR, the \fItile\fR, and the image. +.IP [2] +The string \fBunset\fR, and the \fItile\fR. +.RE +.IP +These two possibilities are used to either signal the image for the +\fItile\fR, or that the \fItile\fR has no image defined for it. +.sp +When the cache has no information about the tile it will invoke the +\fIprovider\fR command prefix specified during its construction, +adding three arguments: The string \fBget\fR, the \fItile\fR, and a +callback into the cache. The latter will be invoked by the provider to +either transfer the image to the cache, or signal that the tile has no +image. +.sp +When multiple requests for the same tile are made only one request +will be issued to the provider. +.PP +.SH REFERENCES +.IP [1] +\fIhttp://wiki.openstreetmap.org/wiki/Main_Page\fR +.PP +.SH KEYWORDS +cache, filesystem, location, map, slippy, tile, zoom ADDED embedded/man/files/modules/map/map_slippy_fetcher.n Index: embedded/man/files/modules/map/map_slippy_fetcher.n ================================================================== --- /dev/null +++ embedded/man/files/modules/map/map_slippy_fetcher.n @@ -0,0 +1,314 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/map/map_slippy_fetcher.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "map::slippy::fetcher" n 0.3 tcllib "Mapping utilities" +.BS +.SH NAME +map::slippy::fetcher \- Accessing a server providing tiles for slippy-based maps +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBTk 8.4\fR +.sp +package require \fBimg::png \fR +.sp +package require \fBmap::slippy \fR +.sp +package require \fBmap::slippy::fetcher ?0.3?\fR +.sp +\fB::map::slippy::fetcher\fR \fIfetcherName\fR \fIlevels\fR \fIurl\fR +.sp +\fIfetcherName\fR \fBlevels\fR +.sp +\fIfetcherName\fR \fBtileheight\fR +.sp +\fIfetcherName\fR \fBtilewidth\fR +.sp +\fIfetcherName\fR \fBget\fR \fItile\fR \fIdonecmd\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for accessing http servers providing +tiles for slippy-based maps. +.SH API +.TP +\fB::map::slippy::fetcher\fR \fIfetcherName\fR \fIlevels\fR \fIurl\fR +Creates the fetcher \fIfetcherName\fR and configures it with the +number of zoom \fIlevels\fR supported by the tile server, and the +\fIurl\fR it is listening on for tile requests. +.sp +The result of the command is \fIfetcherName\fR. +.PP +.SS METHODS +.TP +\fIfetcherName\fR \fBlevels\fR +This method returns the number of zoom levels supported by the fetcher +object, and the tile server it is accessing. +.TP +\fIfetcherName\fR \fBtileheight\fR +This method returns the height of tiles served, in pixels. +.TP +\fIfetcherName\fR \fBtilewidth\fR +This method returns the width of tiles served, in pixels. +.TP +\fIfetcherName\fR \fBget\fR \fItile\fR \fIdonecmd\fR +This is the main method of the fetcher, retrieving the image for the +specified \fItile\fR. The tile identifier is a list containing three +elements, the zoom level, row, and column number of the tile, in this +order. +.sp +The command refix \fIdonecmd\fR will be invoked when the fetcher +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e. +.RS +.IP [1] +The string \fBset\fR, the \fItile\fR, and the image. +.IP [2] +The string \fBunset\fR, and the \fItile\fR. +.RE +.IP +These two possibilities are used to either signal the image for the +\fItile\fR, or that the \fItile\fR has no image defined for it. +.PP +.SH REFERENCES +.IP [1] +\fIhttp://wiki.openstreetmap.org/wiki/Main_Page\fR +.PP +.SH KEYWORDS +http, location, map, server, slippy, tile, url, zoom ADDED embedded/man/files/modules/mapproj/mapproj.n Index: embedded/man/files/modules/mapproj/mapproj.n ================================================================== --- /dev/null +++ embedded/man/files/modules/mapproj/mapproj.n @@ -0,0 +1,684 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/mapproj/mapproj.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Kevin B. Kenny <kennykb@acm.org> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "mapproj" n 0.1 tcllib "Tcl Library" +.BS +.SH NAME +mapproj \- Map projection routines +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBmath::interpolate ?1.0?\fR +.sp +package require \fBmath::special ?0.2.1?\fR +.sp +package require \fBmapproj ?1.0?\fR +.sp +\fB::mapproj::toPlateCarree\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromPlateCarree\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toMercator\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromMercator\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toMillerCylindrical\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromMillerCylindrical\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toSinusoidal\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromSinusoidal\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toMollweide\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromMollweide\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toEckertIV\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromEckertIV\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toEckertVI\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromEckertVI\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toRobinson\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromRobinson\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toCassini\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromCassini\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toPeirceQuincuncial\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromPeirceQuincuncial\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toOrthographic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromOrthographic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toStereographic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromStereographic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toGnomonic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromGnomonic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toAzimuthalEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromAzimuthalEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toLambertAzimuthalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromLambertAzimuthalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toHammer\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromHammer\fR \fIlambda_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toConicEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromConicEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toAlbersEqualAreaConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromAlbersEqualAreaConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toLambertConformalConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromLambertConformalConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toLambertCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromLambertCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toBehrmann\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromBehrmann\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toTrystanEdwards\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromTrystanEdwards\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toHoboDyer\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromHoboDyer\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toGallPeters\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromGallPeters\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +\fB::mapproj::toBalthasart\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +.sp +\fB::mapproj::fromBalthasart\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +.sp +.BE +.SH DESCRIPTION +The \fBmapproj\fR package provides a set of procedures for +converting between world co-ordinates (latitude and longitude) and map +co-ordinates on a number of different map projections. +.SH COMMANDS +The following commands convert between world co-ordinates and +map co-ordinates: +.TP +\fB::mapproj::toPlateCarree\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the \fIplate carrée\fR (cylindrical equidistant) +projection. +.TP +\fB::mapproj::fromPlateCarree\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the \fIplate carrée\fR (cylindrical equidistant) +projection. +.TP +\fB::mapproj::toCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the cylindrical equal-area projection. +.TP +\fB::mapproj::fromCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the cylindrical equal-area projection. +.TP +\fB::mapproj::toMercator\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Mercator (cylindrical conformal) projection. +.TP +\fB::mapproj::fromMercator\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Mercator (cylindrical conformal) projection. +.TP +\fB::mapproj::toMillerCylindrical\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Miller Cylindrical projection. +.TP +\fB::mapproj::fromMillerCylindrical\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Miller Cylindrical projection. +.TP +\fB::mapproj::toSinusoidal\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the sinusoidal (Sanson-Flamsteed) projection. +projection. +.TP +\fB::mapproj::fromSinusoidal\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the sinusoidal (Sanson-Flamsteed) projection. +projection. +.TP +\fB::mapproj::toMollweide\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Mollweide projection. +.TP +\fB::mapproj::fromMollweide\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Mollweide projection. +.TP +\fB::mapproj::toEckertIV\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Eckert IV projection. +.TP +\fB::mapproj::fromEckertIV\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Eckert IV projection. +.TP +\fB::mapproj::toEckertVI\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Eckert VI projection. +.TP +\fB::mapproj::fromEckertVI\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Eckert VI projection. +.TP +\fB::mapproj::toRobinson\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Robinson projection. +.TP +\fB::mapproj::fromRobinson\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Robinson projection. +.TP +\fB::mapproj::toCassini\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Cassini (transverse cylindrical equidistant) +projection. +.TP +\fB::mapproj::fromCassini\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Cassini (transverse cylindrical equidistant) +projection. +.TP +\fB::mapproj::toPeirceQuincuncial\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Peirce Quincuncial Projection. +.TP +\fB::mapproj::fromPeirceQuincuncial\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Peirce Quincuncial Projection. +.TP +\fB::mapproj::toOrthographic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the orthographic projection. +.TP +\fB::mapproj::fromOrthographic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the orthographic projection. +.TP +\fB::mapproj::toStereographic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the stereographic (azimuthal conformal) projection. +.TP +\fB::mapproj::fromStereographic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the stereographic (azimuthal conformal) projection. +.TP +\fB::mapproj::toGnomonic\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the gnomonic projection. +.TP +\fB::mapproj::fromGnomonic\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the gnomonic projection. +.TP +\fB::mapproj::toAzimuthalEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the azimuthal equidistant projection. +.TP +\fB::mapproj::fromAzimuthalEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the azimuthal equidistant projection. +.TP +\fB::mapproj::toLambertAzimuthalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Lambert azimuthal equal-area projection. +.TP +\fB::mapproj::fromLambertAzimuthalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Lambert azimuthal equal-area projection. +.TP +\fB::mapproj::toHammer\fR \fIlambda_0\fR \fIlambda\fR \fIphi\fR +Converts to the Hammer projection. +.TP +\fB::mapproj::fromHammer\fR \fIlambda_0\fR \fIx\fR \fIy\fR +Converts from the Hammer projection. +.TP +\fB::mapproj::toConicEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +Converts to the conic equidistant projection. +.TP +\fB::mapproj::fromConicEquidistant\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +Converts from the conic equidistant projection. +.TP +\fB::mapproj::toAlbersEqualAreaConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +Converts to the Albers equal-area conic projection. +.TP +\fB::mapproj::fromAlbersEqualAreaConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +Converts from the Albers equal-area conic projection. +.TP +\fB::mapproj::toLambertConformalConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIlambda\fR \fIphi\fR +Converts to the Lambert conformal conic projection. +.TP +\fB::mapproj::fromLambertConformalConic\fR \fIlambda_0\fR \fIphi_0\fR \fIphi_1\fR \fIphi_2\fR \fIx\fR \fIy\fR +Converts from the Lambert conformal conic projection. +.PP +Among the cylindrical equal-area projections, there are a number of +choices of standard parallels that have names: +.TP +\fB::mapproj::toLambertCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Lambert cylindrical equal area projection. (standard parallel +is the Equator.) +.TP +\fB::mapproj::fromLambertCylindricalEqualArea\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Lambert cylindrical equal area projection. (standard parallel +is the Equator.) +.TP +\fB::mapproj::toBehrmann\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South) +.TP +\fB::mapproj::fromBehrmann\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South.) +.TP +\fB::mapproj::toTrystanEdwards\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South) +.TP +\fB::mapproj::fromTrystanEdwards\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South.) +.TP +\fB::mapproj::toHoboDyer\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South) +.TP +\fB::mapproj::fromHoboDyer\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South.) +.TP +\fB::mapproj::toGallPeters\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South) +.TP +\fB::mapproj::fromGallPeters\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South.) +.TP +\fB::mapproj::toBalthasart\fR \fIlambda_0\fR \fIphi_0\fR \fIlambda\fR \fIphi\fR +Converts to the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South) +.TP +\fB::mapproj::fromBalthasart\fR \fIlambda_0\fR \fIphi_0\fR \fIx\fR \fIy\fR +Converts from the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South.) +.PP +.SH ARGUMENTS +The following arguments are accepted by the projection commands: +.TP +\fIlambda\fR +Longitude of the point to be projected, in degrees. +.TP +\fIphi\fR +Latitude of the point to be projected, in degrees. +.TP +\fIlambda_0\fR +Longitude of the center of the sheet, in degrees. For many projections, +this figure is also the reference meridian of the projection. +.TP +\fIphi_0\fR +Latitude of the center of the sheet, in degrees. For the azimuthal +projections, this figure is also the latitude of the center of the projection. +.TP +\fIphi_1\fR +Latitude of the first reference parallel, for projections that use reference +parallels. +.TP +\fIphi_2\fR +Latitude of the second reference parallel, for projections that use reference +parallels. +.TP +\fIx\fR +X co-ordinate of a point on the map, in units of Earth radii. +.TP +\fIy\fR +Y co-ordinate of a point on the map, in units of Earth radii. +.PP +.SH RESULTS +For all of the procedures whose names begin with 'to', the return value +is a list comprising an \fIx\fR co-ordinate and a \fIy\fR co-ordinate. +The co-ordinates are relative to the center of the map sheet to be drawn, +measured in Earth radii at the reference location on the map. +For all of the functions whose names begin with 'from', the return value +is a list comprising the longitude and latitude, in degrees. +.SH "CHOOSING A PROJECTION" +This package offers a great many projections, because no single projection +is appropriate to all maps. This section attempts to provide guidance +on how to choose a projection. +.PP +First, consider the type of data that you intend to display on the map. +If the data are \fIdirectional\fR (\fIe.g.,\fR winds, ocean currents, or +magnetic fields) then you need to use a projection that preserves +angles; these are known as \fIconformal\fR projections. Conformal +projections include the Mercator, the Albers azimuthal equal-area, +the stereographic, and the Peirce Quincuncial projection. If the +data are \fIthematic\fR, describing properties of land or water, such +as temperature, population density, land use, or demographics; then +you need a projection that will show these data with the areas on the map +proportional to the areas in real life. These so-called \fIequal area\fR +projections include the various cylindrical equal area projections, +the sinusoidal projection, the Lambert azimuthal equal-area projection, +the Albers equal-area conic projection, and several of the world-map +projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, +and Hammer). If the significant factor in your data is distance from a +central point or line (such as air routes), then you will do best with +an \fIequidistant\fR projection such as \fIplate carrée\fR, +Cassini, azimuthal equidistant, or conic equidistant. If direction from +a central point is a critical factor in your data (for instance, +air routes, radio antenna pointing), then you will almost surely want to +use one of the azimuthal projections. Appropriate choices are azimuthal +equidistant, azimuthal equal-area, stereographic, and perhaps orthographic. +.PP +Next, consider how much of the Earth your map will cover, and the general +shape of the area of interest. For maps of the entire Earth, +the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer +projections are good overall choices. The Mercator projection is traditional, +but the extreme distortions of area at high latitudes make it +a poor choice unless a conformal projection is required. The Peirce +projection is a better choice of conformal projection, having less distortion +of landforms. The Miller Cylindrical is a compromise designed to give +shapes similar to the traditional Mercator, but with less polar stretching. +The Peirce Quincuncial projection shows all the continents with acceptable +distortion if a reference meridian close to +20 degrees is chosen. +The Robinson projection yields attractive maps for things like political +divisions, but should be avoided in presenting scientific data, since other +projections have moe useful geometric properties. +.PP +If the map will cover a hemisphere, then choose stereographic, +azimuthal-equidistant, Hammer, or Mollweide projections; these all project +the hemisphere into a circle. +.PP +If the map will cover a large area (at least a few hundred km on a side), +but less than +a hemisphere, then you have several choices. Azimuthal projections +are usually good (choose stereographic, azimuthal equidistant, or +Lambert azimuthal equal-area according to whether shapes, distances from +a central point, or areas are important). Azimuthal projections (and possibly +the Cassini projection) are the only +really good choices for mapping the polar regions. +.PP +If the large area is in one of the temperate zones and is round or has +a primarily east-west extent, then the conic projections are good choices. +Choose the Lambert conformal conic, the conic equidistant, or the Albers +equal-area conic according to whether shape, distance, or area are the +most important parameters. For any of these, the reference parallels +should be chosen at approximately 1/6 and 5/6 of the range of latitudes +to be displayed. For instance, maps of the 48 coterminous United States +are attractive with reference parallels of 28.5 and 45.5 degrees. +.PP +If the large area is equatorial and is round or has a primarily east-west +extent, then the Mercator projection is a good choice for a conformal +projection; Lambert cylindrical equal-area and sinusoidal projections are +good equal-area projections; and the \fIplate carrée\fR is a +good equidistant projection. +.PP +Large areas having a primarily North-South aspect, particularly those +spanning the Equator, need some other choices. The Cassini projection +is a good choice for an equidistant projection (for instance, a Cassini +projection with a central meridian of 80 degrees West produces an +attractive map of the Americas). The cylindrical equal-area, Albers +equal-area conic, sinusoidal, Mollweide and Hammer +projections are possible choices for equal-area projections. +A good conformal projection in this situation is the Transverse +Mercator, which alas, is not yet implemented. +.PP +Small areas begin to get into a realm where the ellipticity of the +Earth affects the map scale. This package does not attempt to +handle accurate mapping for large-scale topographic maps. If +slight scale errors are acceptable in your application, then any +of the projections appropriate to large areas should work for +small ones as well. +.PP +There are a few projections that are included for their special +properties. The orthographic projection produces views of the +Earth as seen from space. The gnomonic projection produces a +map on which all great circles (the shortest distance between +two points on the Earth's surface) are rendered as straight lines. +While this projection is useful for navigational planning, it +has extreme distortions of shape and area, and can display +only a limited area of the Earth (substantially less than a hemisphere). +.SH KEYWORDS +geodesy, map, projection +.SH COPYRIGHT +.nf +Copyright (c) 2007 Kevin B. Kenny <kennykb@acm.org> + +.fi ADDED embedded/man/files/modules/math/bigfloat.n Index: embedded/man/files/modules/math/bigfloat.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/bigfloat.n @@ -0,0 +1,789 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/bigfloat.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::bigfloat" n 2.0.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::bigfloat \- Arbitrary precision floating-point numbers +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBmath::bigfloat ?2.0.1?\fR +.sp +\fBfromstr\fR \fInumber\fR ?\fItrailingZeros\fR? +.sp +\fBtostr\fR ?\fB-nosci\fR? \fInumber\fR +.sp +\fBfromdouble\fR \fIdouble\fR ?\fIdecimals\fR? +.sp +\fBtodouble\fR \fInumber\fR +.sp +\fBisInt\fR \fInumber\fR +.sp +\fBisFloat\fR \fInumber\fR +.sp +\fBint2float\fR \fIinteger\fR ?\fIdecimals\fR? +.sp +\fBadd\fR \fIx\fR \fIy\fR +.sp +\fBsub\fR \fIx\fR \fIy\fR +.sp +\fBmul\fR \fIx\fR \fIy\fR +.sp +\fBdiv\fR \fIx\fR \fIy\fR +.sp +\fBmod\fR \fIx\fR \fIy\fR +.sp +\fBabs\fR \fIx\fR +.sp +\fBopp\fR \fIx\fR +.sp +\fBpow\fR \fIx\fR \fIn\fR +.sp +\fBiszero\fR \fIx\fR +.sp +\fBequal\fR \fIx\fR \fIy\fR +.sp +\fBcompare\fR \fIx\fR \fIy\fR +.sp +\fBsqrt\fR \fIx\fR +.sp +\fBlog\fR \fIx\fR +.sp +\fBexp\fR \fIx\fR +.sp +\fBcos\fR \fIx\fR +.sp +\fBsin\fR \fIx\fR +.sp +\fBtan\fR \fIx\fR +.sp +\fBcotan\fR \fIx\fR +.sp +\fBacos\fR \fIx\fR +.sp +\fBasin\fR \fIx\fR +.sp +\fBatan\fR \fIx\fR +.sp +\fBcosh\fR \fIx\fR +.sp +\fBsinh\fR \fIx\fR +.sp +\fBtanh\fR \fIx\fR +.sp +\fBpi\fR \fIn\fR +.sp +\fBrad2deg\fR \fIradians\fR +.sp +\fBdeg2rad\fR \fIdegrees\fR +.sp +\fBround\fR \fIx\fR +.sp +\fBceil\fR \fIx\fR +.sp +\fBfloor\fR \fIx\fR +.sp +.BE +.SH DESCRIPTION +The bigfloat package provides arbitrary precision floating-point math +capabilities to the Tcl language. It is designed to work with Tcl 8.5, +but for Tcl 8.4 is provided an earlier version of this package. +See \fBWHAT ABOUT TCL 8.4 ?\fR for more explanations. +By convention, we will talk about the numbers treated in this library as : +.IP \(bu +BigFloat for floating-point numbers of arbitrary length. +.IP \(bu +integers for arbitrary length signed integers, just as basic integers since Tcl 8.5. +.PP +Each BigFloat is an interval, namely [\fIm-d, m+d\fR], +where \fIm\fR is the mantissa and \fId\fR the uncertainty, representing the +limitation of that number's precision. +This is why we call such mathematics \fIinterval computations\fR. +Just take an example in physics : when you measure a temperature, not all +digits you read are \fIsignificant\fR. Sometimes you just cannot trust all digits - not to mention if doubles (f.p. numbers) can handle all these digits. +BigFloat can handle this problem - trusting the digits you get - plus the ability to store numbers with an arbitrary precision. +BigFloats are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to : +.IP \(bu +perform math operations on BigFloats and (optionnaly) with integers. +.IP \(bu +convert BigFloats from their internal representations to strings, and vice versa. +.PP +.SH INTRODUCTION +.TP +\fBfromstr\fR \fInumber\fR ?\fItrailingZeros\fR? +Converts \fInumber\fR into a BigFloat. Its precision +is at least the number of digits provided by \fInumber\fR. +If the \fInumber\fR contains only digits and eventually a minus sign, it is considered as +an integer. Subsequently, no conversion is done at all. +.sp +\fItrailingZeros\fR - the number of zeros to append at the end of the floating-point number +to get more precision. It cannot be applied to an integer. +.CS + + +# x and y are BigFloats : the first string contained a dot, and the second an e sign +set x [fromstr -1.000000] +set y [fromstr 2000e30] +# let's see how we get integers +set t 20000000000000 +# the old way (package 1.2) is still supported for backwards compatibility : +set m [fromstr 10000000000] +# but we do not need fromstr for integers anymore +set n -39 +# t, m and n are integers + +.CE +.sp +The \fInumber\fR's last digit is considered by the procedure to be true at +/-1, +For example, 1.00 is the interval [0.99, 1.01], +and 0.43 the interval [0.42, 0.44]. +The Pi constant may be approximated by the number "3.1415". +This string could be considered as the interval [3.1414 , 3.1416] by \fBfromstr\fR. +So, when you mean 1.0 as a double, you may have to write 1.000000 to get enough precision. +To learn more about this subject, see \fBPRECISION\fR. +.sp +For example : +.CS + + +set x [fromstr 1.0000000000] +# the next line does the same, but smarter +set y [fromstr 1. 10] + +.CE +.TP +\fBtostr\fR ?\fB-nosci\fR? \fInumber\fR +Returns a string form of a BigFloat, in which all digits are exacts. +\fIAll exact digits\fR means a rounding may occur, for example to zero, +if the uncertainty interval does not clearly show the true digits. +\fInumber\fR may be an integer, causing the command to return exactly the input argument. +With the \fB-nosci\fR option, the number returned is never shown in scientific +notation, i.e. not like '3.4523e+5' but like '345230.'. +.CS + + +puts [tostr [fromstr 0.99999]] ;# 1.0000 +puts [tostr [fromstr 1.00001]] ;# 1.0000 +puts [tostr [fromstr 0.002]] ;# 0.e-2 + +.CE +.IP +See \fBPRECISION\fR for that matter. +See also \fBiszero\fR for how to detect zeros, which is useful when performing a division. +.TP +\fBfromdouble\fR \fIdouble\fR ?\fIdecimals\fR? +Converts a double (a simple floating-point value) to a BigFloat, with +exactly \fIdecimals\fR digits. Without the \fIdecimals\fR argument, +it behaves like \fBfromstr\fR. +Here, the only important feature you might care of is the ability +to create BigFloats with a fixed number of \fIdecimals\fR. +.CS + + +tostr [fromstr 1.111 4] +# returns : 1.111000 (3 zeros) +tostr [fromdouble 1.111 4] +# returns : 1.111 + +.CE +.TP +\fBtodouble\fR \fInumber\fR +Returns a double, that may be used in \fIexpr\fR, +from a BigFloat. +.TP +\fBisInt\fR \fInumber\fR +Returns 1 if \fInumber\fR is an integer, 0 otherwise. +.TP +\fBisFloat\fR \fInumber\fR +Returns 1 if \fInumber\fR is a BigFloat, 0 otherwise. +.TP +\fBint2float\fR \fIinteger\fR ?\fIdecimals\fR? +Converts an integer to a BigFloat with \fIdecimals\fR trailing zeros. +The default, and minimal, number of \fIdecimals\fR is 1. +When converting back to string, one decimal is lost: +.CS + + +set n 10 +set x [int2float $n]; # like fromstr 10.0 +puts [tostr $x]; # prints "10." +set x [int2float $n 3]; # like fromstr 10.000 +puts [tostr $x]; # prints "10.00" + +.CE +.PP +.SH ARITHMETICS +.TP +\fBadd\fR \fIx\fR \fIy\fR +.TP +\fBsub\fR \fIx\fR \fIy\fR +.TP +\fBmul\fR \fIx\fR \fIy\fR +Return the sum, difference and product of \fIx\fR by \fIy\fR. +\fIx\fR - may be either a BigFloat or an integer +\fIy\fR - may be either a BigFloat or an integer +When both are integers, these commands behave like \fBexpr\fR. +.TP +\fBdiv\fR \fIx\fR \fIy\fR +.TP +\fBmod\fR \fIx\fR \fIy\fR +Return the quotient and the rest of \fIx\fR divided by \fIy\fR. +Each argument (\fIx\fR and \fIy\fR) can be either a BigFloat or an integer, +but you cannot divide an integer by a BigFloat +Divide by zero throws an error. +.TP +\fBabs\fR \fIx\fR +Returns the absolute value of \fIx\fR +.TP +\fBopp\fR \fIx\fR +Returns the opposite of \fIx\fR +.TP +\fBpow\fR \fIx\fR \fIn\fR +Returns \fIx\fR taken to the \fIn\fRth power. +It only works if \fIn\fR is an integer. +\fIx\fR might be a BigFloat or an integer. +.PP +.SH COMPARISONS +.TP +\fBiszero\fR \fIx\fR +Returns 1 if \fIx\fR is : +.RS +.IP \(bu +a BigFloat close enough to zero to raise "divide by zero". +.IP \(bu +the integer 0. +.RE +.IP +See here how numbers that are close to zero are converted to strings: +.CS + + +tostr [fromstr 0.001] ; # -> 0.e-2 +tostr [fromstr 0.000000] ; # -> 0.e-5 +tostr [fromstr -0.000001] ; # -> 0.e-5 +tostr [fromstr 0.0] ; # -> 0. +tostr [fromstr 0.002] ; # -> 0.e-2 + +set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003 +tostr $a ; # 0.e-2 +iszero $a ; # false + +set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002 +tostr $a ; # 0.e-2 +iszero $a ; # true + +.CE +.TP +\fBequal\fR \fIx\fR \fIy\fR +Returns 1 if \fIx\fR and \fIy\fR are equal, 0 elsewhere. +.TP +\fBcompare\fR \fIx\fR \fIy\fR +Returns 0 if both BigFloat arguments are equal, +1 if \fIx\fR is greater than \fIy\fR, +and -1 if \fIx\fR is lower than \fIy\fR. +You would not be able to compare an integer to a BigFloat : +the operands should be both BigFloats, or both integers. +.PP +.SH ANALYSIS +.TP +\fBsqrt\fR \fIx\fR +.TP +\fBlog\fR \fIx\fR +.TP +\fBexp\fR \fIx\fR +.TP +\fBcos\fR \fIx\fR +.TP +\fBsin\fR \fIx\fR +.TP +\fBtan\fR \fIx\fR +.TP +\fBcotan\fR \fIx\fR +.TP +\fBacos\fR \fIx\fR +.TP +\fBasin\fR \fIx\fR +.TP +\fBatan\fR \fIx\fR +.TP +\fBcosh\fR \fIx\fR +.TP +\fBsinh\fR \fIx\fR +.TP +\fBtanh\fR \fIx\fR +The above functions return, respectively, the following : +square root, logarithm, exponential, cosine, sine, +tangent, cotangent, arc cosine, arc sine, arc tangent, hyperbolic +cosine, hyperbolic sine, hyperbolic tangent, of a BigFloat named \fIx\fR. +.TP +\fBpi\fR \fIn\fR +Returns a BigFloat representing the Pi constant with \fIn\fR digits after the dot. +\fIn\fR is a positive integer. +.TP +\fBrad2deg\fR \fIradians\fR +.TP +\fBdeg2rad\fR \fIdegrees\fR +\fIradians\fR - angle expressed in radians (BigFloat) +.sp +\fIdegrees\fR - angle expressed in degrees (BigFloat) +.sp +Convert an angle from radians to degrees, and \fIvice versa\fR. +.PP +.SH ROUNDING +.TP +\fBround\fR \fIx\fR +.TP +\fBceil\fR \fIx\fR +.TP +\fBfloor\fR \fIx\fR +The above functions return the \fIx\fR BigFloat, +rounded like with the same mathematical function in \fIexpr\fR, +and returns it as an integer. +.PP +.SH PRECISION +How do conversions work with precision ? +.IP \(bu +When a BigFloat is converted from string, the internal representation +holds its uncertainty as 1 at the level of the last digit. +.IP \(bu +During computations, the uncertainty of each result +is internally computed the closest to the reality, thus saving the memory used. +.IP \(bu +When converting back to string, the digits that are printed +are not subject to uncertainty. However, some rounding is done, as not doing so +causes severe problems. +.PP +Uncertainties are kept in the internal representation of the number ; +it is recommended to use \fBtostr\fR only for outputting data (on the screen or in a file), +and NEVER call \fBfromstr\fR with the result of \fBtostr\fR. +It is better to always keep operands in their internal representation. +Due to the internals of this library, the uncertainty interval may be slightly +wider than expected, but this should not cause false digits. +.PP +Now you may ask this question : What precision am I going to get +after calling add, sub, mul or div? +First you set a number from the string representation and, +by the way, its uncertainty is set: +.CS + + +set a [fromstr 1.230] +# $a belongs to [1.229, 1.231] +set a [fromstr 1.000] +# $a belongs to [0.999, 1.001] +# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value) + +.CE +The uncertainty of the sum, or the difference, of two numbers, is the sum +of their respective uncertainties. +.CS + + +set a [fromstr 1.230] +set b [fromstr 2.340] +set sum [add $a $b]] +# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2) +tostr $sum ; # 3.57 + +.CE +But when, for example, we add or substract an integer to a BigFloat, +the relative uncertainty of the result is unchanged. So it is desirable +not to convert integers to BigFloats: +.CS + + +set a [fromstr 0.999999999] +# now something dangerous +set b [fromstr 2.000] +# the result has only 3 digits +tostr [add $a $b] + +# how to keep precision at its maximum +puts [tostr [add $a 2]] + +.CE +.PP +For multiplication and division, the relative uncertainties of the product +or the quotient, is the sum of the relative uncertainties of the operands. +Take care of division by zero : check each divider with \fBiszero\fR. +.CS + + +set num [fromstr 4.00] +set denom [fromstr 0.01] + +puts [iszero $denom];# true +set quotient [div $num $denom];# error : divide by zero + +# opposites of our operands +puts [compare $num [opp $num]]; # 1 +puts [compare $denom [opp $denom]]; # 0 !!! +# No suprise ! 0 and its opposite are the same... + +.CE +Effects of the precision of a number considered equal to zero +to the cos function: +.CS + + +puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000 +puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000 +puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000 +puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000 + +.CE +BigFloats with different internal representations may be converted +to the same string. +.PP +For most analysis functions (cosine, square root, logarithm, etc.), determining the precision +of the result is difficult. +It seems however that in many cases, the loss of precision in the result +is of one or two digits. +There are some exceptions : for example, +.CS + + +tostr [exp [fromstr 100.0 10]] +# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry +# has 14 digits of precision. + +.CE +.SH "WHAT ABOUT TCL 8.4 ?" +If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be loaded, +switching back to \fImath::bigfloat\fR 1.2. Indeed, an important function introduced in Tcl 8.5 +is required - the ability to handle bignums, that we can do with \fBexpr\fR. +Before 8.5, this ability was provided by several packages, +including the pure-Tcl \fImath::bignum\fR package provided by \fItcllib\fR. +In this case, all you need to know, is that arguments to the commands explained here, +are expected to be in their internal representation. +So even with integers, you will need to call \fBfromstr\fR +and \fBtostr\fR in order to convert them between string and internal representations. +.CS + + +# +# with Tcl 8.5 +# ============ +set a [pi 20] +# round returns an integer and 'everything is a string' applies to integers +# whatever big they are +puts [round [mul $a 10000000000]] +# +# the same with Tcl 8.4 +# ===================== +set a [pi 20] +# bignums (arbitrary length integers) need a conversion hook +set b [fromstr 10000000000] +# round returns a bignum: +# before printing it, we need to convert it with 'tostr' +puts [tostr [round [mul $a $b]]] + +.CE +.SH "NAMESPACES AND OTHER PACKAGES" +We have not yet discussed about namespaces +because we assumed that you had imported public commands into the global namespace, +like this: +.CS + + +namespace import ::math::bigfloat::* + +.CE +If you matter much about avoiding names conflicts, +I considere it should be resolved by the following : +.CS + + +package require math::bigfloat +# beware: namespace ensembles are not available in Tcl 8.4 +namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat} +# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands +set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]] +puts [bigfloat tostr $a] + +.CE +.SH EXAMPLES +Guess what happens when you are doing some astronomy. Here is an example : +.CS + + +# convert acurrate angles with a millisecond-rated accuracy +proc degree-angle {degrees minutes seconds milliseconds} { + set result 0 + set div 1 + foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] { + # we convert each entry var into milliseconds + set div [expr {$div*$factor}] + incr result [expr {$var*$div}] + } + return [div [int2float $result] $div] +} +# load the package +package require math::bigfloat +namespace import ::math::bigfloat::* +# work with angles : a standard formula for navigation (taking bearings) +set angle1 [deg2rad [degree-angle 20 30 40 0]] +set angle2 [deg2rad [degree-angle 21 0 50 500]] +set opposite3 [deg2rad [degree-angle 51 0 50 500]] +set sinProduct [mul [sin $angle1] [sin $angle2]] +set cosProduct [mul [cos $angle1] [cos $angle2]] +set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]] +puts "angle3 : [tostr [rad2deg $angle3]]" + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: bignum :: float\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +computations, floating-point, interval, math, multiprecision, tcl +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr> + +.fi ADDED embedded/man/files/modules/math/bignum.n Index: embedded/man/files/modules/math/bignum.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/bignum.n @@ -0,0 +1,540 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/bignum.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Salvatore Sanfilippo <antirez at invece dot org> +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::bignum" n 3.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::bignum \- Arbitrary precision integer numbers +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBmath::bignum ?3.1?\fR +.sp +\fB::math::bignum::fromstr\fR \fIstring\fR ?\fIradix\fR? +.sp +\fB::math::bignum::tostr\fR \fIbignum\fR ?\fIradix\fR? +.sp +\fB::math::bignum::sign\fR \fIbignum\fR +.sp +\fB::math::bignum::abs\fR \fIbignum\fR +.sp +\fB::math::bignum::cmp\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::iszero\fR \fIbignum\fR +.sp +\fB::math::bignum::lt\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::le\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::gt\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::ge\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::eq\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::ne\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::isodd\fR \fIbignum\fR +.sp +\fB::math::bignum::iseven\fR \fIbignum\fR +.sp +\fB::math::bignum::add\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::sub\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::mul\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::divqr\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::div\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::rem\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::mod\fR \fIn\fR \fIm\fR +.sp +\fB::math::bignum::pow\fR \fIbase\fR \fIexp\fR +.sp +\fB::math::bignum::powm\fR \fIbase\fR \fIexp\fR \fIm\fR +.sp +\fB::math::bignum::sqrt\fR \fIbignum\fR +.sp +\fB::math::bignum::rand\fR \fIbits\fR +.sp +\fB::math::bignum::lshift\fR \fIbignum\fR \fIbits\fR +.sp +\fB::math::bignum::rshift\fR \fIbignum\fR \fIbits\fR +.sp +\fB::math::bignum::bitand\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::bitor\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::bitxor\fR \fIa\fR \fIb\fR +.sp +\fB::math::bignum::setbit\fR \fIbignumVar\fR \fIbit\fR +.sp +\fB::math::bignum::clearbit\fR \fIbignumVar\fR \fIbit\fR +.sp +\fB::math::bignum::testbit\fR \fIbignum\fR \fIbit\fR +.sp +\fB::math::bignum::bits\fR \fIbignum\fR +.sp +.BE +.SH DESCRIPTION +.PP +The bignum package provides arbitrary precision integer math +(also known as "big numbers") capabilities to the Tcl language. +Big numbers are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to: +.IP \(bu +perform math operations +.IP \(bu +convert bignums from the internal representation to a string in +the desired radix and vice versa. +.PP +But the two constants "0" and "1" are automatically converted to +the internal representation, in order to easily compare a number to zero, +or increment a big number. +.PP +The bignum interface is opaque, so +operations on bignums that are not returned by procedures +in this package (but created by hand) may lead to unspecified behaviours. +It's safe to treat bignums as pure values, so there is no need +to free a bignum, or to duplicate it via a special operation. +.SH EXAMPLES +This section shows some simple example. This library being just +a way to perform math operations, examples may be the simplest way +to learn how to work with it. Consult the API section of +this man page for information about individual procedures. +.PP +.CS + + + package require math::bignum + + # Multiplication of two bignums + set a [::math::bignum::fromstr 88888881111111] + set b [::math::bignum::fromstr 22222220000000] + set c [::math::bignum::mul $a $b] + puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000 + set c [::math::bignum::sqrt $c] + puts [::math::bignum::tostr $c] ; # => will output 44444440277777 + + # From/To string conversion in different radix + set a [::math::bignum::fromstr 1100010101010111001001111010111 2] + puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7 + + # Factorial example + proc fact n { + # fromstr is not needed for 0 and 1 + set z 1 + for {set i 2} {$i <= $n} {incr i} { + set z [::math::bignum::mul $z [::math::bignum::fromstr $i]] + } + return $z + } + + puts [::math::bignum::tostr [fact 100]] + +.CE +.SH API +.TP +\fB::math::bignum::fromstr\fR \fIstring\fR ?\fIradix\fR? +Convert \fIstring\fR into a bignum. If \fIradix\fR is omitted or zero, +the string is interpreted in hex if prefixed with +\fI0x\fR, in octal if prefixed with \fIox\fR, +in binary if it's pefixed with \fIbx\fR, as a number in +radix 10 otherwise. If instead the \fIradix\fR argument +is specified in the range 2-36, the \fIstring\fR is interpreted +in the given radix. Please note that this conversion is +not needed for two constants : \fI0\fR and \fI1\fR. (see the example) +.TP +\fB::math::bignum::tostr\fR \fIbignum\fR ?\fIradix\fR? +Convert \fIbignum\fR into a string representing the number +in the specified radix. If \fIradix\fR is omitted, the +default is 10. +.TP +\fB::math::bignum::sign\fR \fIbignum\fR +Return the sign of the bignum. +The procedure returns 0 if the number is positive, 1 if it's negative. +.TP +\fB::math::bignum::abs\fR \fIbignum\fR +Return the absolute value of the bignum. +.TP +\fB::math::bignum::cmp\fR \fIa\fR \fIb\fR +Compare the two bignums a and b, returning \fI0\fR if \fIa == b\fR, +\fI1\fR if \fIa > b\fR, and \fI-1\fR if \fIa < b\fR. +.TP +\fB::math::bignum::iszero\fR \fIbignum\fR +Return true if \fIbignum\fR value is zero, otherwise false is returned. +.TP +\fB::math::bignum::lt\fR \fIa\fR \fIb\fR +Return true if \fIa < b\fR, otherwise false is returned. +.TP +\fB::math::bignum::le\fR \fIa\fR \fIb\fR +Return true if \fIa <= b\fR, otherwise false is returned. +.TP +\fB::math::bignum::gt\fR \fIa\fR \fIb\fR +Return true if \fIa > b\fR, otherwise false is returned. +.TP +\fB::math::bignum::ge\fR \fIa\fR \fIb\fR +Return true if \fIa >= b\fR, otherwise false is returned. +.TP +\fB::math::bignum::eq\fR \fIa\fR \fIb\fR +Return true if \fIa == b\fR, otherwise false is returned. +.TP +\fB::math::bignum::ne\fR \fIa\fR \fIb\fR +Return true if \fIa != b\fR, otherwise false is returned. +.TP +\fB::math::bignum::isodd\fR \fIbignum\fR +Return true if \fIbignum\fR is odd. +.TP +\fB::math::bignum::iseven\fR \fIbignum\fR +Return true if \fIbignum\fR is even. +.TP +\fB::math::bignum::add\fR \fIa\fR \fIb\fR +Return the sum of the two bignums \fIa\fR and \fIb\fR. +.TP +\fB::math::bignum::sub\fR \fIa\fR \fIb\fR +Return the difference of the two bignums \fIa\fR and \fIb\fR. +.TP +\fB::math::bignum::mul\fR \fIa\fR \fIb\fR +Return the product of the two bignums \fIa\fR and \fIb\fR. +The implementation uses Karatsuba multiplication if both +the numbers are bigger than a given threshold, otherwise +the direct algorith is used. +.TP +\fB::math::bignum::divqr\fR \fIa\fR \fIb\fR +Return a two-elements list containing as first element +the quotient of the division between the two bignums +\fIa\fR and \fIb\fR, and the remainder of the division as second element. +.TP +\fB::math::bignum::div\fR \fIa\fR \fIb\fR +Return the quotient of the division between the two +bignums \fIa\fR and \fIb\fR. +.TP +\fB::math::bignum::rem\fR \fIa\fR \fIb\fR +Return the remainder of the division between the two +bignums \fIa\fR and \fIb\fR. +.TP +\fB::math::bignum::mod\fR \fIn\fR \fIm\fR +Return \fIn\fR modulo \fIm\fR. This operation is +called modular reduction. +.TP +\fB::math::bignum::pow\fR \fIbase\fR \fIexp\fR +Return \fIbase\fR raised to the exponent \fIexp\fR. +.TP +\fB::math::bignum::powm\fR \fIbase\fR \fIexp\fR \fIm\fR +Return \fIbase\fR raised to the exponent \fIexp\fR, +modulo \fIm\fR. This function is often used in the field +of cryptography. +.TP +\fB::math::bignum::sqrt\fR \fIbignum\fR +Return the integer part of the square root of \fIbignum\fR +.TP +\fB::math::bignum::rand\fR \fIbits\fR +Return a random number of at most \fIbits\fR bits. +The returned number is internally generated using Tcl's \fIexpr rand()\fR +function and is not suitable where an unguessable and cryptographically +secure random number is needed. +.TP +\fB::math::bignum::lshift\fR \fIbignum\fR \fIbits\fR +Return the result of left shifting \fIbignum\fR's binary +representation of \fIbits\fR positions on the left. +This is equivalent to multiplying by 2^\fIbits\fR but much faster. +.TP +\fB::math::bignum::rshift\fR \fIbignum\fR \fIbits\fR +Return the result of right shifting \fIbignum\fR's binary +representation of \fIbits\fR positions on the right. +This is equivalent to dividing by \fI2^bits\fR but much faster. +.TP +\fB::math::bignum::bitand\fR \fIa\fR \fIb\fR +Return the result of doing a bitwise AND operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined. +.TP +\fB::math::bignum::bitor\fR \fIa\fR \fIb\fR +Return the result of doing a bitwise OR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined. +.TP +\fB::math::bignum::bitxor\fR \fIa\fR \fIb\fR +Return the result of doing a bitwise XOR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined. +.TP +\fB::math::bignum::setbit\fR \fIbignumVar\fR \fIbit\fR +Set the bit at \fIbit\fR position to 1 in the bignum stored +in the variable \fIbignumVar\fR. Bit 0 is the least significant. +.TP +\fB::math::bignum::clearbit\fR \fIbignumVar\fR \fIbit\fR +Set the bit at \fIbit\fR position to 0 in the bignum stored +in the variable \fIbignumVar\fR. Bit 0 is the least significant. +.TP +\fB::math::bignum::testbit\fR \fIbignum\fR \fIbit\fR +Return true if the bit at the \fIbit\fR position of \fIbignum\fR +is on, otherwise false is returned. If \fIbit\fR is out of +range, it is considered as set to zero. +.TP +\fB::math::bignum::bits\fR \fIbignum\fR +Return the number of bits needed to represent bignum in radix 2. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: bignum\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +bignums, math, multiprecision, tcl +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Salvatore Sanfilippo <antirez at invece dot org> +Copyright (c) 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net> + +.fi ADDED embedded/man/files/modules/math/calculus.n Index: embedded/man/files/modules/math/calculus.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/calculus.n @@ -0,0 +1,719 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/calculus.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002,2003,2004 Arjen Markus +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::calculus" n 0.7.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::calculus \- Integration and ordinary differential equations +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmath::calculus 0.7.1\fR +.sp +\fB::math::calculus::integral\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIfunc\fR +.sp +\fB::math::calculus::integralExpr\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIexpression\fR +.sp +\fB::math::calculus::integral2D\fR \fIxinterval\fR \fIyinterval\fR \fIfunc\fR +.sp +\fB::math::calculus::integral2D_accurate\fR \fIxinterval\fR \fIyinterval\fR \fIfunc\fR +.sp +\fB::math::calculus::integral3D\fR \fIxinterval\fR \fIyinterval\fR \fIzinterval\fR \fIfunc\fR +.sp +\fB::math::calculus::integral3D_accurate\fR \fIxinterval\fR \fIyinterval\fR \fIzinterval\fR \fIfunc\fR +.sp +\fB::math::calculus::eulerStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +.sp +\fB::math::calculus::heunStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +.sp +\fB::math::calculus::rungeKuttaStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +.sp +\fB::math::calculus::boundaryValueSecondOrder\fR \fIcoeff_func\fR \fIforce_func\fR \fIleftbnd\fR \fIrightbnd\fR \fInostep\fR +.sp +\fB::math::calculus::solveTriDiagonal\fR \fIacoeff\fR \fIbcoeff\fR \fIccoeff\fR \fIdvalue\fR +.sp +\fB::math::calculus::newtonRaphson\fR \fIfunc\fR \fIderiv\fR \fIinitval\fR +.sp +\fB::math::calculus::newtonRaphsonParameters\fR \fImaxiter\fR \fItolerance\fR +.sp +\fB::math::calculus::regula_falsi\fR \fIf\fR \fIxb\fR \fIxe\fR \fIeps\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package implements several simple mathematical algorithms: +.IP \(bu +The integration of a function over an interval +.IP \(bu +The numerical integration of a system of ordinary differential +equations. +.IP \(bu +Estimating the root(s) of an equation of one variable. +.PP +.PP +The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, well-known +algorithms have been used in a straightforward manner. +.PP +This document describes the procedures and explains their usage. +.SH PROCEDURES +This package defines the following public procedures: +.TP +\fB::math::calculus::integral\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIfunc\fR +Determine the integral of the given function using the Simpson +rule. The interval for the integration is [\fIbegin\fR, \fIend\fR]. +The remaining arguments are: +.RS +.TP +\fInosteps\fR +Number of steps in which the interval is divided. +.TP +\fIfunc\fR +Function to be integrated. It should take one single argument. +.RE +.sp +.TP +\fB::math::calculus::integralExpr\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIexpression\fR +Similar to the previous proc, this one determines the integral of +the given \fIexpression\fR using the Simpson rule. +The interval for the integration is [\fIbegin\fR, \fIend\fR]. +The remaining arguments are: +.RS +.TP +\fInosteps\fR +Number of steps in which the interval is divided. +.TP +\fIexpression\fR +Expression to be integrated. It should +use the variable "x" as the only variable (the "integrate") +.RE +.sp +.TP +\fB::math::calculus::integral2D\fR \fIxinterval\fR \fIyinterval\fR \fIfunc\fR +.TP +\fB::math::calculus::integral2D_accurate\fR \fIxinterval\fR \fIyinterval\fR \fIfunc\fR +The commands \fBintegral2D\fR and \fBintegral2D_accurate\fR calculate the +integral of a function of two variables over the rectangle given by the +first two arguments, each a list of three items, the start and +stop interval for the variable and the number of steps. +.sp +The command \fBintegral2D\fR evaluates the function at the centre of +each rectangle, whereas the command \fBintegral2D_accurate\fR uses a +four-point quadrature formula. This results in an exact integration of +polynomials of third degree or less. +.sp +The function must take two arguments and return the function +value. +.TP +\fB::math::calculus::integral3D\fR \fIxinterval\fR \fIyinterval\fR \fIzinterval\fR \fIfunc\fR +.TP +\fB::math::calculus::integral3D_accurate\fR \fIxinterval\fR \fIyinterval\fR \fIzinterval\fR \fIfunc\fR +The commands \fBintegral3D\fR and \fBintegral3D_accurate\fR are the +three-dimensional equivalent of \fBintegral2D\fR and \fBintegral3D_accurate\fR. +The function \fIfunc\fR takes three arguments and is integrated over the block in +3D space given by three intervals. +.TP +\fB::math::calculus::eulerStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +Set a single step in the numerical integration of a system of +differential equations. The method used is Euler's. +.RS +.TP +\fIt\fR +Value of the independent variable (typically time) +at the beginning of the step. +.TP +\fItstep\fR +Step size for the independent variable. +.TP +\fIxvec\fR +List (vector) of dependent values +.TP +\fIfunc\fR +Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match). +.RE +.sp +.TP +\fB::math::calculus::heunStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +Set a single step in the numerical integration of a system of +differential equations. The method used is Heun's. +.RS +.TP +\fIt\fR +Value of the independent variable (typically time) +at the beginning of the step. +.TP +\fItstep\fR +Step size for the independent variable. +.TP +\fIxvec\fR +List (vector) of dependent values +.TP +\fIfunc\fR +Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match). +.RE +.sp +.TP +\fB::math::calculus::rungeKuttaStep\fR \fIt\fR \fItstep\fR \fIxvec\fR \fIfunc\fR +Set a single step in the numerical integration of a system of +differential equations. The method used is Runge-Kutta 4th +order. +.RS +.TP +\fIt\fR +Value of the independent variable (typically time) +at the beginning of the step. +.TP +\fItstep\fR +Step size for the independent variable. +.TP +\fIxvec\fR +List (vector) of dependent values +.TP +\fIfunc\fR +Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match). +.RE +.sp +.TP +\fB::math::calculus::boundaryValueSecondOrder\fR \fIcoeff_func\fR \fIforce_func\fR \fIleftbnd\fR \fIrightbnd\fR \fInostep\fR +Solve a second order linear differential equation with boundary +values at two sides. The equation has to be of the form (the +"conservative" form): +.CS + + + d dy d + -- A(x)-- + -- B(x)y + C(x)y = D(x) + dx dx dx + +.CE +.IP +Ordinarily, such an equation would be written as: +.CS + + + d2y dy + a(x)--- + b(x)-- + c(x) y = D(x) + dx2 dx + +.CE +.IP +The first form is easier to discretise (by integrating over a +finite volume) than the second form. The relation between the two +forms is fairly straightforward: +.CS + + + A(x) = a(x) + B(x) = b(x) - a'(x) + C(x) = c(x) - B'(x) = c(x) - b'(x) + a''(x) + +.CE +.IP +Because of the differentiation, however, it is much easier to ask +the user to provide the functions A, B and C directly. +.RS +.TP +\fIcoeff_func\fR +Procedure returning the three coefficients +(A, B, C) of the equation, taking as its one argument the x-coordinate. +.TP +\fIforce_func\fR +Procedure returning the right-hand side +(D) as a function of the x-coordinate. +.TP +\fIleftbnd\fR +A list of two values: the x-coordinate of the +left boundary and the value at that boundary. +.TP +\fIrightbnd\fR +A list of two values: the x-coordinate of the +right boundary and the value at that boundary. +.TP +\fInostep\fR +Number of steps by which to discretise the +interval. +The procedure returns a list of x-coordinates and the approximated +values of the solution. +.RE +.sp +.TP +\fB::math::calculus::solveTriDiagonal\fR \fIacoeff\fR \fIbcoeff\fR \fIccoeff\fR \fIdvalue\fR +Solve a system of linear equations Ax = b with A a tridiagonal +matrix. Returns the solution as a list. +.RS +.TP +\fIacoeff\fR +List of values on the lower diagonal +.TP +\fIbcoeff\fR +List of values on the main diagonal +.TP +\fIccoeff\fR +List of values on the upper diagonal +.TP +\fIdvalue\fR +List of values on the righthand-side +.RE +.sp +.TP +\fB::math::calculus::newtonRaphson\fR \fIfunc\fR \fIderiv\fR \fIinitval\fR +Determine the root of an equation given by +.CS + + + func(x) = 0 + +.CE +.IP +using the method of Newton-Raphson. The procedure takes the following +arguments: +.RS +.TP +\fIfunc\fR +Procedure that returns the value the function at x +.TP +\fIderiv\fR +Procedure that returns the derivative of the function at x +.TP +\fIinitval\fR +Initial value for x +.RE +.sp +.TP +\fB::math::calculus::newtonRaphsonParameters\fR \fImaxiter\fR \fItolerance\fR +Set the numerical parameters for the Newton-Raphson method: +.RS +.TP +\fImaxiter\fR +Maximum number of iteration steps (defaults to 20) +.TP +\fItolerance\fR +Relative precision (defaults to 0.001) +.RE +.TP +\fB::math::calculus::regula_falsi\fR \fIf\fR \fIxb\fR \fIxe\fR \fIeps\fR +Return an estimate of the zero or one of the zeros of the function +contained in the interval [xb,xe]. The error in this estimate is of the +order of eps*abs(xe-xb), the actual error may be slightly larger. +.sp +The method used is the so-called \fIregula falsi\fR or +\fIfalse position\fR method. It is a straightforward implementation. +The method is robust, but requires that the interval brackets a zero or +at least an uneven number of zeros, so that the value of the function at +the start has a different sign than the value at the end. +.sp +In contrast to Newton-Raphson there is no need for the computation of +the function's derivative. +.RS +.TP +command \fIf\fR +Name of the command that evaluates the function for +which the zero is to be returned +.TP +float \fIxb\fR +Start of the interval in which the zero is supposed +to lie +.TP +float \fIxe\fR +End of the interval +.TP +float \fIeps\fR +Relative allowed error (defaults to 1.0e-4) +.RE +.PP +.PP +\fINotes:\fR +.PP +Several of the above procedures take the \fInames\fR of procedures as +arguments. To avoid problems with the \fIvisibility\fR of these +procedures, the fully-qualified name of these procedures is determined +inside the calculus routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance: +.CS + + + namespace eval ::mySpace { + namespace export calcfunc + proc calcfunc { x } { return $x } + } + # + # Use a fully-qualified name + # + namespace eval ::myCalc { + proc detIntegral { begin end } { + return [integral $begin $end 100 ::mySpace::calcfunc] + } + } + # + # Import the name + # + namespace eval ::myCalc { + namespace import ::mySpace::calcfunc + proc detIntegral { begin end } { + return [integral $begin $end 100 calcfunc] + } + } + +.CE +.PP +Enhancements for the second-order boundary value problem: +.IP \(bu +Other types of boundary conditions (zero gradient, zero flux) +.IP \(bu +Other schematisation of the first-order term (now central +differences are used, but upstream differences might be useful too). +.PP +.SH EXAMPLES +Let us take a few simple examples: +.PP +Integrate x over the interval [0,100] (20 steps): +.CS + + +proc linear_func { x } { return $x } +puts "Integral: [::math::calculus::integral 0 100 20 linear_func]" + +.CE +For simple functions, the alternative could be: +.CS + + +puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]" + +.CE +Do not forget the braces! +.PP +The differential equation for a dampened oscillator: +.PP +.CS + + +x'' + rx' + wx = 0 + +.CE +.PP +can be split into a system of first-order equations: +.PP +.CS + + +x' = y +y' = -ry - wx + +.CE +.PP +Then this system can be solved with code like this: +.PP +.CS + + +proc dampened_oscillator { t xvec } { + set x [lindex $xvec 0] + set x1 [lindex $xvec 1] + return [list $x1 [expr {-$x1-$x}]] +} + +set xvec { 1.0 0.0 } +set t 0.0 +set tstep 0.1 +for { set i 0 } { $i < 20 } { incr i } { + set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator] + puts "Result ($t): $result" + set t [expr {$t+$tstep}] + set xvec $result +} + +.CE +.PP +Suppose we have the boundary value problem: +.PP +.CS + + + Dy'' + ky = 0 + x = 0: y = 1 + x = L: y = 0 + +.CE +.PP +This boundary value problem could originate from the diffusion of a +decaying substance. +.PP +It can be solved with the following fragment: +.PP +.CS + + + proc coeffs { x } { return [list $::Diff 0.0 $::decay] } + proc force { x } { return 0.0 } + + set Diff 1.0e-2 + set decay 0.0001 + set length 100.0 + + set y [::math::calculus::boundaryValueSecondOrder \\ + coeffs force {0.0 1.0} [list $length 0.0] 100] + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: calculus\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +romberg +.SH KEYWORDS +calculus, differential equations, integration, math, roots +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2002,2003,2004 Arjen Markus + +.fi ADDED embedded/man/files/modules/math/combinatorics.n Index: embedded/man/files/modules/math/combinatorics.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/combinatorics.n @@ -0,0 +1,347 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/combinatorics.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::combinatorics" n 1.2.3 tcllib "Tcl Math Library" +.BS +.SH NAME +math::combinatorics \- Combinatorial functions in the Tcl Math Library +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmath ?1.2.3?\fR +.sp +\fB::math::ln_Gamma\fR \fIz\fR +.sp +\fB::math::factorial\fR \fIx\fR +.sp +\fB::math::choose\fR \fIn k\fR +.sp +\fB::math::Beta\fR \fIz w\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath\fR package contains implementations of several +functions useful in combinatorial problems. +.SH COMMANDS +.TP +\fB::math::ln_Gamma\fR \fIz\fR +Returns the natural logarithm of the Gamma function for the argument +\fIz\fR. +.sp +The Gamma function is defined as the improper integral from zero to +positive infinity of +.CS + + + t**(x-1)*exp(-t) dt + +.CE +.sp +The approximation used in the Tcl Math Library is from Lanczos, +\fIISIAM J. Numerical Analysis, series B,\fR volume 1, p. 86. +For "\fBx\fR > 1", the absolute error of the result is claimed to be +smaller than 5.5*10**-10 -- that is, the resulting value of Gamma when +.CS + + + exp( ln_Gamma( x) ) + +.CE +.IP +is computed is expected to be precise to better than nine significant +figures. +.TP +\fB::math::factorial\fR \fIx\fR +Returns the factorial of the argument \fIx\fR. +.sp +For integer \fIx\fR, 0 <= \fIx\fR <= 12, an exact integer result is +returned. +.sp +For integer \fIx\fR, 13 <= \fIx\fR <= 21, an exact floating-point +result is returned on machines with IEEE floating point. +.sp +For integer \fIx\fR, 22 <= \fIx\fR <= 170, the result is exact to 1 +ULP. +.sp +For real \fIx\fR, \fIx\fR >= 0, the result is approximated by +computing \fIGamma(x+1)\fR using the \fB::math::ln_Gamma\fR +function, and the result is expected to be precise to better than nine +significant figures. +.sp +It is an error to present \fIx\fR <= -1 or \fIx\fR > 170, or a value +of \fIx\fR that is not numeric. +.TP +\fB::math::choose\fR \fIn k\fR +Returns the binomial coefficient \fIC(n, k)\fR +.CS + + + C(n,k) = n! / k! (n-k)! + +.CE +.IP +If both parameters are integers and the result fits in 32 bits, the +result is rounded to an integer. +.sp +Integer results are exact up to at least \fIn\fR = 34. Floating point +results are precise to better than nine significant figures. +.TP +\fB::math::Beta\fR \fIz w\fR +Returns the Beta function of the parameters \fIz\fR and \fIw\fR. +.CS + + + Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w) + +.CE +.IP +Results are returned as a floating point number precise to better than +nine significant digits provided that \fIw\fR and \fIz\fR are both at +least 1. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH CATEGORY +Mathematics ADDED embedded/man/files/modules/math/constants.n Index: embedded/man/files/modules/math/constants.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/constants.n @@ -0,0 +1,348 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/constants.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::constants" n 1.0.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::constants \- Mathematical and numerical constants +.SH SYNOPSIS +package require \fBTcl ?8.3?\fR +.sp +package require \fBmath::constants ?1.0.1?\fR +.sp +\fB::math::constants::constants\fR \fIargs\fR +.sp +\fB::math::constants::print-constants\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package defines some common mathematical and numerical constants. +By using the package you get consistent values for numbers like pi and +ln(10). +.PP +It defines two commands: +.IP \(bu +One for importing the constants +.IP \(bu +One for reporting which constants are defined and what values they +actually have. +.PP +.PP +The motivation for this package is that quite often, with +(mathematical) computations, you need a good approximation to, say, +the ratio of degrees to radians. You can, of course, define this +like: +.CS + + + variable radtodeg [expr {180.0/(4.0*atan(1.0))}] + +.CE +and use the variable radtodeg whenever you need the conversion. +.PP +This has two drawbacks: +.IP \(bu +You need to remember the proper formula or value and that is +error-prone. +.IP \(bu +Especially with the use of mathematical functions like \fIatan\fR +you assume that they have been accurately implemented. This is seldom or +never the case and for each platform you can get subtle differences. +.PP +Here is the way you can do it with the \fImath::constants\fR package: +.CS + + + package require math::constants + ::math::constants::constants radtodeg degtorad + +.CE +which creates two variables, radtodeg and (its reciprocal) degtorad +in the calling namespace. +.PP +Constants that have been defined (their values are mostly taken +from mathematical tables with more precision than usually can be +handled) include: +.IP \(bu +basic constants like pi, e, gamma (Euler's constant) +.IP \(bu +derived values like ln(10) and sqrt(2) +.IP \(bu +purely numerical values such as 1/3 that are included for convenience +and for the fact that certain seemingly trivial computations like: +.CS + + + set value [expr {3.0*$onethird}] + +.CE +.IP +give \fIexactly\fR the value you expect (if IEEE arithmetic is +available). +.PP +.SH PROCEDURES +The package defines the following public procedures: +.TP +\fB::math::constants::constants\fR \fIargs\fR +Import the constants whose names are given as arguments +.sp +.TP +\fB::math::constants::print-constants\fR \fIargs\fR +Print the constants whose names are given as arguments on the screen +(name, value and description) or, if no arguments are given, print all +defined constants. This is mainly a convenience procedure. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: constants\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +constants, degrees, e, math, pi, radians +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/decimal.n Index: embedded/man/files/modules/math/decimal.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/decimal.n @@ -0,0 +1,525 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/decimal.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011 Mark Alston <mark at beernut dot com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::decimal" n 1.0.2 tcllib "Tcl Decimal Arithmetic Library" +.BS +.SH NAME +math::decimal \- General decimal arithmetic +.SH SYNOPSIS +package require \fBTcl ?8.5?\fR +.sp +\fB::math::decimal::fromstr\fR \fIstring\fR +.sp +\fB::math::decimal::tostr\fR \fIdecimal\fR +.sp +\fB::math::decimal::setVariable\fR \fIvariable\fR \fIsetting\fR +.sp +\fB::math::decimal::add\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::+\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::subtract\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::-\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::multiply\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::*\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::divide\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::/\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::divideint\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::remainder\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::abs\fR \fIdecimal\fR +.sp +\fB::math::decimal::compare\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::max\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::maxmag\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::min\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::minmag\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::plus\fR \fIa\fR +.sp +\fB::math::decimal::minus\fR \fIa\fR +.sp +\fB::math::decimal::copynegate\fR \fIa\fR +.sp +\fB::math::decimal::copysign\fR \fIa\fR \fIb\fR +.sp +\fB::math::decimal::is-signed\fR \fIdecimal\fR +.sp +\fB::math::decimal::is-zero\fR \fIdecimal\fR +.sp +\fB::math::decimal::is-NaN\fR \fIdecimal\fR +.sp +\fB::math::decimal::is-infinite\fR \fIdecimal\fR +.sp +\fB::math::decimal::is-finite\fR \fIdecimal\fR +.sp +\fB::math::decimal::fma\fR \fIa\fR \fIb\fR \fIc\fR +.sp +\fB::math::decimal::round_half_even\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_half_up\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_half_down\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_down\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_up\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_floor\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_ceiling\fR \fIdecimal\fR \fIdigits\fR +.sp +\fB::math::decimal::round_05up\fR \fIdecimal\fR \fIdigits\fR +.sp +.BE +.SH DESCRIPTION +.PP +The decimal package provides decimal arithmetic support for both limited +precision floating point and arbitrary precision floating point. +Additionally, integer arithmetic is supported. +.PP +More information and the specifications on which this package depends can be +found on the general decimal arithmetic page at http://speleotrove.com/decimal +This package provides for: +.IP \(bu +A new data type decimal which is represented as a list containing sign, +mantissa and exponent. +.IP \(bu +Arithmetic operations on those decimal numbers such as addition, subtraction, +multiplication, etc... +.PP +.PP +Numbers are converted to decimal format using the operation ::math::decimal::fromstr. +.PP +Numbers are converted back to string format using the operation +::math::decimal::tostr. +.PP +.SH EXAMPLES +This section shows some simple examples. Since the purpose of this library +is to perform decimal math operations, examples may be the simplest way +to learn how to work with it and to see the difference between using this +package and sticking with expr. Consult the API section of +this man page for information about individual procedures. +.PP +.CS + + + package require decimal + + # Various operations on two numbers. + # We first convert them to decimal format. + set a [::math::decimal::fromstr 8.2] + set b [::math::decimal::fromstr .2] + + # Then we perform our operations. Here we multiply + set c [::math::decimal::* $a $b] + + # Finally we convert back to string format for presentation to the user. + puts [::math::decimal::tostr $c] ; # => will output 8.4 + + # Other examples + # + # Subtraction + set c [::math::decimal::- $a $b] + puts [::math::decimal::tostr $c] ; # => will output 8.0 + + # Why bother using this instead of simply expr? + puts 8.399999999999999 ; # => will output 8.399999999999999 + puts 7.999999999999999 ; # => will output 7.999999999999999 + # See http://speleotrove.com/decimal to learn more about why this happens. + +.CE +.SH API +.TP +\fB::math::decimal::fromstr\fR \fIstring\fR +Convert \fIstring\fR into a decimal. +.TP +\fB::math::decimal::tostr\fR \fIdecimal\fR +Convert \fIdecimal\fR into a string representing the number in base 10. +.TP +\fB::math::decimal::setVariable\fR \fIvariable\fR \fIsetting\fR +Sets the \fIvariable\fR to \fIsetting\fR. Valid variables are: +.RS +.IP \(bu +\fIrounding\fR - Method of rounding to use during rescale. Valid +methods are round_half_even, round_half_up, round_half_down, +round_down, round_up, round_floor, round_ceiling. +.IP \(bu +\fIprecision\fR - Maximum number of digits allowed in mantissa. +.IP \(bu +\fIextended\fR - Set to 1 for extended mode. 0 for simplified mode. +.IP \(bu +\fImaxExponent\fR - Maximum value for the exponent. Defaults to 999. +.IP \(bu +\fIminExponent\fR - Minimum value for the exponent. Default to -998. +.RE +.TP +\fB::math::decimal::add\fR \fIa\fR \fIb\fR +.TP +\fB::math::decimal::+\fR \fIa\fR \fIb\fR +Return the sum of the two decimals \fIa\fR and \fIb\fR. +.TP +\fB::math::decimal::subtract\fR \fIa\fR \fIb\fR +.TP +\fB::math::decimal::-\fR \fIa\fR \fIb\fR +Return the differnece of the two decimals \fIa\fR and \fIb\fR. +.TP +\fB::math::decimal::multiply\fR \fIa\fR \fIb\fR +.TP +\fB::math::decimal::*\fR \fIa\fR \fIb\fR +Return the product of the two decimals \fIa\fR and \fIb\fR. +.TP +\fB::math::decimal::divide\fR \fIa\fR \fIb\fR +.TP +\fB::math::decimal::/\fR \fIa\fR \fIb\fR +Return the quotient of the division between the two +decimals \fIa\fR and \fIb\fR. +.TP +\fB::math::decimal::divideint\fR \fIa\fR \fIb\fR +Return a the integer portion of the quotient of the division between +decimals \fIa\fR and \fIb\fR +.TP +\fB::math::decimal::remainder\fR \fIa\fR \fIb\fR +Return the remainder of the division between the two +decimals \fIa\fR and \fIb\fR. +.TP +\fB::math::decimal::abs\fR \fIdecimal\fR +Return the absolute value of the decimal. +.TP +\fB::math::decimal::compare\fR \fIa\fR \fIb\fR +Compare the two decimals a and b, returning \fI0\fR if \fIa == b\fR, +\fI1\fR if \fIa > b\fR, and \fI-1\fR if \fIa < b\fR. +.TP +\fB::math::decimal::max\fR \fIa\fR \fIb\fR +Compare the two decimals a and b, and return \fIa\fR if \fIa >= b\fR, and \fIb\fR if \fIa < b\fR. +.TP +\fB::math::decimal::maxmag\fR \fIa\fR \fIb\fR +Compare the two decimals a and b while ignoring their signs, and return \fIa\fR if \fIabs(a) >= abs(b)\fR, and \fIb\fR if \fIabs(a) < abs(b)\fR. +.TP +\fB::math::decimal::min\fR \fIa\fR \fIb\fR +Compare the two decimals a and b, and return \fIa\fR if \fIa <= b\fR, and \fIb\fR if \fIa > b\fR. +.TP +\fB::math::decimal::minmag\fR \fIa\fR \fIb\fR +Compare the two decimals a and b while ignoring their signs, and return \fIa\fR if \fIabs(a) <= abs(b)\fR, and \fIb\fR if \fIabs(a) > abs(b)\fR. +.TP +\fB::math::decimal::plus\fR \fIa\fR +Return the result from \fI::math::decimal::+ 0 $a\fR. +.TP +\fB::math::decimal::minus\fR \fIa\fR +Return the result from \fI::math::decimal::- 0 $a\fR. +.TP +\fB::math::decimal::copynegate\fR \fIa\fR +Returns \fIa\fR with the sign flipped. +.TP +\fB::math::decimal::copysign\fR \fIa\fR \fIb\fR +Returns \fIa\fR with the sign set to the sign of the \fIb\fR. +.TP +\fB::math::decimal::is-signed\fR \fIdecimal\fR +Return the sign of the decimal. +The procedure returns 0 if the number is positive, 1 if it's negative. +.TP +\fB::math::decimal::is-zero\fR \fIdecimal\fR +Return true if \fIdecimal\fR value is zero, otherwise false is returned. +.TP +\fB::math::decimal::is-NaN\fR \fIdecimal\fR +Return true if \fIdecimal\fR value is NaN (not a number), otherwise false is returned. +.TP +\fB::math::decimal::is-infinite\fR \fIdecimal\fR +Return true if \fIdecimal\fR value is Infinite, otherwise false is returned. +.TP +\fB::math::decimal::is-finite\fR \fIdecimal\fR +Return true if \fIdecimal\fR value is finite, otherwise false is returned. +.TP +\fB::math::decimal::fma\fR \fIa\fR \fIb\fR \fIc\fR +Return the result from first multiplying \fIa\fR by \fIb\fR and then adding \fIc\fR. Rescaling only occurs after completion of all operations. In this way the result may vary from that returned by performing the operations individually. +.TP +\fB::math::decimal::round_half_even\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round to the nearest. If equidistant, round so the final digit is even. +.TP +\fB::math::decimal::round_half_up\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round to the nearest. If equidistant, round up. +.TP +\fB::math::decimal::round_half_down\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round to the nearest. If equidistant, round down. +.TP +\fB::math::decimal::round_down\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round toward 0. (Truncate) +.TP +\fB::math::decimal::round_up\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round away from 0 +.TP +\fB::math::decimal::round_floor\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round toward -Infinity. +.TP +\fB::math::decimal::round_ceiling\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round toward Infinity +.TP +\fB::math::decimal::round_05up\fR \fIdecimal\fR \fIdigits\fR +Rounds \fIdecimal\fR to \fIdigits\fR number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow +the result is the same as for round-down. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIDecimal\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +decimal, math, tcl +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2011 Mark Alston <mark at beernut dot com> + +.fi ADDED embedded/man/files/modules/math/fourier.n Index: embedded/man/files/modules/math/fourier.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/fourier.n @@ -0,0 +1,386 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/fourier.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::fourier" n 1.0.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::fourier \- Discrete and fast fourier transforms +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmath::fourier 1.0.2\fR +.sp +\fB::math::fourier::dft\fR \fIin_data\fR +.sp +\fB::math::fourier::inverse_dft\fR \fIin_data\fR +.sp +\fB::math::fourier::lowpass\fR \fIcutoff\fR \fIin_data\fR +.sp +\fB::math::fourier::highpass\fR \fIcutoff\fR \fIin_data\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath::fourier\fR package implements two versions of discrete +Fourier transforms, the ordinary transform and the fast Fourier +transform. It also provides a few simple filter procedures as an +illustrations of how such filters can be implemented. +.PP +The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. We also refer to the original Wiki page on the subject +which describes some of the considerations behind the current +implementation. +.SH "GENERAL INFORMATION" +The two top-level procedures defined are +.IP \(bu +dft data-list +.IP \(bu +inverse_dft data-list +.PP +Both take a list of \fIcomplex numbers\fR and apply a Discrete Fourier +Transform (DFT) or its inverse respectively to these lists of numbers. +A "complex number" in this case is either (i) a pair (two element list) of +numbers, interpreted as the real and imaginary parts of the complex number, +or (ii) a single number, interpreted as the real part of a complex number +whose imaginary part is zero. The return value is always in the +first format. (The DFT generally produces complex results even if the +input is purely real.) Applying first one and then the other of these +procedures to a list of complex numbers will (modulo rounding errors +due to floating point arithmetic) return the original list of numbers. +.PP +If the input length N is a power of two then these procedures will +utilize the O(N log N) Fast Fourier Transform algorithm. If input +length is not a power of two then the DFT will instead be computed +using a the naive quadratic algorithm. +.PP +Some examples: +.CS + + + % dft {1 2 3 4} + {10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0} + % inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}} + {1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0} + % dft {1 2 3 4 5} + {15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118} + % inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}} + {1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17} + +.CE +.PP +In the last case, the imaginary parts <1e-16 would have been zero in exact +arithmetic, but aren't here due to rounding errors. +.PP +Internally, the procedures use a flat list format where every even +index element of a list is a real part and every odd index element +is an imaginary part. This is reflected in the variable names by Re_ +and Im_ prefixes. +.PP +The package includes two simple filters. They have an analogue +equivalent in a simple electronic circuit, a resistor and a capacitance +in series. Using these filters requires the +\fBmath::complexnumbers\fR package. +.SH PROCEDURES +The public Fourier transform procedures are: +.TP +\fB::math::fourier::dft\fR \fIin_data\fR +Determine the \fIFourier transform\fR of the given list of complex +numbers. The result is a list of complex numbers representing the +(complex) amplitudes of the Fourier components. +.RS +.TP +list \fIin_data\fR +List of data +.RE +.sp +.TP +\fB::math::fourier::inverse_dft\fR \fIin_data\fR +Determine the \fIinverse Fourier transform\fR of the given list of +complex numbers (interpreted as amplitudes). The result is a list of +complex numbers representing the original (complex) data +.RS +.TP +list \fIin_data\fR +List of data (amplitudes) +.RE +.sp +.TP +\fB::math::fourier::lowpass\fR \fIcutoff\fR \fIin_data\fR +Filter the (complex) amplitudes so that high-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance. +.RS +.TP +float \fIcutoff\fR +Cut-off frequency +.TP +list \fIin_data\fR +List of data (amplitudes) +.RE +.sp +.TP +\fB::math::fourier::highpass\fR \fIcutoff\fR \fIin_data\fR +Filter the (complex) amplitudes so that low-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance. +.RS +.TP +float \fIcutoff\fR +Cut-off frequency +.TP +list \fIin_data\fR +List of data (amplitudes) +.RE +.sp +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: fourier\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +FFT, Fourier transform, complex numbers, mathematics +.SH CATEGORY +Mathematics ADDED embedded/man/files/modules/math/fuzzy.n Index: embedded/man/files/modules/math/fuzzy.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/fuzzy.n @@ -0,0 +1,388 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/fuzzy.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::fuzzy" n 0.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::fuzzy \- Fuzzy comparison of floating-point numbers +.SH SYNOPSIS +package require \fBTcl ?8.3?\fR +.sp +package require \fBmath::fuzzy ?0.2?\fR +.sp +\fB::math::fuzzy::teq\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tne\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tge\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tle\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tlt\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tgt\fR \fIvalue1\fR \fIvalue2\fR +.sp +\fB::math::fuzzy::tfloor\fR \fIvalue\fR +.sp +\fB::math::fuzzy::tceil\fR \fIvalue\fR +.sp +\fB::math::fuzzy::tround\fR \fIvalue\fR +.sp +\fB::math::fuzzy::troundn\fR \fIvalue\fR \fIndigits\fR +.sp +.BE +.SH DESCRIPTION +.PP +The package Fuzzy is meant to solve common problems with floating-point +numbers in a systematic way: +.IP \(bu +Comparing two numbers that are "supposed" to be identical, like +1.0 and 2.1/(1.2+0.9) is not guaranteed to give the +intuitive result. +.IP \(bu +Rounding a number that is halfway two integer numbers can cause +strange errors, like int(100.0*2.8) != 28 but 27 +.PP +.PP +The Fuzzy package is meant to help sorting out this type of problems +by defining "fuzzy" comparison procedures for floating-point numbers. +It does so by allowing for a small margin that is determined +automatically - the margin is three times the "epsilon" value, that is +three times the smallest number \fIeps\fR such that 1.0 and 1.0+$eps +canbe distinguished. In Tcl, which uses double precision floating-point +numbers, this is typically 1.1e-16. +.SH PROCEDURES +Effectively the package provides the following procedures: +.TP +\fB::math::fuzzy::teq\fR \fIvalue1\fR \fIvalue2\fR +Compares two floating-point numbers and returns 1 if their values +fall within a small range. Otherwise it returns 0. +.TP +\fB::math::fuzzy::tne\fR \fIvalue1\fR \fIvalue2\fR +Returns the negation, that is, if the difference is larger than +the margin, it returns 1. +.TP +\fB::math::fuzzy::tge\fR \fIvalue1\fR \fIvalue2\fR +Compares two floating-point numbers and returns 1 if their values +either fall within a small range or if the first number is larger +than the second. Otherwise it returns 0. +.TP +\fB::math::fuzzy::tle\fR \fIvalue1\fR \fIvalue2\fR +Returns 1 if the two numbers are equal according to +[teq] or if the first is smaller than the second. +.TP +\fB::math::fuzzy::tlt\fR \fIvalue1\fR \fIvalue2\fR +Returns the opposite of [tge]. +.TP +\fB::math::fuzzy::tgt\fR \fIvalue1\fR \fIvalue2\fR +Returns the opposite of [tle]. +.TP +\fB::math::fuzzy::tfloor\fR \fIvalue\fR +Returns the integer number that is lower or equal +to the given floating-point number, within a well-defined +tolerance. +.TP +\fB::math::fuzzy::tceil\fR \fIvalue\fR +Returns the integer number that is greater or equal to the given +floating-point number, within a well-defined tolerance. +.TP +\fB::math::fuzzy::tround\fR \fIvalue\fR +Rounds the floating-point number off. +.TP +\fB::math::fuzzy::troundn\fR \fIvalue\fR \fIndigits\fR +Rounds the floating-point number off to the +specified number of decimals (Pro memorie). +.PP +Usage: +.CS + + +if { [teq $x $y] } { puts "x == y" } +if { [tne $x $y] } { puts "x != y" } +if { [tge $x $y] } { puts "x >= y" } +if { [tgt $x $y] } { puts "x > y" } +if { [tlt $x $y] } { puts "x < y" } +if { [tle $x $y] } { puts "x <= y" } + +set fx [tfloor $x] +set fc [tceil $x] +set rounded [tround $x] +set roundn [troundn $x $nodigits] + +.CE +.SH "TEST CASES" +The problems that can occur with floating-point numbers are illustrated +by the test cases in the file "fuzzy.test": +.IP \(bu +Several test case use the ordinary comparisons, and they +fail invariably to produce understandable results +.IP \(bu +One test case uses [expr] without braces ({ and }). It too +fails. +.PP +The conclusion from this is that any expression should be surrounded by +braces, because otherwise very awkward things can happen if you need +accuracy. Furthermore, accuracy and understandable results are +enhanced by using these "tolerant" or fuzzy comparisons. +.PP +Note that besides the Tcl-only package, there is also a C-based version. +.SH REFERENCES +Original implementation in Fortran by dr. H.D. Knoble (Penn State +University). +.PP +P. E. Hagerty, "More on Fuzzy Floor and Ceiling," +APL QUOTE QUAD 8(4):20-24, June 1978. Note that TFLOOR=FL5 took five +years of refereed evolution (publication). +.PP +L. M. Breed, "Definitions for Fuzzy Floor and Ceiling", +APL QUOTE QUAD 8(3):16-23, March 1978. +.PP +D. Knuth, Art of Computer Programming, +Vol. 1, Problem 1.2.4-5. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: fuzzy\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +floating-point, math, rounding +.SH CATEGORY +Mathematics ADDED embedded/man/files/modules/math/interpolate.n Index: embedded/man/files/modules/math/interpolate.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/interpolate.n @@ -0,0 +1,522 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/interpolate.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" Copyright (c) 2004 Kevn B. Kenny <kennykb@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::interpolate" n 1.0.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::interpolate \- Interpolation routines +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBstruct \fR +.sp +package require \fBmath::interpolate ?1.0.2?\fR +.sp +\fB::math::interpolate::defineTable\fR \fIname\fR \fIcolnames\fR \fIvalues\fR +.sp +\fB::math::interpolate::interp-1d-table\fR \fIname\fR \fIxval\fR +.sp +\fB::math::interpolate::interp-table\fR \fIname\fR \fIxval\fR \fIyval\fR +.sp +\fB::math::interpolate::interp-linear\fR \fIxyvalues\fR \fIxval\fR +.sp +\fB::math::interpolate::interp-lagrange\fR \fIxyvalues\fR \fIxval\fR +.sp +\fB::math::interpolate::prepare-cubic-splines\fR \fIxcoord\fR \fIycoord\fR +.sp +\fB::math::interpolate::interp-cubic-splines\fR \fIcoeffs\fR \fIx\fR +.sp +\fB::math::interpolate::interp-spatial\fR \fIxyvalues\fR \fIcoord\fR +.sp +\fB::math::interpolate::interp-spatial-params\fR \fImax_search\fR \fIpower\fR +.sp +\fB::math::interpolate::neville\fR \fIxlist\fR \fIylist\fR \fIx\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package implements several interpolation algorithms: +.IP \(bu +Interpolation into a table (one or two independent variables), this is useful +for example, if the data are static, like with tables of statistical functions. +.IP \(bu +Linear interpolation into a given set of data (organised as (x,y) pairs). +.IP \(bu +Lagrange interpolation. This is mainly of theoretical interest, because there is +no guarantee about error bounds. One possible use: if you need a line or +a parabola through given points (it will calculate the values, but not return +the coefficients). +.sp +A variation is Neville's method which has better behaviour and error +bounds. +.IP \(bu +Spatial interpolation using a straightforward distance-weight method. This procedure +allows any number of spatial dimensions and any number of dependent variables. +.IP \(bu +Interpolation in one dimension using cubic splines. +.PP +.PP +This document describes the procedures and explains their usage. +.SH PROCEDURES +The interpolation package defines the following public procedures: +.TP +\fB::math::interpolate::defineTable\fR \fIname\fR \fIcolnames\fR \fIvalues\fR +Define a table with one or two independent variables (the distinction is implicit in +the data). The procedure returns the name of the table - this name is used whenever you +want to interpolate the values. \fINote:\fR this procedure is a convenient wrapper for the +struct::matrix procedure. Therefore you can access the data at any location in your program. +.RS +.TP +string \fIname\fR (in) +Name of the table to be created +.TP +list \fIcolnames\fR (in) +List of column names +.TP +list \fIvalues\fR (in) +List of values (the number of elements should be a +multiple of the number of columns. See \fBEXAMPLES\fR for more information on the +interpretation of the data. +.sp +The values must be sorted with respect to the independent variable(s). +.RE +.sp +.TP +\fB::math::interpolate::interp-1d-table\fR \fIname\fR \fIxval\fR +Interpolate into the one-dimensional table "name" and return a list of values, one for +each dependent column. +.RS +.TP +string \fIname\fR (in) +Name of an existing table +.TP +float \fIxval\fR (in) +Value of the independent \fIrow\fR variable +.RE +.sp +.TP +\fB::math::interpolate::interp-table\fR \fIname\fR \fIxval\fR \fIyval\fR +Interpolate into the two-dimensional table "name" and return the interpolated value. +.RS +.TP +string \fIname\fR (in) +Name of an existing table +.TP +float \fIxval\fR (in) +Value of the independent \fIrow\fR variable +.TP +float \fIyval\fR (in) +Value of the independent \fIcolumn\fR variable +.RE +.sp +.TP +\fB::math::interpolate::interp-linear\fR \fIxyvalues\fR \fIxval\fR +Interpolate linearly into the list of x,y pairs and return the interpolated value. +.RS +.TP +list \fIxyvalues\fR (in) +List of pairs of (x,y) values, sorted to increasing x. +They are used as the breakpoints of a piecewise linear function. +.TP +float \fIxval\fR (in) +Value of the independent variable for which the value of y +must be computed. +.RE +.sp +.TP +\fB::math::interpolate::interp-lagrange\fR \fIxyvalues\fR \fIxval\fR +Use the list of x,y pairs to construct the unique polynomial of lowest degree +that passes through all points and return the interpolated value. +.RS +.TP +list \fIxyvalues\fR (in) +List of pairs of (x,y) values +.TP +float \fIxval\fR (in) +Value of the independent variable for which the value of y +must be computed. +.RE +.sp +.TP +\fB::math::interpolate::prepare-cubic-splines\fR \fIxcoord\fR \fIycoord\fR +Returns a list of coefficients for the second routine +\fIinterp-cubic-splines\fR to actually interpolate. +.RS +.TP +list \fIxcoord\fR +List of x-coordinates for the value of the +function to be interpolated is known. The coordinates must be strictly +ascending. At least three points are required. +.TP +list \fIycoord\fR +List of y-coordinates (the values of the +function at the given x-coordinates). +.RE +.sp +.TP +\fB::math::interpolate::interp-cubic-splines\fR \fIcoeffs\fR \fIx\fR +Returns the interpolated value at coordinate x. The coefficients are +computed by the procedure \fIprepare-cubic-splines\fR. +.RS +.TP +list \fIcoeffs\fR +List of coefficients as returned by +prepare-cubic-splines +.TP +float \fIx\fR +x-coordinate at which to estimate the function. Must +be between the first and last x-coordinate for which values were given. +.RE +.sp +.TP +\fB::math::interpolate::interp-spatial\fR \fIxyvalues\fR \fIcoord\fR +Use a straightforward interpolation method with weights as function of the +inverse distance to interpolate in 2D and N-dimensional space +.sp +The list xyvalues is a list of lists: +.CS + + + { {x1 y1 z1 {v11 v12 v13 v14}} + {x2 y2 z2 {v21 v22 v23 v24}} + ... + } + +.CE +.IP +The last element of each inner list is either a single number or a list in itself. +In the latter case the return value is a list with the same number of elements. +.sp +The method is influenced by the search radius and the power of the inverse distance +.RS +.TP +list \fIxyvalues\fR (in) +List of lists, each sublist being a list of coordinates and +of dependent values. +.TP +list \fIcoord\fR (in) +List of coordinates for which the values must be calculated +.RE +.sp +.TP +\fB::math::interpolate::interp-spatial-params\fR \fImax_search\fR \fIpower\fR +Set the parameters for spatial interpolation +.RS +.TP +float \fImax_search\fR (in) +Search radius (data points further than this are ignored) +.TP +integer \fIpower\fR (in) +Power for the distance (either 1 or 2; defaults to 2) +.RE +.TP +\fB::math::interpolate::neville\fR \fIxlist\fR \fIylist\fR \fIx\fR +Interpolates between the tabulated values of a function +whose abscissae are \fIxlist\fR +and whose ordinates are \fIylist\fR to produce an estimate for the value +of the function at \fIx\fR. The result is a two-element list; the first +element is the function's estimated value, and the second is an estimate +of the absolute error of the result. Neville's algorithm for polynomial +interpolation is used. Note that a large table of values will use an +interpolating polynomial of high degree, which is likely to result in +numerical instabilities; one is better off using only a few tabulated +values near the desired abscissa. +.PP +.SH EXAMPLES +\fITODO\fR +Example of using the cubic splines: +.PP +Suppose the following values are given: +.CS + + + x y + 0.1 1.0 + 0.3 2.1 + 0.4 2.2 + 0.8 4.11 + 1.0 4.12 + +.CE +Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use: +.CS + + + set coeffs [::math::interpolate::prepare-cubic-splines {0.1 0.3 0.4 0.8 1.0} {1.0 2.1 2.2 4.11 4.12}] + foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} { + puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]" + } + +.CE +to get the following output: +.CS + + +0.1: 1.0 +0.2: 1.68044117647 +0.3: 2.1 +0.4: 2.2 +0.5: 3.11221507353 +0.6: 4.25242647059 +0.7: 5.41804227941 +0.8: 4.11 +0.9: 3.95675857843 +1.0: 4.12 + +.CE +As you can see, the values at the abscissae are reproduced perfectly. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: interpolate\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +interpolation, math, spatial interpolation +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +Copyright (c) 2004 Kevn B. Kenny <kennykb@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/linalg.n Index: embedded/man/files/modules/math/linalg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/linalg.n @@ -0,0 +1,1454 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/linalg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2008 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" Copyright (c) 2004 Ed Hume <http://www.hume.com/contact.us.htm> +'\" Copyright (c) 2008 Michael Buadin <relaxkmike@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::linearalgebra" n 1.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::linearalgebra \- Linear Algebra +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBmath::linearalgebra ?1.1?\fR +.sp +\fB::math::linearalgebra::mkVector\fR \fIndim\fR \fIvalue\fR +.sp +\fB::math::linearalgebra::mkUnitVector\fR \fIndim\fR \fIndir\fR +.sp +\fB::math::linearalgebra::mkMatrix\fR \fInrows\fR \fIncols\fR \fIvalue\fR +.sp +\fB::math::linearalgebra::getrow\fR \fImatrix\fR \fIrow\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::setrow\fR \fImatrix\fR \fIrow\fR \fInewvalues\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::getcol\fR \fImatrix\fR \fIcol\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::setcol\fR \fImatrix\fR \fIcol\fR \fInewvalues\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::getelem\fR \fImatrix\fR \fIrow\fR \fIcol\fR +.sp +\fB::math::linearalgebra::setelem\fR \fImatrix\fR \fIrow\fR ?col? \fInewvalue\fR +.sp +\fB::math::linearalgebra::swaprows\fR \fImatrix\fR \fIirow1\fR \fIirow2\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::swapcols\fR \fImatrix\fR \fIicol1\fR \fIicol2\fR ?imin? ?imax? +.sp +\fB::math::linearalgebra::show\fR \fIobj\fR ?format? ?rowsep? ?colsep? +.sp +\fB::math::linearalgebra::dim\fR \fIobj\fR +.sp +\fB::math::linearalgebra::shape\fR \fIobj\fR +.sp +\fB::math::linearalgebra::conforming\fR \fItype\fR \fIobj1\fR \fIobj2\fR +.sp +\fB::math::linearalgebra::symmetric\fR \fImatrix\fR ?eps? +.sp +\fB::math::linearalgebra::norm\fR \fIvector\fR \fItype\fR +.sp +\fB::math::linearalgebra::norm_one\fR \fIvector\fR +.sp +\fB::math::linearalgebra::norm_two\fR \fIvector\fR +.sp +\fB::math::linearalgebra::norm_max\fR \fIvector\fR ?index? +.sp +\fB::math::linearalgebra::normMatrix\fR \fImatrix\fR \fItype\fR +.sp +\fB::math::linearalgebra::dotproduct\fR \fIvect1\fR \fIvect2\fR +.sp +\fB::math::linearalgebra::unitLengthVector\fR \fIvector\fR +.sp +\fB::math::linearalgebra::normalizeStat\fR \fImv\fR +.sp +\fB::math::linearalgebra::axpy\fR \fIscale\fR \fImv1\fR \fImv2\fR +.sp +\fB::math::linearalgebra::add\fR \fImv1\fR \fImv2\fR +.sp +\fB::math::linearalgebra::sub\fR \fImv1\fR \fImv2\fR +.sp +\fB::math::linearalgebra::scale\fR \fIscale\fR \fImv\fR +.sp +\fB::math::linearalgebra::rotate\fR \fIc\fR \fIs\fR \fIvect1\fR \fIvect2\fR +.sp +\fB::math::linearalgebra::transpose\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::matmul\fR \fImv1\fR \fImv2\fR +.sp +\fB::math::linearalgebra::angle\fR \fIvect1\fR \fIvect2\fR +.sp +\fB::math::linearalgebra::crossproduct\fR \fIvect1\fR \fIvect2\fR +.sp +\fB::math::linearalgebra::matmul\fR \fImv1\fR \fImv2\fR +.sp +\fB::math::linearalgebra::mkIdentity\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkDiagonal\fR \fIdiag\fR +.sp +\fB::math::linearalgebra::mkRandom\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkTriangular\fR \fIsize\fR ?uplo? ?value? +.sp +\fB::math::linearalgebra::mkHilbert\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkDingdong\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkOnes\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkMoler\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkFrank\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkBorder\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkWilkinsonW+\fR \fIsize\fR +.sp +\fB::math::linearalgebra::mkWilkinsonW-\fR \fIsize\fR +.sp +\fB::math::linearalgebra::solveGauss\fR \fImatrix\fR \fIbvect\fR +.sp +\fB::math::linearalgebra::solvePGauss\fR \fImatrix\fR \fIbvect\fR +.sp +\fB::math::linearalgebra::solveTriangular\fR \fImatrix\fR \fIbvect\fR ?uplo? +.sp +\fB::math::linearalgebra::solveGaussBand\fR \fImatrix\fR \fIbvect\fR +.sp +\fB::math::linearalgebra::solveTriangularBand\fR \fImatrix\fR \fIbvect\fR +.sp +\fB::math::linearalgebra::determineSVD\fR \fIA\fR \fIeps\fR +.sp +\fB::math::linearalgebra::eigenvectorsSVD\fR \fIA\fR \fIeps\fR +.sp +\fB::math::linearalgebra::leastSquaresSVD\fR \fIA\fR \fIy\fR \fIqmin\fR \fIeps\fR +.sp +\fB::math::linearalgebra::choleski\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::orthonormalizeColumns\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::orthonormalizeRows\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::dger\fR \fImatrix\fR \fIalpha\fR \fIx\fR \fIy\fR ?scope? +.sp +\fB::math::linearalgebra::dgetrf\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::det\fR \fImatrix\fR +.sp +\fB::math::linearalgebra::largesteigen\fR \fImatrix\fR \fItolerance\fR \fImaxiter\fR +.sp +\fB::math::linearalgebra::to_LA\fR \fImv\fR +.sp +\fB::math::linearalgebra::from_LA\fR \fImv\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package offers both low-level procedures and high-level algorithms +to deal with linear algebra problems: +.IP \(bu +robust solution of linear equations or least squares problems +.IP \(bu +determining eigenvectors and eigenvalues of symmetric matrices +.IP \(bu +various decompositions of general matrices or matrices of a specific +form +.IP \(bu +(limited) support for matrices in band storage, a common type of sparse +matrices +.PP +It arose as a re-implementation of Hume's LA package and the desire to +offer low-level procedures as found in the well-known BLAS library. +Matrices are implemented as lists of lists rather linear lists with +reserved elements, as in the original LA package, as it was found that +such an implementation is actually faster. +.PP +It is advisable, however, to use the procedures that are offered, such +as \fIsetrow\fR and \fIgetrow\fR, rather than rely on this +representation explicitly: that way it is to switch to a possibly even +faster compiled implementation that supports the same API. +.PP +\fINote:\fR When using this package in combination with Tk, there may +be a naming conflict, as both this package and Tk define a command +\fIscale\fR. See the \fBNAMING CONFLICT\fR section below. +.SH PROCEDURES +The package defines the following public procedures (several exist as +specialised procedures, see below): +.PP +\fIConstructing matrices and vectors\fR +.TP +\fB::math::linearalgebra::mkVector\fR \fIndim\fR \fIvalue\fR +Create a vector with ndim elements, each with the value \fIvalue\fR. +.RS +.TP +integer \fIndim\fR +Dimension of the vector (number of components) +.TP +double \fIvalue\fR +Uniform value to be used (default: 0.0) +.RE +.sp +.TP +\fB::math::linearalgebra::mkUnitVector\fR \fIndim\fR \fIndir\fR +Create a unit vector in \fIndim\fR-dimensional space, along the +\fIndir\fR-th direction. +.RS +.TP +integer \fIndim\fR +Dimension of the vector (number of components) +.TP +integer \fIndir\fR +Direction (0, ..., ndim-1) +.RE +.sp +.TP +\fB::math::linearalgebra::mkMatrix\fR \fInrows\fR \fIncols\fR \fIvalue\fR +Create a matrix with \fInrows\fR rows and \fIncols\fR columns. All +elements have the value \fIvalue\fR. +.RS +.TP +integer \fInrows\fR +Number of rows +.TP +integer \fIncols\fR +Number of columns +.TP +double \fIvalue\fR +Uniform value to be used (default: 0.0) +.RE +.sp +.TP +\fB::math::linearalgebra::getrow\fR \fImatrix\fR \fIrow\fR ?imin? ?imax? +Returns a single row of a matrix as a list +.RS +.TP +list \fImatrix\fR +Matrix in question +.TP +integer \fIrow\fR +Index of the row to return +.TP +integer \fIimin\fR +Minimum index of the column (default: 0) +.TP +integer \fIimax\fR +Maximum index of the column (default: ncols-1) +.RE +.sp +.TP +\fB::math::linearalgebra::setrow\fR \fImatrix\fR \fIrow\fR \fInewvalues\fR ?imin? ?imax? +Set a single row of a matrix to new values (this list must have the same +number of elements as the number of \fIcolumns\fR in the matrix) +.RS +.TP +list \fImatrix\fR +\fIname\fR of the matrix in question +.TP +integer \fIrow\fR +Index of the row to update +.TP +list \fInewvalues\fR +List of new values for the row +.TP +integer \fIimin\fR +Minimum index of the column (default: 0) +.TP +integer \fIimax\fR +Maximum index of the column (default: ncols-1) +.RE +.sp +.TP +\fB::math::linearalgebra::getcol\fR \fImatrix\fR \fIcol\fR ?imin? ?imax? +Returns a single column of a matrix as a list +.RS +.TP +list \fImatrix\fR +Matrix in question +.TP +integer \fIcol\fR +Index of the column to return +.TP +integer \fIimin\fR +Minimum index of the row (default: 0) +.TP +integer \fIimax\fR +Maximum index of the row (default: nrows-1) +.RE +.sp +.TP +\fB::math::linearalgebra::setcol\fR \fImatrix\fR \fIcol\fR \fInewvalues\fR ?imin? ?imax? +Set a single column of a matrix to new values (this list must have +the same number of elements as the number of \fIrows\fR in the matrix) +.RS +.TP +list \fImatrix\fR +\fIname\fR of the matrix in question +.TP +integer \fIcol\fR +Index of the column to update +.TP +list \fInewvalues\fR +List of new values for the column +.TP +integer \fIimin\fR +Minimum index of the row (default: 0) +.TP +integer \fIimax\fR +Maximum index of the row (default: nrows-1) +.RE +.sp +.TP +\fB::math::linearalgebra::getelem\fR \fImatrix\fR \fIrow\fR \fIcol\fR +Returns a single element of a matrix/vector +.RS +.TP +list \fImatrix\fR +Matrix or vector in question +.TP +integer \fIrow\fR +Row of the element +.TP +integer \fIcol\fR +Column of the element (not present for vectors) +.RE +.sp +.TP +\fB::math::linearalgebra::setelem\fR \fImatrix\fR \fIrow\fR ?col? \fInewvalue\fR +Set a single element of a matrix (or vector) to a new value +.RS +.TP +list \fImatrix\fR +\fIname\fR of the matrix in question +.TP +integer \fIrow\fR +Row of the element +.TP +integer \fIcol\fR +Column of the element (not present for vectors) +.RE +.sp +.TP +\fB::math::linearalgebra::swaprows\fR \fImatrix\fR \fIirow1\fR \fIirow2\fR ?imin? ?imax? +Swap two rows in a matrix completely or only a selected part +.RS +.TP +list \fImatrix\fR +\fIname\fR of the matrix in question +.TP +integer \fIirow1\fR +Index of first row +.TP +integer \fIirow2\fR +Index of second row +.TP +integer \fIimin\fR +Minimum column index (default: 0) +.TP +integer \fIimin\fR +Maximum column index (default: ncols-1) +.RE +.sp +.TP +\fB::math::linearalgebra::swapcols\fR \fImatrix\fR \fIicol1\fR \fIicol2\fR ?imin? ?imax? +Swap two columns in a matrix completely or only a selected part +.RS +.TP +list \fImatrix\fR +\fIname\fR of the matrix in question +.TP +integer \fIirow1\fR +Index of first column +.TP +integer \fIirow2\fR +Index of second column +.TP +integer \fIimin\fR +Minimum row index (default: 0) +.TP +integer \fIimin\fR +Maximum row index (default: nrows-1) +.RE +.PP +.PP +\fIQuerying matrices and vectors\fR +.TP +\fB::math::linearalgebra::show\fR \fIobj\fR ?format? ?rowsep? ?colsep? +Return a string representing the vector or matrix, for easy printing. +(There is currently no way to print fixed sets of columns) +.RS +.TP +list \fIobj\fR +Matrix or vector in question +.TP +string \fIformat\fR +Format for printing the numbers (default: %6.4f) +.TP +string \fIrowsep\fR +String to use for separating rows (default: newline) +.TP +string \fIcolsep\fR +String to use for separating columns (default: space) +.RE +.sp +.TP +\fB::math::linearalgebra::dim\fR \fIobj\fR +Returns the number of dimensions for the object (either 0 for a scalar, +1 for a vector and 2 for a matrix) +.RS +.TP +any \fIobj\fR +Scalar, vector, or matrix +.RE +.sp +.TP +\fB::math::linearalgebra::shape\fR \fIobj\fR +Returns the number of elements in each dimension for the object (either +an empty list for a scalar, a single number for a vector and a list of +the number of rows and columns for a matrix) +.RS +.TP +any \fIobj\fR +Scalar, vector, or matrix +.RE +.sp +.TP +\fB::math::linearalgebra::conforming\fR \fItype\fR \fIobj1\fR \fIobj2\fR +Checks if two objects (vector or matrix) have conforming shapes, that is +if they can be applied in an operation like addition or matrix +multiplication. +.RS +.TP +string \fItype\fR +Type of check: +.RS +.IP \(bu +"shape" - the two objects have the same shape (for all element-wise +operations) +.IP \(bu +"rows" - the two objects have the same number of rows (for use as A and +b in a system of linear equations \fIAx = b\fR +.IP \(bu +"matmul" - the first object has the same number of columns as the number +of rows of the second object. Useful for matrix-matrix or matrix-vector +multiplication. +.RE +.TP +list \fIobj1\fR +First vector or matrix (left operand) +.TP +list \fIobj2\fR +Second vector or matrix (right operand) +.RE +.sp +.TP +\fB::math::linearalgebra::symmetric\fR \fImatrix\fR ?eps? +Checks if the given (square) matrix is symmetric. The argument eps +is the tolerance. +.RS +.TP +list \fImatrix\fR +Matrix to be inspected +.TP +float \fIeps\fR +Tolerance for determining approximate equality +(defaults to 1.0e-8) +.RE +.PP +.PP +\fIBasic operations\fR +.TP +\fB::math::linearalgebra::norm\fR \fIvector\fR \fItype\fR +Returns the norm of the given vector. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm. +.RS +.TP +list \fIvector\fR +Vector, list of coefficients +.TP +string \fItype\fR +Type of norm (default: 2, the Euclidean norm) +.RE +.TP +\fB::math::linearalgebra::norm_one\fR \fIvector\fR +Returns the L1 norm of the given vector, the sum of absolute values +.RS +.TP +list \fIvector\fR +Vector, list of coefficients +.RE +.TP +\fB::math::linearalgebra::norm_two\fR \fIvector\fR +Returns the L2 norm of the given vector, the ordinary Euclidean norm +.RS +.TP +list \fIvector\fR +Vector, list of coefficients +.RE +.TP +\fB::math::linearalgebra::norm_max\fR \fIvector\fR ?index? +Returns the Linf norm of the given vector, the maximum absolute +coefficient +.RS +.TP +list \fIvector\fR +Vector, list of coefficients +.TP +integer \fIindex\fR +(optional) if non zero, returns a list made of the maximum +value and the index where that maximum was found. +if zero, returns the maximum value. +.RE +.sp +.TP +\fB::math::linearalgebra::normMatrix\fR \fImatrix\fR \fItype\fR +Returns the norm of the given matrix. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm. +.RS +.TP +list \fImatrix\fR +Matrix, list of row vectors +.TP +string \fItype\fR +Type of norm (default: 2, the Euclidean norm) +.RE +.sp +.TP +\fB::math::linearalgebra::dotproduct\fR \fIvect1\fR \fIvect2\fR +Determine the inproduct or dot product of two vectors. These must have +the same shape (number of dimensions) +.RS +.TP +list \fIvect1\fR +First vector, list of coefficients +.TP +list \fIvect2\fR +Second vector, list of coefficients +.RE +.sp +.TP +\fB::math::linearalgebra::unitLengthVector\fR \fIvector\fR +Return a vector in the same direction with length 1. +.RS +.TP +list \fIvector\fR +Vector to be normalized +.RE +.sp +.TP +\fB::math::linearalgebra::normalizeStat\fR \fImv\fR +Normalize the matrix or vector in a statistical sense: the mean of the +elements of the columns of the result is zero and the standard deviation +is 1. +.RS +.TP +list \fImv\fR +Vector or matrix to be normalized in the above sense +.RE +.sp +.TP +\fB::math::linearalgebra::axpy\fR \fIscale\fR \fImv1\fR \fImv2\fR +Return a vector or matrix that results from a "daxpy" operation, that +is: compute a*x+y (a a scalar and x and y both vectors or matrices of +the same shape) and return the result. +.sp +Specialised variants are: axpy_vect and axpy_mat (slightly faster, +but no check on the arguments) +.RS +.TP +double \fIscale\fR +The scale factor for the first vector/matrix (a) +.TP +list \fImv1\fR +First vector or matrix (x) +.TP +list \fImv2\fR +Second vector or matrix (y) +.RE +.sp +.TP +\fB::math::linearalgebra::add\fR \fImv1\fR \fImv2\fR +Return a vector or matrix that is the sum of the two arguments (x+y) +.sp +Specialised variants are: add_vect and add_mat (slightly faster, +but no check on the arguments) +.RS +.TP +list \fImv1\fR +First vector or matrix (x) +.TP +list \fImv2\fR +Second vector or matrix (y) +.RE +.sp +.TP +\fB::math::linearalgebra::sub\fR \fImv1\fR \fImv2\fR +Return a vector or matrix that is the difference of the two arguments +(x-y) +.sp +Specialised variants are: sub_vect and sub_mat (slightly faster, +but no check on the arguments) +.RS +.TP +list \fImv1\fR +First vector or matrix (x) +.TP +list \fImv2\fR +Second vector or matrix (y) +.RE +.sp +.TP +\fB::math::linearalgebra::scale\fR \fIscale\fR \fImv\fR +Scale a vector or matrix and return the result, that is: compute a*x. +.sp +Specialised variants are: scale_vect and scale_mat (slightly faster, +but no check on the arguments) +.RS +.TP +double \fIscale\fR +The scale factor for the vector/matrix (a) +.TP +list \fImv\fR +Vector or matrix (x) +.RE +.sp +.TP +\fB::math::linearalgebra::rotate\fR \fIc\fR \fIs\fR \fIvect1\fR \fIvect2\fR +Apply a planar rotation to two vectors and return the result as a list +of two vectors: c*x-s*y and s*x+c*y. In algorithms you can often easily +determine the cosine and sine of the angle, so it is more efficient to +pass that information directly. +.RS +.TP +double \fIc\fR +The cosine of the angle +.TP +double \fIs\fR +The sine of the angle +.TP +list \fIvect1\fR +First vector (x) +.TP +list \fIvect2\fR +Seocnd vector (x) +.RE +.sp +.TP +\fB::math::linearalgebra::transpose\fR \fImatrix\fR +Transpose a matrix +.RS +.TP +list \fImatrix\fR +Matrix to be transposed +.RE +.sp +.TP +\fB::math::linearalgebra::matmul\fR \fImv1\fR \fImv2\fR +Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector. +.RS +.TP +list \fImv1\fR +First vector/matrix (x) +.TP +list \fImv2\fR +Second vector/matrix (y) +.RE +.sp +.TP +\fB::math::linearalgebra::angle\fR \fIvect1\fR \fIvect2\fR +Compute the angle between two vectors (in radians) +.RS +.TP +list \fIvect1\fR +First vector +.TP +list \fIvect2\fR +Second vector +.RE +.sp +.TP +\fB::math::linearalgebra::crossproduct\fR \fIvect1\fR \fIvect2\fR +Compute the cross product of two (three-dimensional) vectors +.RS +.TP +list \fIvect1\fR +First vector +.TP +list \fIvect2\fR +Second vector +.RE +.sp +.TP +\fB::math::linearalgebra::matmul\fR \fImv1\fR \fImv2\fR +Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector. +.RS +.TP +list \fImv1\fR +First vector/matrix (x) +.TP +list \fImv2\fR +Second vector/matrix (y) +.RE +.PP +.PP +\fICommon matrices and test matrices\fR +.TP +\fB::math::linearalgebra::mkIdentity\fR \fIsize\fR +Create an identity matrix of dimension \fIsize\fR. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkDiagonal\fR \fIdiag\fR +Create a diagonal matrix whose diagonal elements are the elements of the +vector \fIdiag\fR. +.RS +.TP +list \fIdiag\fR +Vector whose elements are used for the diagonal +.RE +.sp +.TP +\fB::math::linearalgebra::mkRandom\fR \fIsize\fR +Create a square matrix whose elements are uniformly distributed random +numbers between 0 and 1 of dimension \fIsize\fR. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkTriangular\fR \fIsize\fR ?uplo? ?value? +Create a triangular matrix with non-zero elements in the upper or lower +part, depending on argument \fIuplo\fR. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.TP +string \fIuplo\fR +Fill the upper (U) or lower part (L) +.TP +double \fIvalue\fR +Value to fill the matrix with +.RE +.sp +.TP +\fB::math::linearalgebra::mkHilbert\fR \fIsize\fR +Create a Hilbert matrix of dimension \fIsize\fR. +Hilbert matrices are very ill-conditioned with respect to +eigenvalue/eigenvector problems. Therefore they +are good candidates for testing the accuracy +of algorithms and implementations. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkDingdong\fR \fIsize\fR +Create a "dingdong" matrix of dimension \fIsize\fR. +Dingdong matrices are imprecisely represented, +but have the property of being very stable in +such algorithms as Gauss elimination. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkOnes\fR \fIsize\fR +Create a square matrix of dimension \fIsize\fR whose entries are all 1. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkMoler\fR \fIsize\fR +Create a Moler matrix of size \fIsize\fR. (Moler matrices have +a very simple Choleski decomposition. It has one small eigenvalue +and it can easily upset elimination methods for systems of linear +equations.) +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkFrank\fR \fIsize\fR +Create a Frank matrix of size \fIsize\fR. (Frank matrices are +fairly well-behaved matrices) +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkBorder\fR \fIsize\fR +Create a bordered matrix of size \fIsize\fR. (Bordered matrices have +a very low rank and can upset certain specialised algorithms.) +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkWilkinsonW+\fR \fIsize\fR +Create a Wilkinson W+ of size \fIsize\fR. This kind of matrix +has pairs of eigenvalues that are very close together. Usually +the order (size) is odd. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.sp +.TP +\fB::math::linearalgebra::mkWilkinsonW-\fR \fIsize\fR +Create a Wilkinson W- of size \fIsize\fR. This kind of matrix +has pairs of eigenvalues with opposite signs, when the order (size) +is odd. +.RS +.TP +integer \fIsize\fR +Dimension of the matrix +.RE +.PP +.PP +\fICommon algorithms\fR +.TP +\fB::math::linearalgebra::solveGauss\fR \fImatrix\fR \fIbvect\fR +Solve a system of linear equations (Ax=b) using Gauss elimination. +Returns the solution (x) as a vector or matrix of the same shape as +bvect. +.RS +.TP +list \fImatrix\fR +Square matrix (matrix A) +.TP +list \fIbvect\fR +Vector or matrix whose columns are the individual +b-vectors +.RE +.TP +\fB::math::linearalgebra::solvePGauss\fR \fImatrix\fR \fIbvect\fR +Solve a system of linear equations (Ax=b) using Gauss elimination with +partial pivoting. Returns the solution (x) as a vector or matrix of the +same shape as bvect. +.RS +.TP +list \fImatrix\fR +Square matrix (matrix A) +.TP +list \fIbvect\fR +Vector or matrix whose columns are the individual +b-vectors +.RE +.sp +.TP +\fB::math::linearalgebra::solveTriangular\fR \fImatrix\fR \fIbvect\fR ?uplo? +Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular. +.RS +.TP +list \fImatrix\fR +Lower or upper-triangular matrix (matrix A) +.TP +list \fIbvect\fR +Vector or matrix whose columns are the individual +b-vectors +.TP +string \fIuplo\fR +Indicates whether the matrix is lower-triangular +(L) or upper-triangular (U). Defaults to "U". +.RE +.TP +\fB::math::linearalgebra::solveGaussBand\fR \fImatrix\fR \fIbvect\fR +Solve a system of linear equations (Ax=b) using Gauss elimination, +where the matrix is stored as a band matrix (\fIcf.\fR \fBSTORAGE\fR). +Returns the solution (x) as a vector or matrix of the same shape as +bvect. +.RS +.TP +list \fImatrix\fR +Square matrix (matrix A; in band form) +.TP +list \fIbvect\fR +Vector or matrix whose columns are the individual +b-vectors +.RE +.sp +.TP +\fB::math::linearalgebra::solveTriangularBand\fR \fImatrix\fR \fIbvect\fR +Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular and stored in band form. +.RS +.TP +list \fImatrix\fR +Upper-triangular matrix (matrix A) +.TP +list \fIbvect\fR +Vector or matrix whose columns are the individual +b-vectors +.RE +.sp +.TP +\fB::math::linearalgebra::determineSVD\fR \fIA\fR \fIeps\fR +Determines the Singular Value Decomposition of a matrix: A = U S Vtrans. +Returns a list with the matrix U, the vector of singular values S and +the matrix V. +.RS +.TP +list \fIA\fR +Matrix to be decomposed +.TP +float \fIeps\fR +Tolerance (defaults to 2.3e-16) +.RE +.sp +.TP +\fB::math::linearalgebra::eigenvectorsSVD\fR \fIA\fR \fIeps\fR +Determines the eigenvectors and eigenvalues of a real +\fIsymmetric\fR matrix, using SVD. Returns a list with the matrix of +normalized eigenvectors and their eigenvalues. +.RS +.TP +list \fIA\fR +Matrix whose eigenvalues must be determined +.TP +float \fIeps\fR +Tolerance (defaults to 2.3e-16) +.RE +.sp +.TP +\fB::math::linearalgebra::leastSquaresSVD\fR \fIA\fR \fIy\fR \fIqmin\fR \fIeps\fR +Determines the solution to a least-sqaures problem Ax ~ y via singular +value decomposition. The result is the vector x. +.sp +Note that if you add a column of 1s to the matrix, then this column will +represent a constant like in: y = a*x1 + b*x2 + c. To force the +intercept to be zero, simply leave it out. +.RS +.TP +list \fIA\fR +Matrix of independent variables +.TP +list \fIy\fR +List of observed values +.TP +float \fIqmin\fR +Minimum singular value to be considered (defaults to 0.0) +.TP +float \fIeps\fR +Tolerance (defaults to 2.3e-16) +.RE +.sp +.TP +\fB::math::linearalgebra::choleski\fR \fImatrix\fR +Determine the Choleski decomposition of a symmetric positive +semidefinite matrix (this condition is not checked!). The result +is the lower-triangular matrix L such that L Lt = matrix. +.RS +.TP +list \fImatrix\fR +Matrix to be decomposed +.RE +.sp +.TP +\fB::math::linearalgebra::orthonormalizeColumns\fR \fImatrix\fR +Use the modified Gram-Schmidt method to orthogonalize and normalize +the \fIcolumns\fR of the given matrix and return the result. +.RS +.TP +list \fImatrix\fR +Matrix whose columns must be orthonormalized +.RE +.sp +.TP +\fB::math::linearalgebra::orthonormalizeRows\fR \fImatrix\fR +Use the modified Gram-Schmidt method to orthogonalize and normalize +the \fIrows\fR of the given matrix and return the result. +.RS +.TP +list \fImatrix\fR +Matrix whose rows must be orthonormalized +.RE +.sp +.TP +\fB::math::linearalgebra::dger\fR \fImatrix\fR \fIalpha\fR \fIx\fR \fIy\fR ?scope? +Perform the rank 1 operation A + alpha*x*y' inline (that is: the matrix A is adjusted). +For convenience the new matrix is also returned as the result. +.RS +.TP +list \fImatrix\fR +Matrix whose rows must be adjusted +.TP +double \fIalpha\fR +Scale factor +.TP +list \fIx\fR +A column vector +.TP +list \fIy\fR +A column vector +.TP +list \fIscope\fR +If not provided, the operation is performed on all rows/columns of A +if provided, it is expected to be the list {imin imax jmin jmax} +where: +.RS +.IP \(bu +\fIimin\fR Minimum row index +.IP \(bu +\fIimax\fR Maximum row index +.IP \(bu +\fIjmin\fR Minimum column index +.IP \(bu +\fIjmax\fR Maximum column index +.RE +.RE +.sp +.TP +\fB::math::linearalgebra::dgetrf\fR \fImatrix\fR +Computes an LU factorization of a general matrix, using partial, +pivoting with row interchanges. Returns the permutation vector. +.sp +The factorization has the form +.CS + + + P * A = L * U + +.CE +.IP +where P is a permutation matrix, L is lower triangular with unit +diagonal elements, and U is upper triangular. +Returns the permutation vector, as a list of length n-1. +The last entry of the permutation is not stored, since it is +implicitely known, with value n (the last row is not swapped +with any other row). +At index #i of the permutation is stored the index of the row #j +which is swapped with row #i at step #i. That means that each +index of the permutation gives the permutation at each step, not the +cumulated permutation matrix, which is the product of permutations. +.RS +.TP +list \fImatrix\fR +On entry, the matrix to be factored. +On exit, the factors L and U from the factorization +P*A = L*U; the unit diagonal elements of L are not stored. +.RE +.sp +.TP +\fB::math::linearalgebra::det\fR \fImatrix\fR +Returns the determinant of the given matrix, based on PA=LU +decomposition, i.e. Gauss partial pivotal. +.RS +.TP +list \fImatrix\fR +Square matrix (matrix A) +.TP +list \fIipiv\fR +The pivots (optionnal). +If the pivots are not provided, a PA=LU decomposition +is performed. +If the pivots are provided, we assume that it +contains the pivots and that the matrix A contains the +L and U factors, as provided by dgterf. +b-vectors +.RE +.sp +.TP +\fB::math::linearalgebra::largesteigen\fR \fImatrix\fR \fItolerance\fR \fImaxiter\fR +Returns a list made of the largest eigenvalue (in magnitude) +and associated eigenvector. +Uses iterative Power Method as provided as algorithm #7.3.3 of Golub & Van Loan. +This algorithm is used here for a dense matrix (but is usually +used for sparse matrices). +.RS +.TP +list \fImatrix\fR +Square matrix (matrix A) +.TP +double \fItolerance\fR +The relative tolerance of the eigenvalue (default:1.e-8). +.TP +integer \fImaxiter\fR +The maximum number of iterations (default:10). +.RE +.PP +.PP +\fICompability with the LA package\fR +Two procedures are provided for compatibility with Hume's LA package: +.TP +\fB::math::linearalgebra::to_LA\fR \fImv\fR +Transforms a vector or matrix into the format used by the original LA +package. +.RS +.TP +list \fImv\fR +Matrix or vector +.RE +.TP +\fB::math::linearalgebra::from_LA\fR \fImv\fR +Transforms a vector or matrix from the format used by the original LA +package into the format used by the present implementation. +.RS +.TP +list \fImv\fR +Matrix or vector as used by the LA package +.RE +.PP +.PP +.SH STORAGE +While most procedures assume that the matrices are given in full form, +the procedures \fIsolveGaussBand\fR and \fIsolveTriangularBand\fR +assume that the matrices are stored as \fIband matrices\fR. This +common type of "sparse" matrices is related to ordinary matrices as +follows: +.IP \(bu +"A" is a full-size matrix with N rows and M columns. +.IP \(bu +"B" is a band matrix, with m upper and lower diagonals and n rows. +.IP \(bu +"B" can be stored in an ordinary matrix of (2m+1) columns (one for +each off-diagonal and the main diagonal) and n rows. +.IP \(bu +Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element +k,j of "A" where k = M+i-1 and M is at least (!) n, the number of rows +in "B". +.IP \(bu +To set element (i,j) of matrix "B" use: +.CS + + + setelem B $j [expr {$N+$i-1}] $value + +.CE +.PP +(There is no convenience procedure for this yet) +.SH "REMARKS ON THE IMPLEMENTATION" +There is a difference between the original LA package by Hume and the +current implementation. Whereas the LA package uses a linear list, the +current package uses lists of lists to represent matrices. It turns out +that with this representation, the algorithms are faster and easier to +implement. +.PP +The LA package was used as a model and in fact the implementation of, +for instance, the SVD algorithm was taken from that package. The set of +procedures was expanded using ideas from the well-known BLAS library and +some algorithms were updated from the second edition of J.C. Nash's +book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that +inspired the LA package. +.PP +Two procedures are provided to make the transition between the two +implementations easier: \fIto_LA\fR and \fIfrom_LA\fR. They are +described above. +.SH TODO +Odds and ends: the following algorithms have not been implemented yet: +.IP \(bu +determineQR +.IP \(bu +certainlyPositive, diagonallyDominant +.PP +.SH "NAMING CONFLICT" +If you load this package in a Tk-enabled shell like wish, then the +command +.CS + +namespace import ::math::linearalgebra +.CE +results in an error +message about "scale". This is due to the fact that Tk defines all +its commands in the global namespace. The solution is to import +the linear algebra commands in a namespace that is not the global one: +.CS + + +package require math::linearalgebra +namespace eval compute { + namespace import ::math::linearalgebra::* + ... use the linear algebra version of scale ... +} + +.CE +To use Tk's scale command in that same namespace you can rename it: +.CS + + +namespace eval compute { + rename ::scale scaleTk + scaleTk .scale ... +} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: linearalgebra\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +least squares, linear algebra, linear equations, math, matrices, matrix, vectors +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004-2008 Arjen Markus <arjenmarkus@users.sourceforge.net> +Copyright (c) 2004 Ed Hume <http://www.hume.com/contact.us.htm> +Copyright (c) 2008 Michael Buadin <relaxkmike@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/machineparameters.n Index: embedded/man/files/modules/math/machineparameters.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/machineparameters.n @@ -0,0 +1,442 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/machineparameters.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Michael Baudin <michael.baudin@sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tclrep/machineparameters" n 1.0 tcllib "tclrep" +.BS +.SH NAME +tclrep/machineparameters \- Compute double precision machine parameters. +.SH SYNOPSIS +package require \fBsnit \fR +.sp +\fBmachineparameters\fR create \fIobjectname\fR ?\fIoptions\fR...? +.sp +\fIobjectname\fR \fBconfigure\fR ?\fIoptions\fR...? +.sp +\fIobjectname\fR \fBcget\fR \fIopt\fR +.sp +\fIobjectname\fR \fBdestroy\fR +.sp +\fIobjectname\fR \fBcompute\fR +.sp +\fIobjectname\fR \fBget\fR \fIkey\fR +.sp +\fIobjectname\fR \fBtostring\fR +.sp +\fIobjectname\fR \fBprint\fR +.sp +.BE +.SH DESCRIPTION +The \fImath::machineparameters\fR package +is the Tcl equivalent of the DLAMCH LAPACK function. +In floating point systems, a floating point number is represented +by +.CS + + +x = +/- d1 d2 ... dt basis^e + +.CE +where digits satisfy +.CS + + +0 <= di <= basis - 1, i = 1, t + +.CE +with the convention : +.IP \(bu +t is the size of the mantissa +.IP \(bu +basis is the basis (the "radix") +.PP +.PP +The \fBcompute\fR method computes all machine parameters. +Then, the \fBget\fR method can be used to get each +parameter. +The \fBprint\fR method prints a report on standard output. +.SH EXAMPLE +In the following example, one compute the parameters of a desktop +under Linux with the following Tcl 8.4.19 properties : +.CS + + +% parray tcl_platform +tcl_platform(byteOrder) = littleEndian +tcl_platform(machine) = i686 +tcl_platform(os) = Linux +tcl_platform(osVersion) = 2.6.24-19-generic +tcl_platform(platform) = unix +tcl_platform(tip,268) = 1 +tcl_platform(tip,280) = 1 +tcl_platform(user) = <username> +tcl_platform(wordSize) = 4 + +.CE +The following example creates a machineparameters object, +computes the properties and displays it. +.CS + + + set pp [machineparameters create %AUTO%] + $pp compute + $pp print + $pp destroy + +.CE +This prints out : +.CS + + + Machine parameters + Epsilon : 1.11022302463e-16 + Beta : 2 + Rounding : proper + Mantissa : 53 + Maximum exponent : 1024 + Minimum exponent : -1021 + Overflow threshold : 8.98846567431e+307 + Underflow threshold : 2.22507385851e-308 + +.CE +That compares well with the results produced by Lapack 3.1.1 : +.CS + + + Epsilon = 1.11022302462515654E-016 + Safe minimum = 2.22507385850720138E-308 + Base = 2.0000000000000000 + Precision = 2.22044604925031308E-016 + Number of digits in mantissa = 53.000000000000000 + Rounding mode = 1.00000000000000000 + Minimum exponent = -1021.0000000000000 + Underflow threshold = 2.22507385850720138E-308 + Largest exponent = 1024.0000000000000 + Overflow threshold = 1.79769313486231571E+308 + Reciprocal of safe minimum = 4.49423283715578977E+307 + +.CE +The following example creates a machineparameters object, +computes the properties and gets the epsilon for +the machine. +.CS + + + set pp [machineparameters create %AUTO%] + $pp compute + set eps [$pp get -epsilon] + $pp destroy + +.CE +.SH REFERENCES +.IP \(bu +"Algorithms to Reveal Properties of Floating-Point Arithmetic", Michael A. Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue 11 (November 1972), Pages: 949 - 951 +.IP \(bu +"More on Algorithms that Reveal Properties of Floating, Point Arithmetic Units", W. Morven Gentleman, University of Waterloo, Scott B. Marovich, Purdue University, Communications of the ACM, Volume 17 , Issue 5 (May 1974), Pages: 276 - 277 +.PP +.SH "CLASS API" +.TP +\fBmachineparameters\fR create \fIobjectname\fR ?\fIoptions\fR...? +The command creates a new machineparameters object and returns the fully +qualified name of the object command as its result. +.RS +.TP +\fB-verbose\fR \fIverbose\fR +Set this option to 1 to enable verbose logging. +This option is mainly for debug purposes. +The default value of \fIverbose\fR is 0. +.RE +.PP +.SH "OBJECT API" +.TP +\fIobjectname\fR \fBconfigure\fR ?\fIoptions\fR...? +The command configure the options of the object \fIobjectname\fR. The options +are the same as the static method \fBcreate\fR. +.TP +\fIobjectname\fR \fBcget\fR \fIopt\fR +Returns the value of the option which name is \fIopt\fR. The options +are the same as the method \fBcreate\fR and \fBconfigure\fR. +.TP +\fIobjectname\fR \fBdestroy\fR +Destroys the object \fIobjectname\fR. +.TP +\fIobjectname\fR \fBcompute\fR +Computes the machine parameters. +.TP +\fIobjectname\fR \fBget\fR \fIkey\fR +Returns the value corresponding with given key. +The following is the list of available keys. +.RS +.IP \(bu +-epsilon : smallest value so that 1+epsilon>1 is false +.IP \(bu +-rounding : The rounding mode used on the machine. +The rounding occurs when more than t digits would be required to +represent the number. +Two modes can be determined with the current system : +"chop" means than only t digits are kept, no matter the value of the number +"proper" means that another rounding mode is used, be it "round to nearest", +"round up", "round down". +.IP \(bu +-basis : the basis of the floating-point representation. +The basis is usually 2, i.e. binary representation (for example IEEE 754 machines), +but some machines (like HP calculators for example) uses 10, or 16, etc... +.IP \(bu +-mantissa : the number of bits in the mantissa +.IP \(bu +-exponentmax : the largest positive exponent before overflow occurs +.IP \(bu +-exponentmin : the largest negative exponent before (gradual) underflow occurs +.IP \(bu +-vmax : largest positive value before overflow occurs +.IP \(bu +-vmin : largest negative value before (gradual) underflow occurs +.RE +.TP +\fIobjectname\fR \fBtostring\fR +Return a report for machine parameters. +.TP +\fIobjectname\fR \fBprint\fR +Print machine parameters on standard output. +.PP +.SH COPYRIGHT +.nf +Copyright (c) 2008 Michael Baudin <michael.baudin@sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/math.n Index: embedded/man/files/modules/math/math.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/math.n @@ -0,0 +1,376 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/math.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math" n 1.2.5 tcllib "Tcl Math Library" +.BS +.SH NAME +math \- Tcl Math Library +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmath ?1.2.5?\fR +.sp +\fB::math::cov\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::integrate\fR \fIlist of xy value pairs\fR +.sp +\fB::math::fibonacci\fR \fIn\fR +.sp +\fB::math::max\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::mean\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::min\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::product\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::random\fR ?\fIvalue1\fR? ?\fIvalue2\fR? +.sp +\fB::math::sigma\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::stats\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fB::math::sum\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath\fR package provides utility math functions. +.PP +Besides a set of basic commands, available via the package \fImath\fR, +there are more specialised packages: +.IP \(bu +\fBmath::bigfloat\fR - Arbitrary-precision floating-point +arithmetic +.IP \(bu +\fBmath::bignum\fR - Arbitrary-precision integer arithmetic +.IP \(bu +\fBmath::calculus::romberg\fR - Robust integration methods for +functions of one variable, using Romberg integration +.IP \(bu +\fBmath::calculus\fR - Integration of functions, solving ordinary +differential equations +.IP \(bu +\fBmath::combinatorics\fR - Procedures for various combinatorial +functions (for instance the Gamma function and "k out of n") +.IP \(bu +\fBmath::complexnumbers\fR - Complex number arithmetic +.IP \(bu +\fBmath::constants\fR - A set of well-known mathematical +constants, such as Pi, E, and the golden ratio +.IP \(bu +\fBmath::fourier\fR - Discrete Fourier transforms +.IP \(bu +\fBmath::fuzzy\fR - Fuzzy comparisons of floating-point numbers +.IP \(bu +\fBmath::geometry\fR - 2D geometrical computations +.IP \(bu +\fBmath::interpolate\fR - Various interpolation methods +.IP \(bu +\fBmath::linearalgebra\fR - Linear algebra package +.IP \(bu +\fBmath::optimize\fR - Optimization methods +.IP \(bu +\fBmath::polynomials\fR - Polynomial arithmetic (includes families +of classical polynomials) +.IP \(bu +\fBmath::rationalfunctions\fR - Arithmetic of rational functions +.IP \(bu +\fBmath::roman\fR - Manipulation (including arithmetic) of Roman +numerals +.IP \(bu +\fBmath::special\fR - Approximations of special functions from +mathematical physics +.IP \(bu +\fBmath::statistics\fR - Statistical operations and tests +.PP +.SH "BASIC COMMANDS" +.TP +\fB::math::cov\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the coefficient of variation expressed as percent of two or +more numeric values. +.TP +\fB::math::integrate\fR \fIlist of xy value pairs\fR +Return the area under a "curve" defined by a set of x,y pairs and the +error bound as a list. +.TP +\fB::math::fibonacci\fR \fIn\fR +Return the \fIn\fR'th Fibonacci number. +.TP +\fB::math::max\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the maximum of one or more numeric values. +.TP +\fB::math::mean\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the mean, or "average" of one or more numeric values. +.TP +\fB::math::min\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the minimum of one or more numeric values. +.TP +\fB::math::product\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the product of one or more numeric values. +.TP +\fB::math::random\fR ?\fIvalue1\fR? ?\fIvalue2\fR? +Return a random number. If no arguments are given, the number is a +floating point value between 0 and 1. If one argument is given, the +number is an integer value between 0 and \fIvalue1\fR. If two +arguments are given, the number is an integer value between +\fIvalue1\fR and \fIvalue2\fR. +.TP +\fB::math::sigma\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the population standard deviation of two or more numeric +values. +.TP +\fB::math::stats\fR \fIvalue\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the mean, standard deviation, and coefficient of variation (as +percent) as a list. +.TP +\fB::math::sum\fR \fIvalue\fR ?\fIvalue ...\fR? +Return the sum of one or more numeric values. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +math, statistics +.SH CATEGORY +Mathematics ADDED embedded/man/files/modules/math/math_geometry.n Index: embedded/man/files/modules/math/math_geometry.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/math_geometry.n @@ -0,0 +1,756 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/math_geometry.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2001 by Ideogramic ApS and other parties +'\" Copyright (c) 2004 by Arjen Markus +'\" Copyright (c) 2010 by Andreas Kupries +'\" Copyright (c) 2010 by Kevin Kenny +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::geometry" n 1.1.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::geometry \- Geometrical computations +.SH SYNOPSIS +package require \fBTcl ?8.3?\fR +.sp +package require \fBmath::geometry ?1.1.2?\fR +.sp +\fB::math::geometry::+\fR \fIpoint1\fR \fIpoint2\fR +.sp +\fB::math::geometry::-\fR \fIpoint1\fR \fIpoint2\fR +.sp +\fB::math::geometry::p\fR \fIx\fR \fIy\fR +.sp +\fB::math::geometry::distance\fR \fIpoint1\fR \fIpoint2\fR +.sp +\fB::math::geometry::length\fR \fIpoint\fR +.sp +\fB::math::geometry::s*\fR \fIfactor\fR \fIpoint\fR +.sp +\fB::math::geometry::direction\fR \fIangle\fR +.sp +\fB::math::geometry::h\fR \fIlength\fR +.sp +\fB::math::geometry::v\fR \fIlength\fR +.sp +\fB::math::geometry::between\fR \fIpoint1\fR \fIpoint2\fR \fIs\fR +.sp +\fB::math::geometry::octant\fR \fIpoint\fR +.sp +\fB::math::geometry::rect\fR \fInw\fR \fIse\fR +.sp +\fB::math::geometry::nwse\fR \fIrect\fR +.sp +\fB::math::geometry::angle\fR \fIline\fR +.sp +\fB::math::geometry::calculateDistanceToLine\fR \fIP\fR \fIline\fR +.sp +\fB::math::geometry::calculateDistanceToLineSegment\fR \fIP\fR \fIlinesegment\fR +.sp +\fB::math::geometry::calculateDistanceToPolyline\fR \fIP\fR \fIpolyline\fR +.sp +\fB::math::geometry::findClosestPointOnLine\fR \fIP\fR \fIline\fR +.sp +\fB::math::geometry::findClosestPointOnLineSegment\fR \fIP\fR \fIlinesegment\fR +.sp +\fB::math::geometry::findClosestPointOnPolyline\fR \fIP\fR \fIpolyline\fR +.sp +\fB::math::geometry::lengthOfPolyline\fR \fIpolyline\fR +.sp +\fB::math::geometry::movePointInDirection\fR \fIP\fR \fIdirection\fR \fIdist\fR +.sp +\fB::math::geometry::lineSegmentsIntersect\fR \fIlinesegment1\fR \fIlinesegment2\fR +.sp +\fB::math::geometry::findLineSegmentIntersection\fR \fIlinesegment1\fR \fIlinesegment2\fR +.sp +\fB::math::geometry::findLineIntersection\fR \fIline1\fR \fIline2\fR +.sp +\fB::math::geometry::polylinesIntersect\fR \fIpolyline1\fR \fIpolyline2\fR +.sp +\fB::math::geometry::polylinesBoundingIntersect\fR \fIpolyline1\fR \fIpolyline2\fR \fIgranularity\fR +.sp +\fB::math::geometry::intervalsOverlap\fR \fIy1\fR \fIy2\fR \fIy3\fR \fIy4\fR \fIstrict\fR +.sp +\fB::math::geometry::rectanglesOverlap\fR \fIP1\fR \fIP2\fR \fIQ1\fR \fIQ2\fR \fIstrict\fR +.sp +\fB::math::geometry::bbox\fR \fIpolyline\fR +.sp +\fB::math::geometry::pointInsidePolygon\fR \fIP\fR \fIpolyline\fR +.sp +\fB::math::geometry::rectangleInsidePolygon\fR \fIP1\fR \fIP2\fR \fIpolyline\fR +.sp +\fB::math::geometry::areaPolygon\fR \fIpolygon\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath::geometry\fR package is a collection of functions for +computations and manipulations on two-dimensional geometrical objects, +such as points, lines and polygons. +.PP +The geometrical objects are implemented as plain lists of coordinates. +For instance a line is defined by a list of four numbers, the x- and +y-coordinate of a first point and the x- and y-coordinates of a second +point on the line. +.PP +The various types of object are recognised by the number of coordinate +pairs and the context in which they are used: a list of four elements +can be regarded as an infinite line, a finite line segment but also +as a polyline of one segment and a point set of two points. +.PP +Currently the following types of objects are distinguished: +.IP \(bu +\fIpoint\fR - a list of two coordinates representing the x- and +y-coordinates respectively. +.IP \(bu +\fIline\fR - a list of four coordinates, interpreted as the x- and +y-coordinates of two distinct points on the line. +.IP \(bu +\fIline segment\fR - a list of four coordinates, interpreted as the +x- and y-coordinates of the first and the last points on the line +segment. +.IP \(bu +\fIpolyline\fR - a list of an even number of coordinates, +interpreted as the x- and y-coordinates of an ordered set of points. +.IP \(bu +\fIpolygon\fR - like a polyline, but the implicit assumption is that +the polyline is closed (if the first and last points do not coincide, +the missing segment is automatically added). +.IP \(bu +\fIpoint set\fR - again a list of an even number of coordinates, but +the points are regarded without any ordering. +.PP +.SH PROCEDURES +The package defines the following public procedures: +.TP +\fB::math::geometry::+\fR \fIpoint1\fR \fIpoint2\fR +Compute the sum of the two vectors given as points and return it. +The result is a vector as well. +.TP +\fB::math::geometry::-\fR \fIpoint1\fR \fIpoint2\fR +Compute the difference (point1 - point2) of the two vectors +given as points and return it. The result is a vector as well. +.TP +\fB::math::geometry::p\fR \fIx\fR \fIy\fR +Construct a point from its coordinates and return it as the +result of the command. +.TP +\fB::math::geometry::distance\fR \fIpoint1\fR \fIpoint2\fR +Compute the distance between the two points and return it as the +result of the command. This is in essence the same as +.CS + + + math::geometry::length [math::geomtry::- point1 point2] + +.CE +.TP +\fB::math::geometry::length\fR \fIpoint\fR +Compute the length of the vector and return it as the +result of the command. +.TP +\fB::math::geometry::s*\fR \fIfactor\fR \fIpoint\fR +Scale the vector by the factor and return it as the +result of the command. This is a vector as well. +.TP +\fB::math::geometry::direction\fR \fIangle\fR +Given the angle in degrees this command computes and returns +the unit vector pointing into this direction. The vector for +angle == 0 points to the right (up), and for angle == 90 up (north). +.TP +\fB::math::geometry::h\fR \fIlength\fR +Returns a horizontal vector on the X-axis of the specified length. +Positive lengths point to the right (east). +.TP +\fB::math::geometry::v\fR \fIlength\fR +Returns a vertical vector on the Y-axis of the specified length. +Positive lengths point down (south). +.TP +\fB::math::geometry::between\fR \fIpoint1\fR \fIpoint2\fR \fIs\fR +Compute the point which is at relative distance \fIs\fR between the two +points and return it as the result of the command. A relative distance of +\fB0\fR returns \fIpoint1\fR, the distance \fB1\fR returns \fIpoint2\fR. +Distances < 0 or > 1 extrapolate along the line between the two point. +.TP +\fB::math::geometry::octant\fR \fIpoint\fR +Compute the octant of the circle the point is in and return it as the result +of the command. The possible results are +.RS +.IP [1] +east +.IP [2] +northeast +.IP [3] +north +.IP [4] +northwest +.IP [5] +west +.IP [6] +southwest +.IP [7] +south +.IP [8] +southeast +.RE +.IP +Each octant is the arc of the circle +/- 22.5 degrees from the cardinal direction +the octant is named for. +.TP +\fB::math::geometry::rect\fR \fInw\fR \fIse\fR +Construct a rectangle from its northwest and southeast corners and return +it as the result of the command. +.TP +\fB::math::geometry::nwse\fR \fIrect\fR +Extract the northwest and southeast corners of the rectangle and return +them as the result of the command (a 2-element list containing the +points, in the named order). +.TP +\fB::math::geometry::angle\fR \fIline\fR +Calculate the angle from the positive x-axis to a given line +(in two dimensions only). +.RS +.TP +list \fIline\fR +Coordinates of the line +.RE +.sp +.TP +\fB::math::geometry::calculateDistanceToLine\fR \fIP\fR \fIline\fR +Calculate the distance of point P to the (infinite) line and return the +result +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIline\fR +List of four numbers, the coordinates of two points +on the line +.RE +.sp +.TP +\fB::math::geometry::calculateDistanceToLineSegment\fR \fIP\fR \fIlinesegment\fR +Calculate the distance of point P to the (finite) line segment and +return the result. +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIlinesegment\fR +List of four numbers, the coordinates of the +first and last points of the line segment +.RE +.sp +.sp +.TP +\fB::math::geometry::calculateDistanceToPolyline\fR \fIP\fR \fIpolyline\fR +Calculate the distance of point P to the polyline and +return the result. +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIpolyline\fR +List of numbers, the coordinates of the +vertices of the polyline +.RE +.sp +.TP +\fB::math::geometry::findClosestPointOnLine\fR \fIP\fR \fIline\fR +Return the point on a line which is closest to a given point. +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIline\fR +List of four numbers, the coordinates of two points +on the line +.RE +.sp +.TP +\fB::math::geometry::findClosestPointOnLineSegment\fR \fIP\fR \fIlinesegment\fR +Return the point on a \fIline segment\fR which is closest to a given +point. +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIlinesegment\fR +List of four numbers, the first and last +points on the line segment +.RE +.sp +.TP +\fB::math::geometry::findClosestPointOnPolyline\fR \fIP\fR \fIpolyline\fR +Return the point on a \fIpolyline\fR which is closest to a given +point. +.RS +.TP +list \fIP\fR +List of two numbers, the coordinates of the point +.TP +list \fIpolyline\fR +List of numbers, the vertices of the polyline +.RE +.sp +.TP +\fB::math::geometry::lengthOfPolyline\fR \fIpolyline\fR +Return the length of the \fIpolyline\fR (note: it not regarded as a +polygon) +.RS +.TP +list \fIpolyline\fR +List of numbers, the vertices of the polyline +.RE +.sp +.TP +\fB::math::geometry::movePointInDirection\fR \fIP\fR \fIdirection\fR \fIdist\fR +Move a point over a given distance in a given direction and return the +new coordinates (in two dimensions only). +.RS +.TP +list \fIP\fR +Coordinates of the point to be moved +.TP +double \fIdirection\fR +Direction (in degrees; 0 is to the right, 90 +upwards) +.TP +list \fIdist\fR +Distance over which to move the point +.RE +.sp +.TP +\fB::math::geometry::lineSegmentsIntersect\fR \fIlinesegment1\fR \fIlinesegment2\fR +Check if two line segments intersect or coincide. Returns 1 if that is +the case, 0 otherwise (in two dimensions only). +.RS +.TP +list \fIlinesegment1\fR +First line segment +.TP +list \fIlinesegment2\fR +Second line segment +.RE +.sp +.TP +\fB::math::geometry::findLineSegmentIntersection\fR \fIlinesegment1\fR \fIlinesegment2\fR +Find the intersection point of two line segments. Return the coordinates +or the keywords "coincident" or "none" if the line segments coincide or +have no points in common (in two dimensions only). +.RS +.TP +list \fIlinesegment1\fR +First line segment +.TP +list \fIlinesegment2\fR +Second line segment +.RE +.sp +.TP +\fB::math::geometry::findLineIntersection\fR \fIline1\fR \fIline2\fR +Find the intersection point of two (infinite) lines. Return the coordinates +or the keywords "coincident" or "none" if the lines coincide or +have no points in common (in two dimensions only). +.RS +.TP +list \fIline1\fR +First line +.TP +list \fIline2\fR +Second line +.RE +.IP +See section \fBReferences\fR for details on the algorithm and math behind it. +.sp +.TP +\fB::math::geometry::polylinesIntersect\fR \fIpolyline1\fR \fIpolyline2\fR +Check if two polylines intersect or not (in two dimensions only). +.RS +.TP +list \fIpolyline1\fR +First polyline +.TP +list \fIpolyline2\fR +Second polyline +.RE +.sp +.TP +\fB::math::geometry::polylinesBoundingIntersect\fR \fIpolyline1\fR \fIpolyline2\fR \fIgranularity\fR +Check whether two polylines intersect, but reduce +the correctness of the result to the given granularity. +Use this for faster, but weaker, intersection checking. +.sp +How it works: +.sp +Each polyline is split into a number of smaller polylines, +consisting of granularity points each. If a pair of those smaller +lines' bounding boxes intersect, then this procedure returns 1, +otherwise it returns 0. +.RS +.TP +list \fIpolyline1\fR +First polyline +.TP +list \fIpolyline2\fR +Second polyline +.TP +int \fIgranularity\fR +Number of points in each part (<=1 means check +every edge) +.RE +.sp +.TP +\fB::math::geometry::intervalsOverlap\fR \fIy1\fR \fIy2\fR \fIy3\fR \fIy4\fR \fIstrict\fR +Check if two intervals overlap. +.RS +.TP +double \fIy1,y2\fR +Begin and end of first interval +.TP +double \fIy3,y4\fR +Begin and end of second interval +.TP +logical \fIstrict\fR +Check for strict or non-strict overlap +.RE +.sp +.TP +\fB::math::geometry::rectanglesOverlap\fR \fIP1\fR \fIP2\fR \fIQ1\fR \fIQ2\fR \fIstrict\fR +Check if two rectangles overlap. +.RS +.TP +list \fIP1\fR +upper-left corner of the first rectangle +.TP +list \fIP2\fR +lower-right corner of the first rectangle +.TP +list \fIQ1\fR +upper-left corner of the second rectangle +.TP +list \fIQ2\fR +lower-right corner of the second rectangle +.TP +list \fIstrict\fR +choosing strict or non-strict interpretation +.RE +.sp +.TP +\fB::math::geometry::bbox\fR \fIpolyline\fR +Calculate the bounding box of a polyline. Returns a list of four +coordinates: the upper-left and the lower-right corner of the box. +.RS +.TP +list \fIpolyline\fR +The polyline to be examined +.RE +.sp +.TP +\fB::math::geometry::pointInsidePolygon\fR \fIP\fR \fIpolyline\fR +Determine if a point is completely inside a polygon. If the point +touches the polygon, then the point is not completely inside the +polygon. +.RS +.TP +list \fIP\fR +Coordinates of the point +.TP +list \fIpolyline\fR +The polyline to be examined +.RE +.sp +.TP +\fB::math::geometry::rectangleInsidePolygon\fR \fIP1\fR \fIP2\fR \fIpolyline\fR +Determine if a rectangle is completely inside a polygon. If polygon +touches the rectangle, then the rectangle is not complete inside the +polygon. +.RS +.TP +list \fIP1\fR +Upper-left corner of the rectangle +.TP +list \fIP2\fR +Lower-right corner of the rectangle +.sp +.TP +list \fIpolygon\fR +The polygon in question +.RE +.sp +.TP +\fB::math::geometry::areaPolygon\fR \fIpolygon\fR +Calculate the area of a polygon. +.RS +.TP +list \fIpolygon\fR +The polygon in question +.RE +.PP +.SH REFERENCES +.IP [1] +\fIPolygon Intersection\fR [http:/wiki.tcl.tk/12070] +.IP [2] +\fIhttp://en.wikipedia.org/wiki/Line-line_intersection\fR +.IP [3] +\fIhttp://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: geometry\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +angle, distance, line, math, plane geometry, point +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2001 by Ideogramic ApS and other parties +Copyright (c) 2004 by Arjen Markus +Copyright (c) 2010 by Andreas Kupries +Copyright (c) 2010 by Kevin Kenny + +.fi ADDED embedded/man/files/modules/math/numtheory.n Index: embedded/man/files/modules/math/numtheory.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/numtheory.n @@ -0,0 +1,298 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/numtheory.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010 Lars Hellström <Lars dot Hellstrom at residenset dot net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::numtheory" n 1.0 tcllib "Tcl Math Library" +.BS +.SH NAME +math::numtheory \- Number Theory +.SH SYNOPSIS +package require \fBTcl ?8.5?\fR +.sp +package require \fBmath::numtheory ?1.0?\fR +.sp +\fBmath::numtheory::isprime\fR \fIN\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +.BE +.SH DESCRIPTION +.PP +This package is for collecting various number-theoretic operations, +though at the moment it only provides that of testing whether an +integer is a prime. +.TP +\fBmath::numtheory::isprime\fR \fIN\fR ?\fIoption\fR \fIvalue\fR ...? +The \fBisprime\fR command tests whether the integer \fIN\fR is a +prime, returning a boolean true value for prime \fIN\fR and a +boolean false value for non-prime \fIN\fR. The formal definition of +\'prime' used is the conventional, that the number being tested is +greater than 1 and only has trivial divisors. +.sp +To be precise, the return value is one of \fB0\fR (if \fIN\fR is +definitely not a prime), \fB1\fR (if \fIN\fR is definitely a +prime), and \fBon\fR (if \fIN\fR is probably prime); the latter +two are both boolean true values. The case that an integer may be +classified as "probably prime" arises because the Miller-Rabin +algorithm used in the test implementation is basically probabilistic, +and may if we are unlucky fail to detect that a number is in fact +composite. Options may be used to select the risk of such +"false positives" in the test. \fB1\fR is returned for "small" +\fIN\fR (which currently means \fIN\fR < 118670087467), where it is +known that no false positives are possible. +.sp +The only option currently defined is: +.RS +.TP +\fB-randommr\fR \fIrepetitions\fR +which controls how many times the Miller-Rabin test should be +repeated with randomly chosen bases. Each repetition reduces the +probability of a false positive by a factor at least 4. The +default for \fIrepetitions\fR is 4. +.RE +.IP +Unknown options are silently ignored. +.PP +.SH KEYWORDS +number theory, prime +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2010 Lars Hellström <Lars dot Hellstrom at residenset dot net> + +.fi ADDED embedded/man/files/modules/math/optimize.n Index: embedded/man/files/modules/math/optimize.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/optimize.n @@ -0,0 +1,589 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/optimize.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" Copyright (c) 2004,2005 Kevn B. Kenny <kennykb@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::optimize" n 1.0 tcllib "Tcl Math Library" +.BS +.SH NAME +math::optimize \- Optimisation routines +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmath::optimize ?1.0?\fR +.sp +\fB::math::optimize::minimum\fR \fIbegin\fR \fIend\fR \fIfunc\fR \fImaxerr\fR +.sp +\fB::math::optimize::maximum\fR \fIbegin\fR \fIend\fR \fIfunc\fR \fImaxerr\fR +.sp +\fB::math::optimize::min_bound_1d\fR \fIfunc\fR \fIbegin\fR \fIend\fR ?\fB-relerror\fR \fIreltol\fR? ?\fB-abserror\fR \fIabstol\fR? ?\fB-maxiter\fR \fImaxiter\fR? ?\fB-trace\fR \fItraceflag\fR? +.sp +\fB::math::optimize::min_unbound_1d\fR \fIfunc\fR \fIbegin\fR \fIend\fR ?\fB-relerror\fR \fIreltol\fR? ?\fB-abserror\fR \fIabstol\fR? ?\fB-maxiter\fR \fImaxiter\fR? ?\fB-trace\fR \fItraceflag\fR? +.sp +\fB::math::optimize::solveLinearProgram\fR \fIobjective\fR \fIconstraints\fR +.sp +\fB::math::optimize::linearProgramMaximum\fR \fIobjective\fR \fIresult\fR +.sp +\fB::math::optimize::nelderMead\fR \fIobjective\fR \fIxVector\fR ?\fB-scale\fR \fIxScaleVector\fR? ?\fB-ftol\fR \fIepsilon\fR? ?\fB-maxiter\fR \fIcount\fR? ??-trace? \fIflag\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This package implements several optimisation algorithms: +.IP \(bu +Minimize or maximize a function over a given interval +.IP \(bu +Solve a linear program (maximize a linear function subject to linear +constraints) +.IP \(bu +Minimize a function of several variables given an initial guess for the +location of the minimum. +.PP +.PP +The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, the +algorithms have been used in a straightforward manner. +.PP +This document describes the procedures and explains their usage. +.SH PROCEDURES +.PP +This package defines the following public procedures: +.TP +\fB::math::optimize::minimum\fR \fIbegin\fR \fIend\fR \fIfunc\fR \fImaxerr\fR +Minimize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the minimum. No guarantee is made that the \fIglobal\fR +minimum is found. +.sp +The procedure returns the "x" value for which the function is minimal. +.sp +\fIThis procedure has been deprecated - use min_bound_1d instead\fR +.sp +\fIbegin\fR - Start of the interval +.sp +\fIend\fR - End of the interval +.sp +\fIfunc\fR - Name of the function to be minimized (a procedure taking +one argument). +.sp +\fImaxerr\fR - Maximum relative error (defaults to 1.0e-4) +.TP +\fB::math::optimize::maximum\fR \fIbegin\fR \fIend\fR \fIfunc\fR \fImaxerr\fR +Maximize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the maximum. No guarantee is made that the \fIglobal\fR +maximum is found. +.sp +The procedure returns the "x" value for which the function is maximal. +.sp +\fIThis procedure has been deprecated - use max_bound_1d instead\fR +.sp +\fIbegin\fR - Start of the interval +.sp +\fIend\fR - End of the interval +.sp +\fIfunc\fR - Name of the function to be maximized (a procedure taking +one argument). +.sp +\fImaxerr\fR - Maximum relative error (defaults to 1.0e-4) +.TP +\fB::math::optimize::min_bound_1d\fR \fIfunc\fR \fIbegin\fR \fIend\fR ?\fB-relerror\fR \fIreltol\fR? ?\fB-abserror\fR \fIabstol\fR? ?\fB-maxiter\fR \fImaxiter\fR? ?\fB-trace\fR \fItraceflag\fR? +Miminizes a function of one variable in the given interval. The procedure +uses Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a \fIglobal\fR minimum is found. The function to evaluate, \fIfunc\fR, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument. +.sp +\fIx1\fR and \fIx2\fR are the two bounds of +the interval in which the minimum is to be found. They need not be in +increasing order. +.sp +\fIreltol\fR, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. \fIabstol\fR, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of \fIabstol\fR to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale. +.sp +\fImaxiter\fR may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than \fImaxiter\fR times, it returns an error to the caller. +.sp +\fItraceFlag\fR is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace). +.TP +\fB::math::optimize::min_unbound_1d\fR \fIfunc\fR \fIbegin\fR \fIend\fR ?\fB-relerror\fR \fIreltol\fR? ?\fB-abserror\fR \fIabstol\fR? ?\fB-maxiter\fR \fImaxiter\fR? ?\fB-trace\fR \fItraceflag\fR? +Miminizes a function of one variable over the entire real number line. +The procedure uses parabolic extrapolation combined with golden-section +dilatation to search for a region where a minimum exists, followed by +Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a \fIglobal\fR minimum is found. The function to evaluate, \fIfunc\fR, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument. +.sp +\fIx1\fR and \fIx2\fR are two initial guesses at where the minimum +may lie. \fIx1\fR is the starting point for the minimization, and +the difference between \fIx2\fR and \fIx1\fR is used as a hint at the +characteristic length scale of the problem. +.sp +\fIreltol\fR, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. \fIabstol\fR, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of \fIabstol\fR to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale. +.sp +\fImaxiter\fR may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than \fImaxiter\fR times, it returns an error to the caller. +.sp +\fItraceFlag\fR is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace). +.TP +\fB::math::optimize::solveLinearProgram\fR \fIobjective\fR \fIconstraints\fR +Solve a \fIlinear program\fR in standard form using a straightforward +implementation of the Simplex algorithm. (In the explanation below: The +linear program has N constraints and M variables). +.sp +The procedure returns a list of M values, the values for which the +objective function is maximal or a single keyword if the linear program +is not feasible or unbounded (either "unfeasible" or "unbounded") +.sp +\fIobjective\fR - The M coefficients of the objective function +.sp +\fIconstraints\fR - Matrix of coefficients plus maximum values that +implement the linear constraints. It is expected to be a list of N lists +of M+1 numbers each, M coefficients and the maximum value. +.TP +\fB::math::optimize::linearProgramMaximum\fR \fIobjective\fR \fIresult\fR +Convenience function to return the maximum for the solution found by the +solveLinearProgram procedure. +.sp +\fIobjective\fR - The M coefficients of the objective function +.sp +\fIresult\fR - The result as returned by solveLinearProgram +.TP +\fB::math::optimize::nelderMead\fR \fIobjective\fR \fIxVector\fR ?\fB-scale\fR \fIxScaleVector\fR? ?\fB-ftol\fR \fIepsilon\fR? ?\fB-maxiter\fR \fIcount\fR? ??-trace? \fIflag\fR? +Minimizes, in unconstrained fashion, a function of several variable over all +of space. The function to evaluate, \fIobjective\fR, must be a single Tcl +command. To it will be appended as many elements as appear in the initial guess at +the location of the minimum, passed in as a Tcl list, \fIxVector\fR. +.sp +\fIxScaleVector\fR is an initial guess at the problem scale; the first +function evaluations will be made by varying the co-ordinates in \fIxVector\fR +by the amounts in \fIxScaleVector\fR. If \fIxScaleVector\fR is not supplied, +the co-ordinates will be varied by a factor of 1.0001 (if the co-ordinate +is non-zero) or by a constant 0.0001 (if the co-ordinate is zero). +.sp +\fIepsilon\fR is the desired relative error in the value of the function +evaluated at the minimum. The default is 1.0e-7, which usually gives three +significant digits of accuracy in the values of the x's. +.sp +pp +\fIcount\fR is a limit on the number of trips through the main loop of +the optimizer. The number of function evaluations may be several times +this number. If the optimizer fails to find a minimum to within \fIftol\fR +in \fImaxiter\fR iterations, it returns its current best guess and an +error status. Default is to allow 500 iterations. +.sp +\fIflag\fR is a flag that, if true, causes a line to be written to the +standard output for each evaluation of the objective function, giving +the arguments presented to the function and the value returned. Default is +false. +.sp +The \fBnelderMead\fR procedure returns a list of alternating keywords and +values suitable for use with \fBarray set\fR. The meaning of the keywords is: +.sp +\fIx\fR is the approximate location of the minimum. +.sp +\fIy\fR is the value of the function at \fIx\fR. +.sp +\fIyvec\fR is a vector of the best N+1 function values achieved, where +N is the dimension of \fIx\fR +.sp +\fIvertices\fR is a list of vectors giving the function arguments +corresponding to the values in \fIyvec\fR. +.sp +\fInIter\fR is the number of iterations required to achieve convergence or +fail. +.sp +\fIstatus\fR is 'ok' if the operation succeeded, or 'too-many-iterations' +if the maximum iteration count was exceeded. +.sp +\fBnelderMead\fR minimizes the given function using the downhill +simplex method of Nelder and Mead. This method is quite slow - much +faster methods for minimization are known - but has the advantage of being +extremely robust in the face of problems where the minimum lies in +a valley of complex topology. +.sp +\fBnelderMead\fR can occasionally find itself "stuck" at a point where +it can make no further progress; it is recommended that the caller +run it at least a second time, passing as the initial guess the +result found by the previous call. The second run is usually very +fast. +.sp +\fBnelderMead\fR can be used in some cases for constrained optimization. +To do this, add a large value to the objective function if the parameters +are outside the feasible region. To work effectively in this mode, +\fBnelderMead\fR requires that the initial guess be feasible and +usually requires that the feasible region be convex. +.PP +.SH NOTES +.PP +Several of the above procedures take the \fInames\fR of procedures as +arguments. To avoid problems with the \fIvisibility\fR of these +procedures, the fully-qualified name of these procedures is determined +inside the optimize routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance: +.CS + + + namespace eval ::mySpace { + namespace export calcfunc + proc calcfunc { x } { return $x } + } + # + # Use a fully-qualified name + # + namespace eval ::myCalc { + puts [min_bound_1d ::myCalc::calcfunc $begin $end] + } + # + # Import the name + # + namespace eval ::myCalc { + namespace import ::mySpace::calcfunc + puts [min_bound_1d calcfunc $begin $end] + } + +.CE +The simple procedures \fIminimum\fR and \fImaximum\fR have been +deprecated: the alternatives are much more flexible, robust and +require less function evaluations. +.SH EXAMPLES +.PP +Let us take a few simple examples: +.PP +Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10): +.CS + + +proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} } +puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]" + +.CE +.PP +The maximum allowed error determines the number of steps taken (with +each step in the iteration the interval is reduced with a factor 1/2). +Hence, a maximum error of 0.0001 is achieved in approximately 14 steps. +.PP +An example of a \fIlinear program\fR is: +.PP +Optimise the expression 3x+2y, where: +.CS + + + x >= 0 and y >= 0 (implicit constraints, part of the + definition of linear programs) + + x + y <= 1 (constraints specific to the problem) + 2x + 5y <= 10 + +.CE +.PP +This problem can be solved as follows: +.CS + + + + set solution [::math::optimize::solveLinearProgram { 3.0 2.0 } { { 1.0 1.0 1.0 } + { 2.0 5.0 10.0 } } ] + +.CE +.PP +Note, that a constraint like: +.CS + + + x + y >= 1 + +.CE +can be turned into standard form using: +.CS + + + -x -y <= -1 + +.CE +.PP +The theory of linear programming is the subject of many a text book and +the Simplex algorithm that is implemented here is the best-known +method to solve this type of problems, but it is not the only one. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: optimize\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +linear program, math, maximum, minimum, optimization +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +Copyright (c) 2004,2005 Kevn B. Kenny <kennykb@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/polynomials.n Index: embedded/man/files/modules/math/polynomials.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/polynomials.n @@ -0,0 +1,478 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/polynomials.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::polynomials" n 1.0.1 tcllib "Tcl Math Library" +.BS +.SH NAME +math::polynomials \- Polynomial functions +.SH SYNOPSIS +package require \fBTcl ?8.3?\fR +.sp +package require \fBmath::polynomials ?1.0.1?\fR +.sp +\fB::math::polynomials::polynomial\fR \fIcoeffs\fR +.sp +\fB::math::polynomials::polynCmd\fR \fIcoeffs\fR +.sp +\fB::math::polynomials::evalPolyn\fR \fIpolynomial\fR \fIx\fR +.sp +\fB::math::polynomials::addPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +.sp +\fB::math::polynomials::subPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +.sp +\fB::math::polynomials::multPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +.sp +\fB::math::polynomials::divPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +.sp +\fB::math::polynomials::remainderPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +.sp +\fB::math::polynomials::derivPolyn\fR \fIpolyn\fR +.sp +\fB::math::polynomials::primitivePolyn\fR \fIpolyn\fR +.sp +\fB::math::polynomials::degreePolyn\fR \fIpolyn\fR +.sp +\fB::math::polynomials::coeffPolyn\fR \fIpolyn\fR \fIindex\fR +.sp +\fB::math::polynomials::allCoeffsPolyn\fR \fIpolyn\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package deals with polynomial functions of one variable: +.IP \(bu +the basic arithmetic operations are extended to polynomials +.IP \(bu +computing the derivatives and primitives of these functions +.IP \(bu +evaluation through a general procedure or via specific procedures) +.PP +.SH PROCEDURES +The package defines the following public procedures: +.TP +\fB::math::polynomials::polynomial\fR \fIcoeffs\fR +Return an (encoded) list that defines the polynomial. A polynomial +.CS + + + f(x) = a + b.x + c.x**2 + d.x**3 + +.CE +.IP +can be defined via: +.CS + + + set f [::math::polynomials::polynomial [list $a $b $c $d] + +.CE +.RS +.TP +list \fIcoeffs\fR +Coefficients of the polynomial (in ascending +order) +.RE +.sp +.TP +\fB::math::polynomials::polynCmd\fR \fIcoeffs\fR +Create a new procedure that evaluates the polynomial. The name of the +polynomial is automatically generated. Useful if you need to evualuate +the polynomial many times, as the procedure consists of a single +[expr] command. +.RS +.TP +list \fIcoeffs\fR +Coefficients of the polynomial (in ascending +order) or the polynomial definition returned by the \fIpolynomial\fR +command. +.RE +.sp +.TP +\fB::math::polynomials::evalPolyn\fR \fIpolynomial\fR \fIx\fR +Evaluate the polynomial at x. +.RS +.TP +list \fIpolynomial\fR +The polynomial's definition (as returned by +the polynomial command). +order) +.TP +float \fIx\fR +The coordinate at which to evaluate the polynomial +.RE +.sp +.TP +\fB::math::polynomials::addPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +Return a new polynomial which is the sum of the two others. +.RS +.TP +list \fIpolyn1\fR +The first polynomial operand +.TP +list \fIpolyn2\fR +The second polynomial operand +.RE +.sp +.TP +\fB::math::polynomials::subPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +Return a new polynomial which is the difference of the two others. +.RS +.TP +list \fIpolyn1\fR +The first polynomial operand +.TP +list \fIpolyn2\fR +The second polynomial operand +.RE +.sp +.TP +\fB::math::polynomials::multPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +Return a new polynomial which is the product of the two others. If one +of the arguments is a scalar value, the other polynomial is simply +scaled. +.RS +.TP +list \fIpolyn1\fR +The first polynomial operand or a scalar +.TP +list \fIpolyn2\fR +The second polynomial operand or a scalar +.RE +.sp +.TP +\fB::math::polynomials::divPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +Divide the first polynomial by the second polynomial and return the +result. The remainder is dropped +.RS +.TP +list \fIpolyn1\fR +The first polynomial operand +.TP +list \fIpolyn2\fR +The second polynomial operand +.RE +.sp +.TP +\fB::math::polynomials::remainderPolyn\fR \fIpolyn1\fR \fIpolyn2\fR +Divide the first polynomial by the second polynomial and return the +remainder. +.RS +.TP +list \fIpolyn1\fR +The first polynomial operand +.TP +list \fIpolyn2\fR +The second polynomial operand +.RE +.sp +.TP +\fB::math::polynomials::derivPolyn\fR \fIpolyn\fR +Differentiate the polynomial and return the result. +.RS +.TP +list \fIpolyn\fR +The polynomial to be differentiated +.RE +.sp +.TP +\fB::math::polynomials::primitivePolyn\fR \fIpolyn\fR +Integrate the polynomial and return the result. The integration +constant is set to zero. +.RS +.TP +list \fIpolyn\fR +The polynomial to be integrated +.RE +.sp +.TP +\fB::math::polynomials::degreePolyn\fR \fIpolyn\fR +Return the degree of the polynomial. +.RS +.TP +list \fIpolyn\fR +The polynomial to be examined +.RE +.sp +.TP +\fB::math::polynomials::coeffPolyn\fR \fIpolyn\fR \fIindex\fR +Return the coefficient of the term of the index'th degree of the +polynomial. +.RS +.TP +list \fIpolyn\fR +The polynomial to be examined +.TP +int \fIindex\fR +The degree of the term +.RE +.sp +.TP +\fB::math::polynomials::allCoeffsPolyn\fR \fIpolyn\fR +Return the coefficients of the polynomial (in ascending order). +.RS +.TP +list \fIpolyn\fR +The polynomial in question +.RE +.PP +.SH "REMARKS ON THE IMPLEMENTATION" +The implementation for evaluating the polynomials at some point uses +Horn's rule, which guarantees numerical stability and a minimum of +arithmetic operations. +To recognise that a polynomial definition is indeed a correct +definition, it consists of a list of two elements: the keyword +"POLYNOMIAL" and the list of coefficients in descending order. The +latter makes it easier to implement Horner's rule. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: polynomials\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +math, polynomial functions +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/qcomplex.n Index: embedded/man/files/modules/math/qcomplex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/qcomplex.n @@ -0,0 +1,537 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/qcomplex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::complexnumbers" n 1.0.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::complexnumbers \- Straightforward complex number package +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBmath::complexnumbers ?1.0.2?\fR +.sp +\fB::math::complexnumbers::+\fR \fIz1\fR \fIz2\fR +.sp +\fB::math::complexnumbers::-\fR \fIz1\fR \fIz2\fR +.sp +\fB::math::complexnumbers::*\fR \fIz1\fR \fIz2\fR +.sp +\fB::math::complexnumbers::/\fR \fIz1\fR \fIz2\fR +.sp +\fB::math::complexnumbers::conj\fR \fIz1\fR +.sp +\fB::math::complexnumbers::real\fR \fIz1\fR +.sp +\fB::math::complexnumbers::imag\fR \fIz1\fR +.sp +\fB::math::complexnumbers::mod\fR \fIz1\fR +.sp +\fB::math::complexnumbers::arg\fR \fIz1\fR +.sp +\fB::math::complexnumbers::complex\fR \fIreal\fR \fIimag\fR +.sp +\fB::math::complexnumbers::tostring\fR \fIz1\fR +.sp +\fB::math::complexnumbers::exp\fR \fIz1\fR +.sp +\fB::math::complexnumbers::sin\fR \fIz1\fR +.sp +\fB::math::complexnumbers::cos\fR \fIz1\fR +.sp +\fB::math::complexnumbers::tan\fR \fIz1\fR +.sp +\fB::math::complexnumbers::log\fR \fIz1\fR +.sp +\fB::math::complexnumbers::sqrt\fR \fIz1\fR +.sp +\fB::math::complexnumbers::pow\fR \fIz1\fR \fIz2\fR +.sp +.BE +.SH DESCRIPTION +.PP +The mathematical module \fIcomplexnumbers\fR provides a straightforward +implementation of complex numbers in pure Tcl. The philosophy is that +the user knows he or she is dealing with complex numbers in an abstract +way and wants as high a performance as can be had within the limitations +of an interpreted language. +.PP +Therefore the procedures defined in this package assume that the +arguments are valid (representations of) "complex numbers", that is, +lists of two numbers defining the real and imaginary part of a +complex number (though this is a mere detail: rely on the +\fIcomplex\fR command to construct a valid number.) +.PP +Most procedures implement the basic arithmetic operations or elementary +functions whereas several others convert to and from different +representations: +.PP +.CS + + + set z [complex 0 1] + puts "z = [tostring $z]" + puts "z**2 = [* $z $z] + +.CE +would result in: +.CS + + + z = i + z**2 = -1 + +.CE +.SH "AVAILABLE PROCEDURES" +The package implements all or most basic operations and elementary +functions. +.PP +\fIThe arithmetic operations are:\fR +.TP +\fB::math::complexnumbers::+\fR \fIz1\fR \fIz2\fR +Add the two arguments and return the resulting complex number +.RS +.TP +complex \fIz1\fR (in) +First argument in the summation +.TP +complex \fIz2\fR (in) +Second argument in the summation +.RE +.sp +.TP +\fB::math::complexnumbers::-\fR \fIz1\fR \fIz2\fR +Subtract the second argument from the first and return the +resulting complex number. If there is only one argument, the +opposite of z1 is returned (i.e. -z1) +.RS +.TP +complex \fIz1\fR (in) +First argument in the subtraction +.TP +complex \fIz2\fR (in) +Second argument in the subtraction (optional) +.RE +.sp +.TP +\fB::math::complexnumbers::*\fR \fIz1\fR \fIz2\fR +Multiply the two arguments and return the resulting complex number +.RS +.TP +complex \fIz1\fR (in) +First argument in the multiplication +.TP +complex \fIz2\fR (in) +Second argument in the multiplication +.RE +.sp +.TP +\fB::math::complexnumbers::/\fR \fIz1\fR \fIz2\fR +Divide the first argument by the second and return the resulting complex +number +.RS +.TP +complex \fIz1\fR (in) +First argument (numerator) in the division +.TP +complex \fIz2\fR (in) +Second argument (denominator) in the division +.RE +.sp +.TP +\fB::math::complexnumbers::conj\fR \fIz1\fR +Return the conjugate of the given complex number +.RS +.TP +complex \fIz1\fR (in) +Complex number in question +.RE +.sp +.PP +.PP +\fIConversion/inquiry procedures:\fR +.TP +\fB::math::complexnumbers::real\fR \fIz1\fR +Return the real part of the given complex number +.RS +.TP +complex \fIz1\fR (in) +Complex number in question +.RE +.sp +.TP +\fB::math::complexnumbers::imag\fR \fIz1\fR +Return the imaginary part of the given complex number +.RS +.TP +complex \fIz1\fR (in) +Complex number in question +.RE +.sp +.TP +\fB::math::complexnumbers::mod\fR \fIz1\fR +Return the modulus of the given complex number +.RS +.TP +complex \fIz1\fR (in) +Complex number in question +.RE +.sp +.TP +\fB::math::complexnumbers::arg\fR \fIz1\fR +Return the argument ("angle" in radians) of the given complex number +.RS +.TP +complex \fIz1\fR (in) +Complex number in question +.RE +.sp +.TP +\fB::math::complexnumbers::complex\fR \fIreal\fR \fIimag\fR +Construct the complex number "real + imag*i" and return it +.RS +.TP +float \fIreal\fR (in) +The real part of the new complex number +.TP +float \fIimag\fR (in) +The imaginary part of the new complex number +.RE +.sp +.TP +\fB::math::complexnumbers::tostring\fR \fIz1\fR +Convert the complex number to the form "real + imag*i" and return the +string +.RS +.TP +float \fIcomplex\fR (in) +The complex number to be converted +.RE +.sp +.PP +.PP +\fIElementary functions:\fR +.TP +\fB::math::complexnumbers::exp\fR \fIz1\fR +Calculate the exponential for the given complex argument and return the +result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::sin\fR \fIz1\fR +Calculate the sine function for the given complex argument and return +the result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::cos\fR \fIz1\fR +Calculate the cosine function for the given complex argument and return +the result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::tan\fR \fIz1\fR +Calculate the tangent function for the given complex argument and +return the result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::log\fR \fIz1\fR +Calculate the (principle value of the) logarithm for the given complex +argument and return the result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::sqrt\fR \fIz1\fR +Calculate the (principle value of the) square root for the given complex +argument and return the result +.RS +.TP +complex \fIz1\fR (in) +The complex argument for the function +.RE +.sp +.TP +\fB::math::complexnumbers::pow\fR \fIz1\fR \fIz2\fR +Calculate "z1 to the power of z2" and return the result +.RS +.TP +complex \fIz1\fR (in) +The complex number to be raised to a power +.TP +complex \fIz2\fR (in) +The complex power to be used +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: complexnumbers\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +complex numbers, math +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/rational_funcs.n Index: embedded/man/files/modules/math/rational_funcs.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/rational_funcs.n @@ -0,0 +1,447 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/rational_funcs.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::rationalfunctions" n 1.0.1 tcllib "Math" +.BS +.SH NAME +math::rationalfunctions \- Polynomial functions +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBmath::rationalfunctions ?1.0.1?\fR +.sp +\fB::math::rationalfunctions::rationalFunction\fR \fInum\fR \fIden\fR +.sp +\fB::math::rationalfunctions::ratioCmd\fR \fInum\fR \fIden\fR +.sp +\fB::math::rationalfunctions::evalRatio\fR \fIrational\fR \fIx\fR +.sp +\fB::math::rationalfunctions::addRatio\fR \fIratio1\fR \fIratio2\fR +.sp +\fB::math::rationalfunctions::subRatio\fR \fIratio1\fR \fIratio2\fR +.sp +\fB::math::rationalfunctions::multRatio\fR \fIratio1\fR \fIratio2\fR +.sp +\fB::math::rationalfunctions::divRatio\fR \fIratio1\fR \fIratio2\fR +.sp +\fB::math::rationalfunctions::derivPolyn\fR \fIratio\fR +.sp +\fB::math::rationalfunctions::coeffsNumerator\fR \fIratio\fR +.sp +\fB::math::rationalfunctions::coeffsDenominator\fR \fIratio\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package deals with rational functions of one variable: +.IP \(bu +the basic arithmetic operations are extended to rational functions +.IP \(bu +computing the derivatives of these functions +.IP \(bu +evaluation through a general procedure or via specific procedures) +.PP +.SH PROCEDURES +The package defines the following public procedures: +.TP +\fB::math::rationalfunctions::rationalFunction\fR \fInum\fR \fIden\fR +Return an (encoded) list that defines the rational function. A +rational function +.CS + + + 1 + x^3 + f(x) = ------------ + 1 + 2x + x^2 + +.CE +.IP +can be defined via: +.CS + + + set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1] [list 1 2 1]] + +.CE +.RS +.TP +list \fInum\fR +Coefficients of the numerator of the rational +function (in ascending order) +.sp +.TP +list \fIden\fR +Coefficients of the denominator of the rational +function (in ascending order) +.RE +.sp +.TP +\fB::math::rationalfunctions::ratioCmd\fR \fInum\fR \fIden\fR +Create a new procedure that evaluates the rational function. The name of the +function is automatically generated. Useful if you need to evaluate +the function many times, as the procedure consists of a single +[expr] command. +.RS +.TP +list \fInum\fR +Coefficients of the numerator of the rational +function (in ascending order) +.sp +.TP +list \fIden\fR +Coefficients of the denominator of the rational +function (in ascending order) +.RE +.sp +.TP +\fB::math::rationalfunctions::evalRatio\fR \fIrational\fR \fIx\fR +Evaluate the rational function at x. +.RS +.TP +list \fIrational\fR +The rational function's definition (as returned +by the rationalFunction command). +order) +.TP +float \fIx\fR +The coordinate at which to evaluate the function +.RE +.sp +.TP +\fB::math::rationalfunctions::addRatio\fR \fIratio1\fR \fIratio2\fR +Return a new rational function which is the sum of the two others. +.RS +.TP +list \fIratio1\fR +The first rational function operand +.TP +list \fIratio2\fR +The second rational function operand +.RE +.sp +.TP +\fB::math::rationalfunctions::subRatio\fR \fIratio1\fR \fIratio2\fR +Return a new rational function which is the difference of the two +others. +.RS +.TP +list \fIratio1\fR +The first rational function operand +.TP +list \fIratio2\fR +The second rational function operand +.RE +.sp +.TP +\fB::math::rationalfunctions::multRatio\fR \fIratio1\fR \fIratio2\fR +Return a new rational function which is the product of the two others. +If one of the arguments is a scalar value, the other rational function is +simply scaled. +.RS +.TP +list \fIratio1\fR +The first rational function operand or a scalar +.TP +list \fIratio2\fR +The second rational function operand or a scalar +.RE +.sp +.TP +\fB::math::rationalfunctions::divRatio\fR \fIratio1\fR \fIratio2\fR +Divide the first rational function by the second rational function and +return the result. The remainder is dropped +.RS +.TP +list \fIratio1\fR +The first rational function operand +.TP +list \fIratio2\fR +The second rational function operand +.RE +.sp +.TP +\fB::math::rationalfunctions::derivPolyn\fR \fIratio\fR +Differentiate the rational function and return the result. +.RS +.TP +list \fIratio\fR +The rational function to be differentiated +.RE +.sp +.TP +\fB::math::rationalfunctions::coeffsNumerator\fR \fIratio\fR +Return the coefficients of the numerator of the rational function. +.RS +.TP +list \fIratio\fR +The rational function to be examined +.RE +.sp +.TP +\fB::math::rationalfunctions::coeffsDenominator\fR \fIratio\fR +Return the coefficients of the denominator of the rational +function. +.RS +.TP +list \fIratio\fR +The rational function to be examined +.RE +.sp +.PP +.SH "REMARKS ON THE IMPLEMENTATION" +The implementation of the rational functions relies on the +math::polynomials package. For further remarks see the documentation on +that package. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: rationalfunctions\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +math, rational functions +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2005 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/roman.n Index: embedded/man/files/modules/math/roman.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/roman.n @@ -0,0 +1,306 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/roman.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Kenneth Green <kenneth.green@gmail.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::roman" 1.0 tcllib "Tcl Math Library" +.BS +.SH NAME +math::roman \- Tools for creating and manipulating roman numerals +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBmath::roman ?1.0?\fR +.sp +\fB::math::roman::toroman\fR \fIi\fR +.sp +\fB::math::roman::tointeger\fR \fIr\fR +.sp +\fB::math::roman::sort\fR \fIlist\fR +.sp +\fB::math::roman::expr\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +\fB::math::roman\fR is a pure-Tcl library for converting between integers +and roman numerals. It also provides utility functions for sorting and performing +arithmetic on roman numerals. +.PP +This code was originally harvested from the Tcler's wiki at +http://wiki.tcl.tk/1823 and as such is free for any use for +any purpose. Many thanks to the ingeneous folk who devised +these clever routines and generously contributed them to the +Tcl community. +.PP +While written and tested under Tcl 8.3, I expect this library +will work under all 8.x versions of Tcl. +.SH COMMANDS +.TP +\fB::math::roman::toroman\fR \fIi\fR +Convert an integer to roman numerals. The result is always in +upper case. The value zero is converted to an empty string. +.TP +\fB::math::roman::tointeger\fR \fIr\fR +Convert a roman numeral into an integer. +.TP +\fB::math::roman::sort\fR \fIlist\fR +Sort a list of roman numerals from smallest to largest. +.TP +\fB::math::roman::expr\fR \fIargs\fR +Evaluate an expression where the operands are all roman numerals. +.PP +Of these commands both \fItoroman\fR and \fItointeger\fR are exported +for easier use. The other two are not, as they could interfer or be +confused with existing Tcl commands. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: roman\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +conversion, integer, roman numeral +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2005 Kenneth Green <kenneth.green@gmail.com> + +.fi ADDED embedded/man/files/modules/math/romberg.n Index: embedded/man/files/modules/math/romberg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/romberg.n @@ -0,0 +1,552 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/romberg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::calculus::romberg" n 0.6 tcllib "Tcl Math Library" +.BS +.SH NAME +math::calculus::romberg \- Romberg integration +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmath::calculus 0.6\fR +.sp +\fB::math::calculus::romberg\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_infinity\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_sqrtSingLower\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_sqrtSingUpper\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_powerLawLower\fR \fIgamma\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_powerLawUpper\fR \fIgamma\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_expLower\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +\fB::math::calculus::romberg_expUpper\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBromberg\fR procedures in the \fBmath::calculus\fR package +perform numerical integration of a function of one variable. They +are intended to be of "production quality" in that they are robust, +precise, and reasonably efficient in terms of the number of function +evaluations. +.SH PROCEDURES +The following procedures are available for Romberg integration: +.TP +\fB::math::calculus::romberg\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates an analytic function over a given interval. +.TP +\fB::math::calculus::romberg_infinity\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates an analytic function over a half-infinite interval. +.TP +\fB::math::calculus::romberg_sqrtSingLower\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +lower limit. +.TP +\fB::math::calculus::romberg_sqrtSingUpper\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +upper limit. +.TP +\fB::math::calculus::romberg_powerLawLower\fR \fIgamma\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +lower limit. +.TP +\fB::math::calculus::romberg_powerLawUpper\fR \fIgamma\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +upper limit. +.TP +\fB::math::calculus::romberg_expLower\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates an exponentially growing function; the lower limit of the +region of integration may be arbitrarily large and negative. +.TP +\fB::math::calculus::romberg_expUpper\fR \fIf\fR \fIa\fR \fIb\fR ?\fI-option value\fR...? +Integrates an exponentially decaying function; the upper limit of the +region of integration may be arbitrarily large. +.PP +.SH PARAMETERS +.TP +\fIf\fR +Function to integrate. Must be expressed as a single Tcl command, +to which will be appended a single argument, specifically, the +abscissa at which the function is to be evaluated. The first word +of the command will be processed with \fBnamespace which\fR in the +caller's scope prior to any evaluation. Given this processing, the +command may local to the calling namespace rather than needing to be +global. +.TP +\fIa\fR +Lower limit of the region of integration. +.TP +\fIb\fR +Upper limit of the region of integration. For the +\fBromberg_sqrtSingLower\fR, \fBromberg_sqrtSingUpper\fR, +\fBromberg_powerLawLower\fR, \fBromberg_powerLawUpper\fR, +\fBromberg_expLower\fR, and \fBromberg_expUpper\fR procedures, +the lower limit must be strictly less than the upper. For +the other procedures, the limits may appear in either order. +.TP +\fIgamma\fR +Power to use for a power law singularity; see section +\fBIMPROPER INTEGRALS\fR for details. +.PP +.SH OPTIONS +.TP +\fB-abserror\fR \fIepsilon\fR +Requests that the integration machinery proceed at most until +the estimated absolute error of the integral is less than +\fIepsilon\fR. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section \fBIMPROPER INTEGRALS\fR for details. Default +is 1.0e-08. +.TP +\fB-relerror\fR \fIepsilon\fR +Requests that the integration machinery proceed at most until +the estimated relative error of the integral is less than +\fIepsilon\fR. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section \fBIMPROPER INTEGRALS\fR for details. Default is +1.0e-06. +.TP +\fB-maxiter\fR \fIm\fR +Requests that integration terminate after at most \fIn\fR triplings of +the number of evaluations performed. In other words, given \fIn\fR +for \fB-maxiter\fR, the integration machinery will make at most +3**\fIn\fR evaluations of the function. Default is 14, corresponding +to a limit approximately 4.8 million evaluations. (Well-behaved +functions will seldom require more than a few hundred evaluations.) +.TP +\fB-degree\fR \fId\fR +Requests that an extrapolating polynomial of degree \fId\fR be used +in Romberg integration; see section \fBDESCRIPTION\fR for +details. Default is 4. Can be at most \fIm\fR-1. +.PP +.SH DESCRIPTION +The \fBromberg\fR procedure performs Romberg integration using +the modified midpoint rule. Romberg integration is an iterative +process. At the first step, the function is evaluated at the +midpoint of the region of integration, and the value is multiplied by +the width of the interval for the coarsest possible estimate. +At the second step, the interval is divided into three parts, +and the function is evaluated at the midpoint of each part; the +sum of the values is multiplied by three. At the third step, +nine parts are used, at the fourth twenty-seven, and so on, +tripling the number of subdivisions at each step. +.PP +Once the interval has been divided at least \fId\fR times, +a polynomial is fitted to the integrals estimated in the last +\fId\fR+1 divisions. The integrals are considered to be a +function of the square of the width of the subintervals +(any good numerical analysis text will discuss this process +under "Romberg integration"). The polynomial is extrapolated +to a step size of zero, computing a value for the integral and +an estimate of the error. +.PP +This process will be well-behaved only if the function is analytic +over the region of integration; there may be removable singularities +at either end of the region provided that the limit of the function +(and of all its derivatives) exists as the ends are approached. +Thus, \fBromberg\fR may be used to integrate a function like +f(x)=sin(x)/x over an interval beginning or ending at zero. +.PP +Note that \fBromberg\fR will either fail to converge or else return +incorrect error estimates if the function, or any of its derivatives, +has a singularity anywhere in the region of integration (except for +the case mentioned above). Care must be used, therefore, in +integrating a function like 1/(1-x**2) to avoid the places +where the derivative is singular. +.SH "IMPROPER INTEGRALS" +Romberg integration is also useful for integrating functions over +half-infinite intervals or functions that have singularities. +The trick is to make a change of variable to eliminate the +singularity, and to put the singularity at one end or the other +of the region of integration. The \fBmath::calculus\fR package +supplies a number of \fBromberg\fR procedures to deal with the +commoner cases. +.TP +\fBromberg_infinity\fR +Integrates a function over a half-infinite interval; either +\fIa\fR or \fIb\fR may be infinite. \fIa\fR and \fIb\fR must be +of the same sign; if you need to integrate across the axis, +say, from a negative value to positive infinity, +use \fBromberg\fR to integrate from the negative +value to a small positive value, and then \fBromberg_infinity\fR +to integrate from the positive value to positive infinity. The +\fBromberg_infinity\fR procedure works by making the change of +variable u=1/x, so that the integral from a to b of f(x) is +evaluated as the integral from 1/a to 1/b of f(1/u)/u**2. +.TP +\fBromberg_powerLawLower\fR and \fBromberg_powerLawUpper\fR +Integrate a function that has an integrable power law singularity +at either the lower or upper bound of the region of integration +(or has a derivative with a power law singularity there). +These procedures take a first parameter, \fIgamma\fR, which gives +the power law. The function or its first derivative are presumed to diverge as +(x-\fIa\fR)**(-\fIgamma\fR) or (\fIb\fR-x)**(-\fIgamma\fR). \fIgamma\fR +must be greater than zero and less than 1. +.sp +These procedures are useful not only in integrating functions +that go to infinity at one end of the region of integration, but +also functions whose derivatives do not exist at the end of +the region. For instance, integrating f(x)=pow(x,0.25) with the +origin as one end of the region will result in the \fBromberg\fR +procedure greatly underestimating the error in the integral. +The problem can be fixed by observing that the first derivative +of f(x), f'(x)=x**(-3/4)/4, goes to infinity at the origin. Integrating +using \fBromberg_powerLawLower\fR with \fIgamma\fR set to 0.75 +gives much more orderly convergence. +.sp +These procedures operate by making the change of variable +u=(x-a)**(1-gamma) (\fBromberg_powerLawLower\fR) or +u=(b-x)**(1-gamma) (\fBromberg_powerLawUpper\fR). +.sp +To summarize the meaning of gamma: +.RS +.IP \(bu +If f(x) ~ x**(-a) (0 < a < 1), use gamma = a +.IP \(bu +If f'(x) ~ x**(-b) (0 < b < 1), use gamma = b +.RE +.TP +\fBromberg_sqrtSingLower\fR and \fBromberg_sqrtSingUpper\fR +These procedures behave identically to \fBromberg_powerLawLower\fR and +\fBromberg_powerLawUpper\fR for the common case of \fIgamma\fR=0.5; +that is, they integrate a function with an inverse square root +singularity at one end of the interval. They have a simpler +implementation involving square roots rather than arbitrary powers. +.TP +\fBromberg_expLower\fR and \fBromberg_expUpper\fR +These procedures are for integrating a function that grows or +decreases exponentially over a half-infinite interval. +\fBromberg_expLower\fR handles exponentially growing functions, and +allows the lower limit of integration to be an arbitrarily large +negative number. \fBromberg_expUpper\fR handles exponentially +decaying functions and allows the upper limit of integration to +be an arbitrary large positive number. The functions make the +change of variable u=exp(-x) and u=exp(x) respectively. +.PP +.SH "OTHER CHANGES OF VARIABLE" +If you need an improper integral other than the ones listed here, +a change of variable can be written in very few lines of Tcl. +Because the Tcl coding that does it is somewhat arcane, +we offer a worked example here. +.PP +Let's say that the function that we want to integrate is +f(x)=exp(x)/sqrt(1-x*x) (not a very natural +function, but a good example), and we want to integrate +it over the interval (-1,1). The denominator falls to zero +at both ends of the interval. We wish to make a change of variable +from x to u +so that dx/sqrt(1-x**2) maps to du. Choosing x=sin(u), we can +find that dx=cos(u)*du, and sqrt(1-x**2)=cos(u). The integral +from a to b of f(x) is the integral from asin(a) to asin(b) +of f(sin(u))*cos(u). +.PP +We can make a function \fBg\fR that accepts an arbitrary function +\fBf\fR and the parameter u, and computes this new integrand. +.CS + + +proc g { f u } { + set x [expr { sin($u) }] + set cmd $f; lappend cmd $x; set y [eval $cmd] + return [expr { $y / cos($u) }] +} + +.CE +Now integrating \fBf\fR from \fIa\fR to \fIb\fR is the same +as integrating \fBg\fR from \fIasin(a)\fR to \fIasin(b)\fR. +It's a little tricky to get \fBf\fR consistently evaluated in +the caller's scope; the following procedure does it. +.CS + + +proc romberg_sine { f a b args } { + set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]] + set f [list g $f] + return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]] +} + +.CE +This \fBromberg_sine\fR procedure will do any function with +sqrt(1-x*x) in the denominator. Our sample function is +f(x)=exp(x)/sqrt(1-x*x): +.CS + + +proc f { x } { + expr { exp($x) / sqrt( 1. - $x*$x ) } +} + +.CE +Integrating it is a matter of applying \fBromberg_sine\fR +as we would any of the other \fBromberg\fR procedures: +.CS + + +foreach { value error } [romberg_sine f -1.0 1.0] break +puts [format "integral is %.6g +/- %.6g" $value $error] + +integral is 3.97746 +/- 2.3557e-010 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: calculus\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +math::calculus, math::interpolate +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> + +.fi ADDED embedded/man/files/modules/math/special.n Index: embedded/man/files/modules/math/special.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/special.n @@ -0,0 +1,742 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/special.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::special" n 0.2 tcllib "Tcl Math Library" +.BS +.SH NAME +math::special \- Special mathematical functions +.SH SYNOPSIS +package require \fBTcl ?8.3?\fR +.sp +package require \fBmath::special ?0.2?\fR +.sp +\fB::math::special::Beta\fR \fIx\fR \fIy\fR +.sp +\fB::math::special::Gamma\fR \fIx\fR \fIy\fR +.sp +\fB::math::special::erf\fR \fIx\fR +.sp +\fB::math::special::erfc\fR \fIx\fR +.sp +\fB::math::special::J0\fR \fIx\fR +.sp +\fB::math::special::J1\fR \fIx\fR +.sp +\fB::math::special::Jn\fR \fIn\fR \fIx\fR +.sp +\fB::math::special::J1/2\fR \fIx\fR +.sp +\fB::math::special::J-1/2\fR \fIx\fR +.sp +\fB::math::special::I_n\fR \fIx\fR +.sp +\fB::math::special::cn\fR \fIu\fR \fIk\fR +.sp +\fB::math::special::dn\fR \fIu\fR \fIk\fR +.sp +\fB::math::special::sn\fR \fIu\fR \fIk\fR +.sp +\fB::math::special::elliptic_K\fR \fIk\fR +.sp +\fB::math::special::elliptic_E\fR \fIk\fR +.sp +\fB::math::special::exponential_Ei\fR \fIx\fR +.sp +\fB::math::special::exponential_En\fR \fIn\fR \fIx\fR +.sp +\fB::math::special::exponential_li\fR \fIx\fR +.sp +\fB::math::special::exponential_Ci\fR \fIx\fR +.sp +\fB::math::special::exponential_Si\fR \fIx\fR +.sp +\fB::math::special::exponential_Chi\fR \fIx\fR +.sp +\fB::math::special::exponential_Shi\fR \fIx\fR +.sp +\fB::math::special::fresnel_C\fR \fIx\fR +.sp +\fB::math::special::fresnel_S\fR \fIx\fR +.sp +\fB::math::special::sinc\fR \fIx\fR +.sp +\fB::math::special::legendre\fR \fIn\fR +.sp +\fB::math::special::chebyshev\fR \fIn\fR +.sp +\fB::math::special::laguerre\fR \fIalpha\fR \fIn\fR +.sp +\fB::math::special::hermite\fR \fIn\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package implements several so-called special functions, like +the Gamma function, the Bessel functions and such. +.PP +Each function is implemented by a procedure that bears its name (well, +in close approximation): +.IP \(bu +J0 for the zeroth-order Bessel function of the first kind +.IP \(bu +J1 for the first-order Bessel function of the first kind +.IP \(bu +Jn for the nth-order Bessel function of the first kind +.IP \(bu +J1/2 for the half-order Bessel function of the first kind +.IP \(bu +J-1/2 for the minus-half-order Bessel function of the first kind +.IP \(bu +I_n for the modified Bessel function of the first kind of order n +.IP \(bu +Gamma for the Gamma function, erf and erfc for the error function and +the complementary error function +.IP \(bu +fresnel_C and fresnel_S for the Fresnel integrals +.IP \(bu +elliptic_K and elliptic_E (complete elliptic integrals) +.IP \(bu +exponent_Ei and other functions related to the so-called exponential +integrals +.IP \(bu +legendre, hermite: some of the classical orthogonal polynomials. +.PP +.SH OVERVIEW +In the following table several characteristics of the functions in this +package are summarized: the domain for the argument, the values for the +parameters and error bounds. +.CS + + +Family | Function | Domain x | Parameter | Error bound +-------------+-------------+-------------+-------------+-------------- +Bessel | J0, J1, | all of R | n = integer | < 1.0e-8 + | Jn | | | (|x|<20, n<20) +Bessel | J1/2, J-1/2,| x > 0 | n = integer | exact +Bessel | I_n | all of R | n = integer | < 1.0e-6 + | | | | +Elliptic | cn | 0 <= x <= 1 | -- | < 1.0e-10 +functions | dn | 0 <= x <= 1 | -- | < 1.0e-10 + | sn | 0 <= x <= 1 | -- | < 1.0e-10 +Elliptic | K | 0 <= x < 1 | -- | < 1.0e-6 +integrals | E | 0 <= x < 1 | -- | < 1.0e-6 + | | | | +Error | erf | | -- | +functions | erfc | | | + | ierfc_n | | | + | | | | +Exponential | Ei | x != 0 | -- | < 1.0e-10 (relative) +integrals | En | x > 0 | -- | as Ei + | li | x > 0 | -- | as Ei + | Chi | x > 0 | -- | < 1.0e-8 + | Shi | x > 0 | -- | < 1.0e-8 + | Ci | x > 0 | -- | < 2.0e-4 + | Si | x > 0 | -- | < 2.0e-4 + | | | | +Fresnel | C | all of R | -- | < 2.0e-3 +integrals | S | all of R | -- | < 2.0e-3 + | | | | +general | Beta | (see Gamma) | -- | < 1.0e-9 + | Gamma | x != 0,-1, | -- | < 1.0e-9 + | | -2, ... | | + | sinc | all of R | -- | exact + | | | | +orthogonal | Legendre | all of R | n = 0,1,... | exact +polynomials | Chebyshev | all of R | n = 0,1,... | exact + | Laguerre | all of R | n = 0,1,... | exact + | | | alpha el. R | + | Hermite | all of R | n = 0,1,... | exact + +.CE +\fINote:\fR Some of the error bounds are estimated, as no +"formal" bounds were available with the implemented approximation +method, others hold for the auxiliary functions used for estimating +the primary functions. +.PP +The following well-known functions are currently missing from the package: +.IP \(bu +Bessel functions of the second kind (Y_n, K_n) +.IP \(bu +Bessel functions of arbitrary order (and hence the Airy functions) +.IP \(bu +Chebyshev polynomials of the second kind (U_n) +.IP \(bu +The digamma function (psi) +.IP \(bu +The incomplete gamma and beta functions +.PP +.SH PROCEDURES +The package defines the following public procedures: +.TP +\fB::math::special::Beta\fR \fIx\fR \fIy\fR +Compute the Beta function for arguments "x" and "y" +.RS +.TP +float \fIx\fR +First argument for the Beta function +.TP +float \fIy\fR +Second argument for the Beta function +.RE +.sp +.TP +\fB::math::special::Gamma\fR \fIx\fR \fIy\fR +Compute the Gamma function for argument "x" +.RS +.TP +float \fIx\fR +Argument for the Gamma function +.RE +.sp +.TP +\fB::math::special::erf\fR \fIx\fR +Compute the error function for argument "x" +.RS +.TP +float \fIx\fR +Argument for the error function +.RE +.sp +.TP +\fB::math::special::erfc\fR \fIx\fR +Compute the complementary error function for argument "x" +.RS +.TP +float \fIx\fR +Argument for the complementary error function +.RE +.sp +.TP +\fB::math::special::J0\fR \fIx\fR +Compute the zeroth-order Bessel function of the first kind for the +argument "x" +.RS +.TP +float \fIx\fR +Argument for the Bessel function +.RE +.TP +\fB::math::special::J1\fR \fIx\fR +Compute the first-order Bessel function of the first kind for the +argument "x" +.RS +.TP +float \fIx\fR +Argument for the Bessel function +.RE +.TP +\fB::math::special::Jn\fR \fIn\fR \fIx\fR +Compute the nth-order Bessel function of the first kind for the +argument "x" +.RS +.TP +integer \fIn\fR +Order of the Bessel function +.TP +float \fIx\fR +Argument for the Bessel function +.RE +.TP +\fB::math::special::J1/2\fR \fIx\fR +Compute the half-order Bessel function of the first kind for the +argument "x" +.RS +.TP +float \fIx\fR +Argument for the Bessel function +.RE +.TP +\fB::math::special::J-1/2\fR \fIx\fR +Compute the minus-half-order Bessel function of the first kind for the +argument "x" +.RS +.TP +float \fIx\fR +Argument for the Bessel function +.RE +.TP +\fB::math::special::I_n\fR \fIx\fR +Compute the modified Bessel function of the first kind of order n for +the argument "x" +.RS +.TP +int \fIx\fR +Positive integer order of the function +.TP +float \fIx\fR +Argument for the function +.RE +.TP +\fB::math::special::cn\fR \fIu\fR \fIk\fR +Compute the elliptic function \fIcn\fR for the argument "u" and +parameter "k". +.RS +.TP +float \fIu\fR +Argument for the function +.TP +float \fIk\fR +Parameter +.RE +.TP +\fB::math::special::dn\fR \fIu\fR \fIk\fR +Compute the elliptic function \fIdn\fR for the argument "u" and +parameter "k". +.RS +.TP +float \fIu\fR +Argument for the function +.TP +float \fIk\fR +Parameter +.RE +.TP +\fB::math::special::sn\fR \fIu\fR \fIk\fR +Compute the elliptic function \fIsn\fR for the argument "u" and +parameter "k". +.RS +.TP +float \fIu\fR +Argument for the function +.TP +float \fIk\fR +Parameter +.RE +.TP +\fB::math::special::elliptic_K\fR \fIk\fR +Compute the complete elliptic integral of the first kind +for the argument "k" +.RS +.TP +float \fIk\fR +Argument for the function +.RE +.TP +\fB::math::special::elliptic_E\fR \fIk\fR +Compute the complete elliptic integral of the second kind +for the argument "k" +.RS +.TP +float \fIk\fR +Argument for the function +.RE +.TP +\fB::math::special::exponential_Ei\fR \fIx\fR +Compute the exponential integral of the second kind +for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x != 0) +.RE +.TP +\fB::math::special::exponential_En\fR \fIn\fR \fIx\fR +Compute the exponential integral of the first kind +for the argument "x" and order n +.RS +.TP +int \fIn\fR +Order of the integral (n >= 0) +.TP +float \fIx\fR +Argument for the function (x >= 0) +.RE +.TP +\fB::math::special::exponential_li\fR \fIx\fR +Compute the logarithmic integral for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x > 0) +.RE +.TP +\fB::math::special::exponential_Ci\fR \fIx\fR +Compute the cosine integral for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x > 0) +.RE +.TP +\fB::math::special::exponential_Si\fR \fIx\fR +Compute the sine integral for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x > 0) +.RE +.TP +\fB::math::special::exponential_Chi\fR \fIx\fR +Compute the hyperbolic cosine integral for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x > 0) +.RE +.TP +\fB::math::special::exponential_Shi\fR \fIx\fR +Compute the hyperbolic sine integral for the argument "x" +.RS +.TP +float \fIx\fR +Argument for the function (x > 0) +.RE +.TP +\fB::math::special::fresnel_C\fR \fIx\fR +Compute the Fresnel cosine integral for real argument x +.RS +.TP +float \fIx\fR +Argument for the function +.RE +.TP +\fB::math::special::fresnel_S\fR \fIx\fR +Compute the Fresnel sine integral for real argument x +.RS +.TP +float \fIx\fR +Argument for the function +.RE +.TP +\fB::math::special::sinc\fR \fIx\fR +Compute the sinc function for real argument x +.RS +.TP +float \fIx\fR +Argument for the function +.RE +.TP +\fB::math::special::legendre\fR \fIn\fR +Return the Legendre polynomial of degree n +(see \fBTHE ORTHOGONAL POLYNOMIALS\fR) +.RS +.TP +int \fIn\fR +Degree of the polynomial +.RE +.sp +.TP +\fB::math::special::chebyshev\fR \fIn\fR +Return the Chebyshev polynomial of degree n (of the first kind) +.RS +.TP +int \fIn\fR +Degree of the polynomial +.RE +.sp +.TP +\fB::math::special::laguerre\fR \fIalpha\fR \fIn\fR +Return the Laguerre polynomial of degree n with parameter alpha +.RS +.TP +float \fIalpha\fR +Parameter of the Laguerre polynomial +.TP +int \fIn\fR +Degree of the polynomial +.RE +.sp +.TP +\fB::math::special::hermite\fR \fIn\fR +Return the Hermite polynomial of degree n +.RS +.TP +int \fIn\fR +Degree of the polynomial +.RE +.sp +.PP +.SH "THE ORTHOGONAL POLYNOMIALS" +For dealing with the classical families of orthogonal polynomials, the +package relies on the \fImath::polynomials\fR package. To evaluate the +polynomial at some coordinate, use the \fIevalPolyn\fR command: +.CS + + + set leg2 [::math::special::legendre 2] + puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]" + +.CE +.PP +The return value from the \fIlegendre\fR and other commands is actually +the definition of the corresponding polynomial as used in that package. +.SH "REMARKS ON THE IMPLEMENTATION" +It should be noted, that the actual implementation of J0 and J1 depends +on straightforward Gaussian quadrature formulas. The (absolute) accuracy +of the results is of the order 1.0e-4 or better. The main reason to +implement them like that was that it was fast to do (the formulas are +simple) and the computations are fast too. +.PP +The implementation of J1/2 does not suffer from this: this function can +be expressed exactly in terms of elementary functions. +.PP +The functions J0 and J1 are the ones you will encounter most frequently +in practice. +.PP +The computation of I_n is based on Miller's algorithm for computing the +minimal function from recurrence relations. +.PP +The computation of the Gamma and Beta functions relies on the +combinatorics package, whereas that of the error functions relies on the +statistics package. +.PP +The computation of the complete elliptic integrals uses the AGM +algorithm. +.PP +Much information about these functions can be found in: +.PP +Abramowitz and Stegun: \fIHandbook of Mathematical Functions\fR +(Dover, ISBN 486-61272-4) +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: special\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +Bessel functions, error function, math, special functions +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/math/statistics.n Index: embedded/man/files/modules/math/statistics.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/statistics.n @@ -0,0 +1,1863 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/statistics.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::statistics" n 0.8 tcllib "Tcl Math Library" +.BS +.SH NAME +math::statistics \- Basic statistical functions and procedures +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBmath::statistics 0.8\fR +.sp +\fB::math::statistics::mean\fR \fIdata\fR +.sp +\fB::math::statistics::min\fR \fIdata\fR +.sp +\fB::math::statistics::max\fR \fIdata\fR +.sp +\fB::math::statistics::number\fR \fIdata\fR +.sp +\fB::math::statistics::stdev\fR \fIdata\fR +.sp +\fB::math::statistics::var\fR \fIdata\fR +.sp +\fB::math::statistics::pstdev\fR \fIdata\fR +.sp +\fB::math::statistics::pvar\fR \fIdata\fR +.sp +\fB::math::statistics::median\fR \fIdata\fR +.sp +\fB::math::statistics::basic-stats\fR \fIdata\fR +.sp +\fB::math::statistics::histogram\fR \fIlimits\fR \fIvalues\fR +.sp +\fB::math::statistics::corr\fR \fIdata1\fR \fIdata2\fR +.sp +\fB::math::statistics::interval-mean-stdev\fR \fIdata\fR \fIconfidence\fR +.sp +\fB::math::statistics::t-test-mean\fR \fIdata\fR \fIest_mean\fR \fIest_stdev\fR \fIconfidence\fR +.sp +\fB::math::statistics::test-normal\fR \fIdata\fR \fIconfidence\fR +.sp +\fB::math::statistics::lillieforsFit\fR \fIdata\fR +.sp +\fB::math::statistics::quantiles\fR \fIdata\fR \fIconfidence\fR +.sp +\fB::math::statistics::quantiles\fR \fIlimits\fR \fIcounts\fR \fIconfidence\fR +.sp +\fB::math::statistics::autocorr\fR \fIdata\fR +.sp +\fB::math::statistics::crosscorr\fR \fIdata1\fR \fIdata2\fR +.sp +\fB::math::statistics::mean-histogram-limits\fR \fImean\fR \fIstdev\fR \fInumber\fR +.sp +\fB::math::statistics::minmax-histogram-limits\fR \fImin\fR \fImax\fR \fInumber\fR +.sp +\fB::math::statistics::linear-model\fR \fIxdata\fR \fIydata\fR \fIintercept\fR +.sp +\fB::math::statistics::linear-residuals\fR \fIxdata\fR \fIydata\fR \fIintercept\fR +.sp +\fB::math::statistics::test-2x2\fR \fIn11\fR \fIn21\fR \fIn12\fR \fIn22\fR +.sp +\fB::math::statistics::print-2x2\fR \fIn11\fR \fIn21\fR \fIn12\fR \fIn22\fR +.sp +\fB::math::statistics::control-xbar\fR \fIdata\fR ?nsamples? +.sp +\fB::math::statistics::control-Rchart\fR \fIdata\fR ?nsamples? +.sp +\fB::math::statistics::test-xbar\fR \fIcontrol\fR \fIdata\fR +.sp +\fB::math::statistics::test-Rchart\fR \fIcontrol\fR \fIdata\fR +.sp +\fB::math::statistics::tstat\fR \fIdof\fR ?alpha? +.sp +\fB::math::statistics::mv-wls\fR \fIwt1\fR \fIweights_and_values\fR +.sp +\fB::math::statistics::mv-ols\fR \fIvalues\fR +.sp +\fB::math::statistics::pdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-exponential\fR \fImean\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-poisson\fR \fImu\fR \fIk\fR +.sp +\fB::math::statistics::pdf-chisquare\fR \fIdf\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-student-t\fR \fIdf\fR \fIvalue\fR +.sp +\fB::math::statistics::pdf-beta\fR \fIa\fR \fIb\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-exponential\fR \fImean\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-students-t\fR \fIdegrees\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR +.sp +\fB::math::statistics::cdf-poisson\fR \fImu\fR \fIk\fR +.sp +\fB::math::statistics::cdf-beta\fR \fIa\fR \fIb\fR \fIvalue\fR +.sp +\fB::math::statistics::random-normal\fR \fImean\fR \fIstdev\fR \fInumber\fR +.sp +\fB::math::statistics::random-exponential\fR \fImean\fR \fInumber\fR +.sp +\fB::math::statistics::random-uniform\fR \fIxmin\fR \fIxmax\fR \fInumber\fR +.sp +\fB::math::statistics::random-gamma\fR \fIalpha\fR \fIbeta\fR \fInumber\fR +.sp +\fB::math::statistics::random-chisquare\fR \fIdf\fR \fInumber\fR +.sp +\fB::math::statistics::random-student-t\fR \fIdf\fR \fInumber\fR +.sp +\fB::math::statistics::random-beta\fR \fIa\fR \fIb\fR \fInumber\fR +.sp +\fB::math::statistics::histogram-uniform\fR \fIxmin\fR \fIxmax\fR \fIlimits\fR \fInumber\fR +.sp +\fB::math::statistics::incompleteGamma\fR \fIx\fR \fIp\fR ?tol? +.sp +\fB::math::statistics::incompleteBeta\fR \fIa\fR \fIb\fR \fIx\fR ?tol? +.sp +\fB::math::statistics::filter\fR \fIvarname\fR \fIdata\fR \fIexpression\fR +.sp +\fB::math::statistics::map\fR \fIvarname\fR \fIdata\fR \fIexpression\fR +.sp +\fB::math::statistics::samplescount\fR \fIvarname\fR \fIlist\fR \fIexpression\fR +.sp +\fB::math::statistics::subdivide\fR +.sp +\fB::math::statistics::test-Kruskal-Wallis\fR \fIconfidence\fR \fIargs\fR +.sp +\fB::math::statistics::analyse-Kruskal-Wallis\fR \fIargs\fR +.sp +\fB::math::statistics::group-rank\fR \fIargs\fR +.sp +\fB::math::statistics::test-Wilcoxon\fR \fIsample_a\fR \fIsample_b\fR +.sp +\fB::math::statistics::spearman-rank\fR \fIsample_a\fR \fIsample_b\fR +.sp +\fB::math::statistics::spearman-rank-extended\fR \fIsample_a\fR \fIsample_b\fR +.sp +\fB::math::statistics::plot-scale\fR \fIcanvas\fR \fIxmin\fR \fIxmax\fR \fIymin\fR \fIymax\fR +.sp +\fB::math::statistics::plot-xydata\fR \fIcanvas\fR \fIxdata\fR \fIydata\fR \fItag\fR +.sp +\fB::math::statistics::plot-xyline\fR \fIcanvas\fR \fIxdata\fR \fIydata\fR \fItag\fR +.sp +\fB::math::statistics::plot-tdata\fR \fIcanvas\fR \fItdata\fR \fItag\fR +.sp +\fB::math::statistics::plot-tline\fR \fIcanvas\fR \fItdata\fR \fItag\fR +.sp +\fB::math::statistics::plot-histogram\fR \fIcanvas\fR \fIcounts\fR \fIlimits\fR \fItag\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath::statistics\fR package contains functions and procedures for +basic statistical data analysis, such as: +.IP \(bu +Descriptive statistical parameters (mean, minimum, maximum, standard +deviation) +.IP \(bu +Estimates of the distribution in the form of histograms and quantiles +.IP \(bu +Basic testing of hypotheses +.IP \(bu +Probability and cumulative density functions +.PP +It is meant to help in developing data analysis applications or doing +ad hoc data analysis, it is not in itself a full application, nor is it +intended to rival with full (non-)commercial statistical packages. +.PP +The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. +The package contains a fairly large number of public procedures. They +can be distinguished in three sets: general procedures, procedures +that deal with specific statistical distributions, list procedures to +select or transform data and simple plotting procedures (these require +Tk). +\fINote:\fR The data that need to be analyzed are always contained in a +simple list. Missing values are represented as empty list elements. +.SH "GENERAL PROCEDURES" +The general statistical procedures are: +.TP +\fB::math::statistics::mean\fR \fIdata\fR +Determine the \fImean\fR value of the given list of data. +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::min\fR \fIdata\fR +Determine the \fIminimum\fR value of the given list of data. +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::max\fR \fIdata\fR +Determine the \fImaximum\fR value of the given list of data. +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::number\fR \fIdata\fR +Determine the \fInumber\fR of non-missing data in the given list +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::stdev\fR \fIdata\fR +Determine the \fIsample standard deviation\fR of the data in the +given list +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::var\fR \fIdata\fR +Determine the \fIsample variance\fR of the data in the given list +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::pstdev\fR \fIdata\fR +Determine the \fIpopulation standard deviation\fR of the data +in the given list +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::pvar\fR \fIdata\fR +Determine the \fIpopulation variance\fR of the data in the +given list +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::median\fR \fIdata\fR +Determine the \fImedian\fR of the data in the given list +(Note that this requires sorting the data, which may be a +costly operation) +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::basic-stats\fR \fIdata\fR +Determine a list of all the descriptive parameters: mean, minimum, +maximum, number of data, sample standard deviation, sample variance, +population standard deviation and population variance. +.sp +(This routine is called whenever either or all of the basic statistical +parameters are required. Hence all calculations are done and the +relevant values are returned.) +.RS +.TP +list \fIdata\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::histogram\fR \fIlimits\fR \fIvalues\fR +Determine histogram information for the given list of data. Returns a +list consisting of the number of values that fall into each interval. +(The first interval consists of all values lower than the first limit, +the last interval consists of all values greater than the last limit. +There is one more interval than there are limits.) +.RS +.TP +list \fIlimits\fR +- List of upper limits (in ascending order) for the +intervals of the histogram. +.TP +list \fIvalues\fR +- List of data +.RE +.sp +.TP +\fB::math::statistics::corr\fR \fIdata1\fR \fIdata2\fR +Determine the correlation coefficient between two sets of data. +.RS +.TP +list \fIdata1\fR +- First list of data +.TP +list \fIdata2\fR +- Second list of data +.RE +.sp +.TP +\fB::math::statistics::interval-mean-stdev\fR \fIdata\fR \fIconfidence\fR +Return the interval containing the mean value and one +containing the standard deviation with a certain +level of confidence (assuming a normal distribution) +.RS +.TP +list \fIdata\fR +- List of raw data values (small sample) +.TP +float \fIconfidence\fR +- Confidence level (0.95 or 0.99 for instance) +.RE +.sp +.TP +\fB::math::statistics::t-test-mean\fR \fIdata\fR \fIest_mean\fR \fIest_stdev\fR \fIconfidence\fR +Test whether the mean value of a sample is in accordance with the +estimated normal distribution with a certain level of confidence. +Returns 1 if the test succeeds or 0 if the mean is unlikely to fit +the given distribution. +.RS +.TP +list \fIdata\fR +- List of raw data values (small sample) +.TP +float \fIest_mean\fR +- Estimated mean of the distribution +.TP +float \fIest_stdev\fR +- Estimated stdev of the distribution +.TP +float \fIconfidence\fR +- Confidence level (0.95 or 0.99 for instance) +.RE +.sp +.TP +\fB::math::statistics::test-normal\fR \fIdata\fR \fIconfidence\fR +Test whether the given data follow a normal distribution +with a certain level of confidence. +Returns 1 if the data are normally distributed within the level of +confidence, returns 0 if not. The underlying test is the Lilliefors +test. +.RS +.TP +list \fIdata\fR +- List of raw data values +.TP +float \fIconfidence\fR +- Confidence level (one of 0.80, 0.90, 0.95 or 0.99) +.RE +.sp +.TP +\fB::math::statistics::lillieforsFit\fR \fIdata\fR +Returns the goodness of fit to a normal distribution according to +Lilliefors. The higher the number, the more likely the data are indeed +normally distributed. The test requires at least \fIfive\fR data +points. +.RS +.TP +list \fIdata\fR +- List of raw data values +.RE +.sp +.TP +\fB::math::statistics::quantiles\fR \fIdata\fR \fIconfidence\fR +Return the quantiles for a given set of data +.RS +.sp +.TP +list \fIdata\fR +- List of raw data values +.sp +.TP +float \fIconfidence\fR +- Confidence level (0.95 or 0.99 for instance) +.sp +.RE +.sp +.TP +\fB::math::statistics::quantiles\fR \fIlimits\fR \fIcounts\fR \fIconfidence\fR +Return the quantiles based on histogram information (alternative to the +call with two arguments) +.RS +.TP +list \fIlimits\fR +- List of upper limits from histogram +.TP +list \fIcounts\fR +- List of counts for for each interval in histogram +.TP +float \fIconfidence\fR +- Confidence level (0.95 or 0.99 for instance) +.RE +.sp +.TP +\fB::math::statistics::autocorr\fR \fIdata\fR +Return the autocorrelation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data) +.sp +The correlation is determined in such a way that the first value is +always 1 and all others are equal to or smaller than 1. The number of +values involved will diminish as the "time" (the index in the list of +returned values) increases +.RS +.TP +list \fIdata\fR +- Raw data for which the autocorrelation must be determined +.RE +.sp +.TP +\fB::math::statistics::crosscorr\fR \fIdata1\fR \fIdata2\fR +Return the cross-correlation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data) +.sp +The correlation is determined in such a way that the values can never +exceed 1 in magnitude. The number of values involved will diminish +as the "time" (the index in the list of returned values) increases. +.RS +.TP +list \fIdata1\fR +- First list of data +.TP +list \fIdata2\fR +- Second list of data +.RE +.sp +.TP +\fB::math::statistics::mean-histogram-limits\fR \fImean\fR \fIstdev\fR \fInumber\fR +Determine reasonable limits based on mean and standard deviation +for a histogram +Convenience function - the result is suitable for the histogram function. +.RS +.TP +float \fImean\fR +- Mean of the data +.TP +float \fIstdev\fR +- Standard deviation +.TP +int \fInumber\fR +- Number of limits to generate (defaults to 8) +.RE +.sp +.TP +\fB::math::statistics::minmax-histogram-limits\fR \fImin\fR \fImax\fR \fInumber\fR +Determine reasonable limits based on a minimum and maximum for a histogram +.sp +Convenience function - the result is suitable for the histogram function. +.RS +.TP +float \fImin\fR +- Expected minimum +.TP +float \fImax\fR +- Expected maximum +.TP +int \fInumber\fR +- Number of limits to generate (defaults to 8) +.RE +.sp +.TP +\fB::math::statistics::linear-model\fR \fIxdata\fR \fIydata\fR \fIintercept\fR +Determine the coefficients for a linear regression between +two series of data (the model: Y = A + B*X). Returns a list of +parameters describing the fit +.RS +.TP +list \fIxdata\fR +- List of independent data +.TP +list \fIydata\fR +- List of dependent data to be fitted +.TP +boolean \fIintercept\fR +- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0) +.sp +The result consists of the following list: +.RS +.IP \(bu +(Estimate of) Intercept A +.IP \(bu +(Estimate of) Slope B +.IP \(bu +Standard deviation of Y relative to fit +.IP \(bu +Correlation coefficient R2 +.IP \(bu +Number of degrees of freedom df +.IP \(bu +Standard error of the intercept A +.IP \(bu +Significance level of A +.IP \(bu +Standard error of the slope B +.IP \(bu +Significance level of B +.RE +.RE +.sp +.TP +\fB::math::statistics::linear-residuals\fR \fIxdata\fR \fIydata\fR \fIintercept\fR +Determine the difference between actual data and predicted from +the linear model. +.sp +Returns a list of the differences between the actual data and the +predicted values. +.RS +.TP +list \fIxdata\fR +- List of independent data +.TP +list \fIydata\fR +- List of dependent data to be fitted +.TP +boolean \fIintercept\fR +- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0) +.RE +.sp +.TP +\fB::math::statistics::test-2x2\fR \fIn11\fR \fIn21\fR \fIn12\fR \fIn22\fR +Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter). +.sp +Returns the "chi-square" value, which can be used to the determine the +significance. +.RS +.TP +int \fIn11\fR +- Number of outcomes with the first value from the first sample. +.TP +int \fIn21\fR +- Number of outcomes with the first value from the second sample. +.TP +int \fIn12\fR +- Number of outcomes with the second value from the first sample. +.TP +int \fIn22\fR +- Number of outcomes with the second value from the second sample. +.RE +.sp +.TP +\fB::math::statistics::print-2x2\fR \fIn11\fR \fIn21\fR \fIn12\fR \fIn22\fR +Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter). +.sp +Returns a short report, useful in an interactive session. +.RS +.TP +int \fIn11\fR +- Number of outcomes with the first value from the first sample. +.TP +int \fIn21\fR +- Number of outcomes with the first value from the second sample. +.TP +int \fIn12\fR +- Number of outcomes with the second value from the first sample. +.TP +int \fIn22\fR +- Number of outcomes with the second value from the second sample. +.RE +.sp +.TP +\fB::math::statistics::control-xbar\fR \fIdata\fR ?nsamples? +Determine the control limits for an xbar chart. The number of data +in each subsample defaults to 4. At least 20 subsamples are required. +.sp +Returns the mean, the lower limit, the upper limit and the number of +data per subsample. +.RS +.TP +list \fIdata\fR +- List of observed data +.TP +int \fInsamples\fR +- Number of data per subsample +.RE +.sp +.TP +\fB::math::statistics::control-Rchart\fR \fIdata\fR ?nsamples? +Determine the control limits for an R chart. The number of data +in each subsample (nsamples) defaults to 4. At least 20 subsamples are required. +.sp +Returns the mean range, the lower limit, the upper limit and the number +of data per subsample. +.RS +.TP +list \fIdata\fR +- List of observed data +.TP +int \fInsamples\fR +- Number of data per subsample +.RE +.sp +.TP +\fB::math::statistics::test-xbar\fR \fIcontrol\fR \fIdata\fR +Determine if the data exceed the control limits for the xbar chart. +.sp +Returns a list of subsamples (their indices) that indeed violate the +limits. +.RS +.TP +list \fIcontrol\fR +- Control limits as returned by the "control-xbar" procedure +.TP +list \fIdata\fR +- List of observed data +.RE +.sp +.TP +\fB::math::statistics::test-Rchart\fR \fIcontrol\fR \fIdata\fR +Determine if the data exceed the control limits for the R chart. +.sp +Returns a list of subsamples (their indices) that indeed violate the +limits. +.RS +.TP +list \fIcontrol\fR +- Control limits as returned by the "control-Rchart" procedure +.TP +list \fIdata\fR +- List of observed data +.RE +.sp +.PP +.SH "MULTIVARIATE LINEAR REGRESSION" +Besides the linear regression with a single independent variable, the +statistics package provides two procedures for doing ordinary +least squares (OLS) and weighted least squares (WLS) linear regression +with several variables. They were written by Eric Kemp-Benedict. +.PP +In addition to these two, it provides a procedure (tstat) +for calculating the value of the t-statistic for the specified number of +degrees of freedom that is required to demonstrate a given level of +significance. +.PP +Note: These procedures depend on the math::linearalgebra package. +.PP +\fIDescription of the procedures\fR +.TP +\fB::math::statistics::tstat\fR \fIdof\fR ?alpha? +Returns the value of the t-distribution t* satisfying +.CS + + + P(t*) = 1 - alpha/2 + P(-t*) = alpha/2 + +.CE +.IP +for the number of degrees of freedom dof. +.sp +Given a sample of normally-distributed data x, with an +estimate xbar for the mean and sbar for the standard deviation, +the alpha confidence interval for the estimate of the mean can +be calculated as +.CS + + + ( xbar - t* sbar , xbar + t* sbar) + +.CE +.IP +The return values from this procedure can be compared to +an estimated t-statistic to determine whether the estimated +value of a parameter is significantly different from zero at +the given confidence level. +.RS +.TP +int \fIdof\fR +Number of degrees of freedom +.TP +float \fIalpha\fR +Confidence level of the t-distribution. Defaults to 0.05. +.RE +.sp +.TP +\fB::math::statistics::mv-wls\fR \fIwt1\fR \fIweights_and_values\fR +Carries out a weighted least squares linear regression for +the data points provided, with weights assigned to each point. +.sp +The linear model is of the form +.CS + + + y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error + +.CE +.IP +and each point satisfies +.CS + + + yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i + +.CE +.sp +The procedure returns a list with the following elements: +.RS +.IP \(bu +The r-squared statistic +.IP \(bu +The adjusted r-squared statistic +.IP \(bu +A list containing the estimated coefficients b1, ... bN, b0 +(The constant b0 comes last in the list.) +.IP \(bu +A list containing the standard errors of the coefficients +.IP \(bu +A list containing the 95% confidence bounds of the coefficients, +with each set of bounds returned as a list with two values +.RE +.IP +Arguments: +.RS +.TP +list \fIweights_and_values\fR +A list consisting of: the weight for the first observation, the data +for the first observation (as a sublist), the weight for the second +observation (as a sublist) and so on. The sublists of data are organised +as lists of the value of the dependent variable y and the independent +variables x1, x2 to xN. +.RE +.sp +.TP +\fB::math::statistics::mv-ols\fR \fIvalues\fR +Carries out an ordinary least squares linear regression for +the data points provided. +.sp +This procedure simply calls ::mvlinreg::wls with the weights +set to 1.0, and returns the same information. +.PP +\fIExample of the use:\fR +.CS + + +# Store the value of the unicode value for the "+/-" character +set pm "\\u00B1" + +# Provide some data +set data {{ -.67 14.18 60.03 -7.5 } + { 36.97 15.52 34.24 14.61 } + {-29.57 21.85 83.36 -7. } + {-16.9 11.79 51.67 -6.56 } + { 14.09 16.24 36.97 -12.84} + { 31.52 20.93 45.99 -25.4 } + { 24.05 20.69 50.27 17.27} + { 22.23 16.91 45.07 -4.3 } + { 40.79 20.49 38.92 -.73 } + {-10.35 17.24 58.77 18.78}} + +# Call the ols routine +set results [::math::statistics::mv-ols $data] + +# Pretty-print the results +puts "R-squared: [lindex $results 0]" +puts "Adj R-squared: [lindex $results 1]" +puts "Coefficients $pm s.e. -- \\[95% confidence interval\\]:" +foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] { + set lb [lindex $bounds 0] + set ub [lindex $bounds 1] + puts " $val $pm $se -- \\[$lb to $ub\\]" +} + +.CE +.SH "STATISTICAL DISTRIBUTIONS" +In the literature a large number of probability distributions can be +found. The statistics package supports: +.IP \(bu +The normal or Gaussian distribution +.IP \(bu +The uniform distribution - equal probability for all data within a given +interval +.IP \(bu +The exponential distribution - useful as a model for certain +extreme-value distributions. +.IP \(bu +The gamma distribution - based on the incomplete Gamma integral +.IP \(bu +The chi-square distribution +.IP \(bu +The student's T distribution +.IP \(bu +The Poisson distribution +.IP \(bu +PM - binomial,F. +.PP +In principle for each distribution one has procedures for: +.IP \(bu +The probability density (pdf-*) +.IP \(bu +The cumulative density (cdf-*) +.IP \(bu +Quantiles for the given distribution (quantiles-*) +.IP \(bu +Histograms for the given distribution (histogram-*) +.IP \(bu +List of random values with the given distribution (random-*) +.PP +The following procedures have been implemented: +.TP +\fB::math::statistics::pdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR +Return the probability of a given value for a normal distribution with +given mean and standard deviation. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +float \fIstdev\fR +- Standard deviation of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-exponential\fR \fImean\fR \fIvalue\fR +Return the probability of a given value for an exponential +distribution with given mean. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR +Return the probability of a given value for a uniform +distribution with given extremes. +.RS +.TP +float \fIxmin\fR +- Minimum value of the distribution +.TP +float \fIxmin\fR +- Maximum value of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR +Return the probability of a given value for a Gamma +distribution with given shape and rate parameters +.RS +.TP +float \fIalpha\fR +- Shape parameter +.TP +float \fIbeta\fR +- Rate parameter +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-poisson\fR \fImu\fR \fIk\fR +Return the probability of a given number of occurrences in the same +interval (k) for a Poisson distribution with given mean (mu) +.RS +.TP +float \fImu\fR +- Mean number of occurrences +.TP +int \fIk\fR +- Number of occurences +.RE +.sp +.TP +\fB::math::statistics::pdf-chisquare\fR \fIdf\fR \fIvalue\fR +Return the probability of a given value for a chi square +distribution with given degrees of freedom +.RS +.TP +float \fIdf\fR +- Degrees of freedom +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-student-t\fR \fIdf\fR \fIvalue\fR +Return the probability of a given value for a Student's t +distribution with given degrees of freedom +.RS +.TP +float \fIdf\fR +- Degrees of freedom +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::pdf-beta\fR \fIa\fR \fIb\fR \fIvalue\fR +Return the probability of a given value for a Beta +distribution with given shape parameters +.RS +.TP +float \fIa\fR +- First shape parameter +.TP +float \fIb\fR +- First shape parameter +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR +Return the cumulative probability of a given value for a normal +distribution with given mean and standard deviation, that is the +probability for values up to the given one. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +float \fIstdev\fR +- Standard deviation of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-exponential\fR \fImean\fR \fIvalue\fR +Return the cumulative probability of a given value for an exponential +distribution with given mean. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR +Return the cumulative probability of a given value for a uniform +distribution with given extremes. +.RS +.TP +float \fIxmin\fR +- Minimum value of the distribution +.TP +float \fIxmin\fR +- Maximum value of the distribution +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-students-t\fR \fIdegrees\fR \fIvalue\fR +Return the cumulative probability of a given value for a Student's t +distribution with given number of degrees. +.RS +.TP +int \fIdegrees\fR +- Number of degrees of freedom +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR +Return the cumulative probability of a given value for a Gamma +distribution with given shape and rate parameters +.RS +.TP +float \fIalpha\fR +- Shape parameter +.TP +float \fIbeta\fR +- Rate parameter +.TP +float \fIvalue\fR +- Value for which the cumulative probability is required +.RE +.sp +.TP +\fB::math::statistics::cdf-poisson\fR \fImu\fR \fIk\fR +Return the cumulative probability of a given number of occurrences in +the same interval (k) for a Poisson distribution with given mean (mu) +.RS +.TP +float \fImu\fR +- Mean number of occurrences +.TP +int \fIk\fR +- Number of occurences +.RE +.sp +.TP +\fB::math::statistics::cdf-beta\fR \fIa\fR \fIb\fR \fIvalue\fR +Return the cumulative probability of a given value for a Beta +distribution with given shape parameters +.RS +.TP +float \fIa\fR +- First shape parameter +.TP +float \fIb\fR +- First shape parameter +.TP +float \fIvalue\fR +- Value for which the probability is required +.RE +.sp +.TP +\fB::math::statistics::random-normal\fR \fImean\fR \fIstdev\fR \fInumber\fR +Return a list of "number" random values satisfying a normal +distribution with given mean and standard deviation. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +float \fIstdev\fR +- Standard deviation of the distribution +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-exponential\fR \fImean\fR \fInumber\fR +Return a list of "number" random values satisfying an exponential +distribution with given mean. +.RS +.TP +float \fImean\fR +- Mean value of the distribution +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-uniform\fR \fIxmin\fR \fIxmax\fR \fInumber\fR +Return a list of "number" random values satisfying a uniform +distribution with given extremes. +.RS +.TP +float \fIxmin\fR +- Minimum value of the distribution +.TP +float \fIxmax\fR +- Maximum value of the distribution +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-gamma\fR \fIalpha\fR \fIbeta\fR \fInumber\fR +Return a list of "number" random values satisfying +a Gamma distribution with given shape and rate parameters +.RS +.TP +float \fIalpha\fR +- Shape parameter +.TP +float \fIbeta\fR +- Rate parameter +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-chisquare\fR \fIdf\fR \fInumber\fR +Return a list of "number" random values satisfying +a chi square distribution with given degrees of freedom +.RS +.TP +float \fIdf\fR +- Degrees of freedom +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-student-t\fR \fIdf\fR \fInumber\fR +Return a list of "number" random values satisfying +a Student's t distribution with given degrees of freedom +.RS +.TP +float \fIdf\fR +- Degrees of freedom +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::random-beta\fR \fIa\fR \fIb\fR \fInumber\fR +Return a list of "number" random values satisfying +a Beta distribution with given shape parameters +.RS +.TP +float \fIa\fR +- First shape parameter +.TP +float \fIb\fR +- Second shape parameter +.TP +int \fInumber\fR +- Number of values to be returned +.RE +.sp +.TP +\fB::math::statistics::histogram-uniform\fR \fIxmin\fR \fIxmax\fR \fIlimits\fR \fInumber\fR +Return the expected histogram for a uniform distribution. +.RS +.TP +float \fIxmin\fR +- Minimum value of the distribution +.TP +float \fIxmax\fR +- Maximum value of the distribution +.TP +list \fIlimits\fR +- Upper limits for the buckets in the histogram +.TP +int \fInumber\fR +- Total number of "observations" in the histogram +.RE +.sp +.TP +\fB::math::statistics::incompleteGamma\fR \fIx\fR \fIp\fR ?tol? +Evaluate the incomplete Gamma integral +.CS + + + 1 / x p-1 + P(p,x) = -------- | dt exp(-t) * t + Gamma(p) / 0 + +.CE +.RS +.TP +float \fIx\fR +- Value of x (limit of the integral) +.TP +float \fIp\fR +- Value of p in the integrand +.TP +float \fItol\fR +- Required tolerance (default: 1.0e-9) +.RE +.sp +.TP +\fB::math::statistics::incompleteBeta\fR \fIa\fR \fIb\fR \fIx\fR ?tol? +Evaluate the incomplete Beta integral +.RS +.TP +float \fIa\fR +- First shape parameter +.TP +float \fIb\fR +- Second shape parameter +.TP +float \fIx\fR +- Value of x (limit of the integral) +.TP +float \fItol\fR +- Required tolerance (default: 1.0e-9) +.RE +.sp +.PP +TO DO: more function descriptions to be added +.SH "DATA MANIPULATION" +The data manipulation procedures act on lists or lists of lists: +.TP +\fB::math::statistics::filter\fR \fIvarname\fR \fIdata\fR \fIexpression\fR +Return a list consisting of the data for which the logical +expression is true (this command works analogously to the command \fBforeach\fR). +.RS +.TP +string \fIvarname\fR +- Name of the variable used in the expression +.TP +list \fIdata\fR +- List of data +.TP +string \fIexpression\fR +- Logical expression using the variable name +.RE +.sp +.TP +\fB::math::statistics::map\fR \fIvarname\fR \fIdata\fR \fIexpression\fR +Return a list consisting of the data that are transformed via the +expression. +.RS +.TP +string \fIvarname\fR +- Name of the variable used in the expression +.TP +list \fIdata\fR +- List of data +.TP +string \fIexpression\fR +- Expression to be used to transform (map) the data +.RE +.sp +.TP +\fB::math::statistics::samplescount\fR \fIvarname\fR \fIlist\fR \fIexpression\fR +Return a list consisting of the \fIcounts\fR of all data in the +sublists of the "list" argument for which the expression is true. +.RS +.TP +string \fIvarname\fR +- Name of the variable used in the expression +.TP +list \fIdata\fR +- List of sublists, each containing the data +.TP +string \fIexpression\fR +- Logical expression to test the data (defaults to +"true"). +.RE +.sp +.TP +\fB::math::statistics::subdivide\fR +Routine \fIPM\fR - not implemented yet +.sp +.TP +\fB::math::statistics::test-Kruskal-Wallis\fR \fIconfidence\fR \fIargs\fR +Check if the population medians of two or more groups are equal with a +given confidence level, using the Kruskal-Wallis test. +.RS +.TP +float \fIconfidence\fR +- Confidence level to be used (0-1) +.TP +list \fIargs\fR +- Two or more lists of data +.RE +.sp +.TP +\fB::math::statistics::analyse-Kruskal-Wallis\fR \fIargs\fR +Compute the statistical parameters for the Kruskal-Wallis test. +Returns the Kruskal-Wallis statistic and the probability that that +value would occur assuming the medians of the populations are +equal. +.RS +.TP +list \fIargs\fR +- Two or more lists of data +.RE +.sp +.TP +\fB::math::statistics::group-rank\fR \fIargs\fR +Rank the groups of data with respect to the complete set. +Returns a list consisting of the group ID, the value and the rank +(possibly a rational number, in case of ties) for each data item. +.RS +.TP +list \fIargs\fR +- Two or more lists of data +.RE +.sp +.TP +\fB::math::statistics::test-Wilcoxon\fR \fIsample_a\fR \fIsample_b\fR +Compute the Wilcoxon test statistic to determine if two samples have the +same median or not. (The statistic can be regarded as standard normal, if the +sample sizes are both larger than 10. Returns the value of this statistic. +.RS +.TP +list \fIsample_a\fR +- List of data comprising the first sample +.TP +list \fIsample_b\fR +- List of data comprising the second sample +.RE +.sp +.TP +\fB::math::statistics::spearman-rank\fR \fIsample_a\fR \fIsample_b\fR +Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient. The two samples should have the same number of data. +.RS +.TP +list \fIsample_a\fR +- First list of data +.TP +list \fIsample_b\fR +- Second list of data +.RE +.sp +.TP +\fB::math::statistics::spearman-rank-extended\fR \fIsample_a\fR \fIsample_b\fR +Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient as well as additional data. The two samples should have the same number of data. +The procedure returns the correlation coefficient, the number of data pairs used and the +z-score, an approximately standard normal statistic, indicating the significance of the correlation. +.RS +.TP +list \fIsample_a\fR +- First list of data +.TP +list \fIsample_b\fR +- Second list of data +.RE +.PP +.SH "PLOT PROCEDURES" +The following simple plotting procedures are available: +.TP +\fB::math::statistics::plot-scale\fR \fIcanvas\fR \fIxmin\fR \fIxmax\fR \fIymin\fR \fIymax\fR +Set the scale for a plot in the given canvas. All plot routines expect +this function to be called first. There is no automatic scaling +provided. +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +float \fIxmin\fR +- Minimum x value +.TP +float \fIxmax\fR +- Maximum x value +.TP +float \fIymin\fR +- Minimum y value +.TP +float \fIymax\fR +- Maximum y value +.RE +.sp +.TP +\fB::math::statistics::plot-xydata\fR \fIcanvas\fR \fIxdata\fR \fIydata\fR \fItag\fR +Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The tag can be used to manipulate the +appearance. +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +float \fIxdata\fR +- Series of independent data +.TP +float \fIydata\fR +- Series of dependent data +.TP +string \fItag\fR +- Tag to give to the plotted data (defaults to xyplot) +.RE +.sp +.TP +\fB::math::statistics::plot-xyline\fR \fIcanvas\fR \fIxdata\fR \fIydata\fR \fItag\fR +Create a simple XY plot in the given canvas - the data are +shown as a line through the data points. The tag can be used to +manipulate the appearance. +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +list \fIxdata\fR +- Series of independent data +.TP +list \fIydata\fR +- Series of dependent data +.TP +string \fItag\fR +- Tag to give to the plotted data (defaults to xyplot) +.RE +.sp +.TP +\fB::math::statistics::plot-tdata\fR \fIcanvas\fR \fItdata\fR \fItag\fR +Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The horizontal coordinate is equal to the +index. The tag can be used to manipulate the appearance. +This type of presentation is suitable for autocorrelation functions for +instance or for inspecting the time-dependent behaviour. +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +list \fItdata\fR +- Series of dependent data +.TP +string \fItag\fR +- Tag to give to the plotted data (defaults to xyplot) +.RE +.sp +.TP +\fB::math::statistics::plot-tline\fR \fIcanvas\fR \fItdata\fR \fItag\fR +Create a simple XY plot in the given canvas - the data are +shown as a line. See plot-tdata for an explanation. +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +list \fItdata\fR +- Series of dependent data +.TP +string \fItag\fR +- Tag to give to the plotted data (defaults to xyplot) +.RE +.sp +.TP +\fB::math::statistics::plot-histogram\fR \fIcanvas\fR \fIcounts\fR \fIlimits\fR \fItag\fR +Create a simple histogram in the given canvas +.RS +.TP +widget \fIcanvas\fR +- Canvas widget to use +.TP +list \fIcounts\fR +- Series of bucket counts +.TP +list \fIlimits\fR +- Series of upper limits for the buckets +.TP +string \fItag\fR +- Tag to give to the plotted data (defaults to xyplot) +.RE +.sp +.PP +.SH "THINGS TO DO" +The following procedures are yet to be implemented: +.IP \(bu +F-test-stdev +.IP \(bu +interval-mean-stdev +.IP \(bu +histogram-normal +.IP \(bu +histogram-exponential +.IP \(bu +test-histogram +.IP \(bu +test-corr +.IP \(bu +quantiles-* +.IP \(bu +fourier-coeffs +.IP \(bu +fourier-residuals +.IP \(bu +onepar-function-fit +.IP \(bu +onepar-function-residuals +.IP \(bu +plot-linear-model +.IP \(bu +subdivide +.PP +.SH EXAMPLES +The code below is a small example of how you can examine a set of +data: +.PP +.CS + + + +# Simple example: +# - Generate data (as a cheap way of getting some) +# - Perform statistical analysis to describe the data +# +package require math::statistics + +# +# Two auxiliary procs +# +proc pause {time} { + set wait 0 + after [expr {$time*1000}] {set ::wait 1} + vwait wait +} + +proc print-histogram {counts limits} { + foreach count $counts limit $limits { + if { $limit != {} } { + puts [format "<%12.4g\\t%d" $limit $count] + set prev_limit $limit + } else { + puts [format ">%12.4g\\t%d" $prev_limit $count] + } + } +} + +# +# Our source of arbitrary data +# +proc generateData { data1 data2 } { + upvar 1 $data1 _data1 + upvar 1 $data2 _data2 + + set d1 0.0 + set d2 0.0 + for { set i 0 } { $i < 100 } { incr i } { + set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}] + set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}] + lappend _data1 $d1 + lappend _data2 $d2 + } + return {} +} + +# +# The analysis session +# +package require Tk +console show +canvas .plot1 +canvas .plot2 +pack .plot1 .plot2 -fill both -side top + +generateData data1 data2 + +puts "Basic statistics:" +set b1 [::math::statistics::basic-stats $data1] +set b2 [::math::statistics::basic-stats $data2] +foreach label {mean min max number stdev var} v1 $b1 v2 $b2 { + puts "$label\\t$v1\\t$v2" +} +puts "Plot the data as function of \\"time\\" and against each other" +::math::statistics::plot-scale .plot1 0 100 0 20 +::math::statistics::plot-scale .plot2 0 20 0 20 +::math::statistics::plot-tline .plot1 $data1 +::math::statistics::plot-tline .plot1 $data2 +::math::statistics::plot-xydata .plot2 $data1 $data2 + +puts "Correlation coefficient:" +puts [::math::statistics::corr $data1 $data2] + +pause 2 +puts "Plot histograms" +.plot2 delete all +::math::statistics::plot-scale .plot2 0 20 0 100 +set limits [::math::statistics::minmax-histogram-limits 7 16] +set histogram_data [::math::statistics::histogram $limits $data1] +::math::statistics::plot-histogram .plot2 $histogram_data $limits + +puts "First series:" +print-histogram $histogram_data $limits + +pause 2 +set limits [::math::statistics::minmax-histogram-limits 0 15 10] +set histogram_data [::math::statistics::histogram $limits $data2] +::math::statistics::plot-histogram .plot2 $histogram_data $limits d2 +.plot2 itemconfigure d2 -fill red + +puts "Second series:" +print-histogram $histogram_data $limits + +puts "Autocorrelation function:" +set autoc [::math::statistics::autocorr $data1] +puts [::math::statistics::map $autoc {[format "%.2f" $x]}] +puts "Cross-correlation function:" +set crossc [::math::statistics::crosscorr $data1 $data2] +puts [::math::statistics::map $crossc {[format "%.2f" $x]}] + +::math::statistics::plot-scale .plot1 0 100 -1 4 +::math::statistics::plot-tline .plot1 $autoc "autoc" +::math::statistics::plot-tline .plot1 $crossc "crossc" +.plot1 itemconfigure autoc -fill green +.plot1 itemconfigure crossc -fill yellow + +puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9" +puts "First: [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]" +puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]" + + +.CE +If you run this example, then the following should be clear: +.IP \(bu +There is a strong correlation between two time series, as displayed by +the raw data and especially by the correlation functions. +.IP \(bu +Both time series show a significant periodic component +.IP \(bu +The histograms are not very useful in identifying the nature of the time +series - they do not show the periodic nature. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: statistics\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +data analysis, mathematics, statistics +.SH CATEGORY +Mathematics ADDED embedded/man/files/modules/math/symdiff.n Index: embedded/man/files/modules/math/symdiff.n ================================================================== --- /dev/null +++ embedded/man/files/modules/math/symdiff.n @@ -0,0 +1,336 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/math/symdiff.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010 by Kevin B. Kenny <kennykb@acm.org> +'\" Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "math::calculus::symdiff" n 1.0 tcllib "Symbolic differentiation for Tcl" +.BS +.SH NAME +math::calculus::symdiff \- Symbolic differentiation for Tcl +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBgrammar::aycock 1.0\fR +.sp +package require \fBmath::calculus::symdiff 1.0\fR +.sp +\fBmath::calculus::symdiff::symdiff\fR \fIexpression\fR \fIvariable\fR +.sp +\fBmath::calculus::jacobian\fR \fIvariableDict\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmath::calculus::symdiff\fR package provides a symbolic differentiation +facility for Tcl math expressions. It is useful for providing derivatives +to packages that either require the Jacobian of a set of functions or else +are more efficient or stable when the Jacobian is provided. +.SH PROCEDURES +The \fBmath::calculus::symdiff\fR package exports the two procedures: +.TP +\fBmath::calculus::symdiff::symdiff\fR \fIexpression\fR \fIvariable\fR +Differentiates the given \fIexpression\fR with respect to the specified +\fIvariable\fR. (See \fBExpressions\fR below for a discussion of the +subset of Tcl math expressions that are acceptable to +\fBmath::calculus::symdiff\fR.) +The result is a Tcl expression that evaluates the derivative. Returns an +error if \fIexpression\fR is not a well-formed expression or is not +differentiable. +.TP +\fBmath::calculus::jacobian\fR \fIvariableDict\fR +Computes the Jacobian of a system of equations. +The system is given by the dictionary \fIvariableDict\fR, whose keys +are the names of variables in the system, and whose values are Tcl expressions +giving the values of those variables. (See \fBExpressions\fR below +for a discussion of the subset of Tcl math expressions that are acceptable +to \fBmath::calculus::symdiff\fR. The result is a list of lists: +the i'th element of the j'th sublist is the partial derivative of +the i'th variable with respect to the j'th variable. Returns an error if +any of the expressions cannot be differentiated, or if \fIvariableDict\fR +is not a well-formed dictionary. +.PP +.SH EXPRESSIONS +The \fBmath::calculus::symdiff\fR package accepts only a small subset of the expressions +that are acceptable to Tcl commands such as \fBexpr\fR or \fBif\fR. +Specifically, the only constructs accepted are: +.IP \(bu +Floating-point constants such as \fB5\fR or \fB3.14159e+00\fR. +.IP \(bu +References to Tcl variable using $-substitution. The variable names +must consist of alphanumerics and underscores: the \fB${...}\fR notation +is not accepted. +.IP \(bu +Parentheses. +.IP \(bu +The \fB+\fR, \fB-\fR, \fB*\fR, \fB/\fR. and \fB**\fR +operators. +.IP \(bu +Calls to the functions \fBacos\fR, \fBasin\fR, \fBatan\fR, +\fBatan2\fR, \fBcos\fR, \fBcosh\fR, \fBexp\fR, \fBhypot\fR, \fBlog\fR, +\fBlog10\fR, \fBpow\fR, \fBsin\fR, \fBsinh\fR. \fBsqrt\fR, \fBtan\fR, +and \fBtanh\fR. +.PP +Command substitution, backslash substitution, and argument expansion are +not accepted. +.SH EXAMPLES +.CS + + +math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x +==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d))) +math::calculus::symdiff::jacobian {x {$a * $x + $b * $y} + y {$c * $x + $d * $y}} +==> {{$a} {$b}} {{$c} {$d}} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImath :: calculus\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +math::calculus, math::interpolate +.SH COPYRIGHT +.nf +Copyright (c) 2010 by Kevin B. Kenny <kennykb@acm.org> +Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/> + +.fi ADDED embedded/man/files/modules/md4/md4.n Index: embedded/man/files/modules/md4/md4.n ================================================================== --- /dev/null +++ embedded/man/files/modules/md4/md4.n @@ -0,0 +1,399 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/md4/md4.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "md4" n 1.0.5 tcllib "MD4 Message-Digest Algorithm" +.BS +.SH NAME +md4 \- MD4 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmd4 ?1.0?\fR +.sp +\fB::md4::md4\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::md4::hmac\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::md4::MD4Init\fR +.sp +\fB::md4::MD4Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::md4::MD4Final\fR \fItoken\fR +.sp +\fB::md4::HMACInit\fR \fIkey\fR +.sp +\fB::md4::HMACUpdate\fR \fItoken\fR \fIdata\fR +.sp +\fB::md4::HMACFinal\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package is an implementation in Tcl of the MD4 message-digest +algorithm as described in RFC 1320 (1) and (2). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD4 algorithm is faster but potentially weaker than +the related MD5 algorithm (3). +.PP +If you have \fBcritcl\fR and have built the \fBtcllibc\fR package +then the implementation of the hashing function will be performed by compiled +code. Alternatively if \fBcryptkit\fR is available this will be +used. If no accelerator package can be found then the pure-tcl +implementation is used. The programming interface remains the same in +all cases. +.SH COMMANDS +.TP +\fB::md4::md4\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate the MD4 digest of the data given in string. This is returned +as a binary string by default. Giving the \fI-hex\fR option will +return a hexadecimal encoded version of the digest. +.sp +The data to be hashed can be specified either as a string argument to +the md4 command, or as a filename or a pre-opened channel. If the +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::md4::hmac\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate an Hashed Message Authentication digest (HMAC) using the MD4 +digest algorithm. HMACs are described in RFC 2104 (4) and provide an MD4 +digest that includes a key. All options other than \fI-key\fR are as +for the \fB::md4::md4\fR command. +.PP +.SH "PROGRAMMING INTERFACE" +For the programmer, the MD4 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD4 hash operates on a token (equivalent to the +bucket). You call \fBMD4Init\fR to obtain a token and then call +\fBMD4Update\fR as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +\fBMD4Final\fR. An equivalent set of functions gives you a keyed digest (HMAC). +.TP +\fB::md4::MD4Init\fR +Begins a new MD4 hash. Returns a token ID that must be used for the +remaining functions. +.TP +\fB::md4::MD4Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fIMD4Update $token "abcd"\fR is equivalent to calling +\fIMD4Update $token "ab"\fR followed by +\fIMD4Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::md4::MD4Final\fR \fItoken\fR +Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD4 +digest value. +.TP +\fB::md4::HMACInit\fR \fIkey\fR +This is equivalent to the \fB::md4::MD4Init\fR command except that +it requires the key that will be included in the HMAC. +.TP +\fB::md4::HMACUpdate\fR \fItoken\fR \fIdata\fR +.TP +\fB::md4::HMACFinal\fR \fItoken\fR +These commands are identical to the MD4 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% md4::md4 -hex "Tcl does MD4" +858da9b31f57648a032230447bd15f25 + +.CE +.CS + + +% md4::hmac -hex -key Sekret "Tcl does MD4" +c324088e5752872689caedf2a0464758 + +.CE +.CS + + +% set tok [md4::MD4Init] +::md4::1 +% md4::MD4Update $tok "Tcl " +% md4::MD4Update $tok "does " +% md4::MD4Update $tok "MD4" +% md4::Hex [md4::MD4Final $tok] +858da9b31f57648a032230447bd15f25 + +.CE +.SH REFERENCES +.IP [1] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [2] +Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes +and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 +Proceedings, pages 303-311, Springer-Verlag, 1991. +.IP [3] +Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and +RSA Data Security, Inc, April 1992. +(\fIhttp://www.rfc-editor.org/rfc/rfc1321.txt\fR) +.IP [4] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImd4\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md5, sha1 +.SH KEYWORDS +hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/md5/md5.n Index: embedded/man/files/modules/md5/md5.n ================================================================== --- /dev/null +++ embedded/man/files/modules/md5/md5.n @@ -0,0 +1,405 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/md5/md5.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "md5" n 2.0.7 tcllib "MD5 Message-Digest Algorithm" +.BS +.SH NAME +md5 \- MD5 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmd5 ?2.0.7?\fR +.sp +\fB::md5::md5\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::md5::hmac\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::md5::MD5Init\fR +.sp +\fB::md5::MD5Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::md5::MD5Final\fR \fItoken\fR +.sp +\fB::md5::HMACInit\fR \fIkey\fR +.sp +\fB::md5::HMACUpdate\fR \fItoken\fR \fIdata\fR +.sp +\fB::md5::HMACFinal\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package is an implementation in Tcl of the MD5 message-digest +algorithm as described in RFC 1321 (1). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD5 algorithm is related to the MD4 algorithm (2) +but has been strengthened against certain types of potential +attack. MD5 should be used in preference to MD4 for new applications. +.PP +If you have \fBcritcl\fR and have built the \fBtcllibc\fR +package then the implementation of the hashing function will be +performed by compiled code. Alternatively if you have either +\fBcryptkit\fR or \fBTrf\fR then either of these can be used to +accelerate the digest computation. If no suitable compiled package is +available then the pure-Tcl implementation wil be used. The +programming interface remains the same in all cases. +.PP +\fINote\fR the previous version of this package always returned a +hex encoded string. This has been changed to simplify the programming +interface and to make this version more compatible with other +implementations. To obtain the previous usage, either explicitly +specify package version 1 or use the \fI-hex\fR option to the +\fBmd5\fR command. +.SH COMMANDS +.TP +\fB::md5::md5\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate the MD5 digest of the data given in string. This is returned +as a binary string by default. Giving the \fI-hex\fR option will +return a hexadecimal encoded version of the digest. +.sp +The data to be hashed can be specified either as a string argument to +the \fBmd5\fR command, or as a filename or a pre-opened channel. If the +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::md5::hmac\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate an Hashed Message Authentication digest (HMAC) using the MD5 +digest algorithm. HMACs are described in RFC 2104 (3) and provide an MD5 +digest that includes a key. All options other than \fI-key\fR are as +for the \fB::md5::md5\fR command. +.PP +.SH "PROGRAMMING INTERFACE" +For the programmer, the MD5 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD5 hash operates on a token (equivalent to the +bucket). You call \fBMD5Init\fR to obtain a token and then call +\fBMD5Update\fR as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +\fBMD5Final\fR. An equivalent set of functions gives you a keyed digest +(HMAC). +.TP +\fB::md5::MD5Init\fR +Begins a new MD5 hash. Returns a token ID that must be used for the +remaining functions. +.TP +\fB::md5::MD5Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fIMD5Update $token "abcd"\fR is equivalent to calling +\fIMD5Update $token "ab"\fR followed by +\fIMD5Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::md5::MD5Final\fR \fItoken\fR +Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD5 +digest value. +.TP +\fB::md5::HMACInit\fR \fIkey\fR +This is equivalent to the \fB::md5::MD5Init\fR command except that +it requires the key that will be included in the HMAC. +.TP +\fB::md5::HMACUpdate\fR \fItoken\fR \fIdata\fR +.TP +\fB::md5::HMACFinal\fR \fItoken\fR +These commands are identical to the MD5 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% md5::md5 -hex "Tcl does MD5" +8AAC1EE01E20BB347104FABB90310433 + +.CE +.CS + + +% md5::hmac -hex -key Sekret "Tcl does MD5" +35BBA244FD56D3EDF5F3C47474DACB5D + +.CE +.CS + + +% set tok [md5::MD5Init] +::md5::1 +% md5::MD5Update $tok "Tcl " +% md5::MD5Update $tok "does " +% md5::MD5Update $tok "MD5" +% md5::Hex [md5::MD5Final $tok] +8AAC1EE01E20BB347104FABB90310433 + +.CE +.SH REFERENCES +.IP [1] +Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and +RSA Data Security, Inc, April 1992. +(\fIhttp://www.rfc-editor.org/rfc/rfc1321.txt\fR) +.IP [2] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [3] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImd5\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md4, sha1 +.SH KEYWORDS +hashing, md5, message-digest, rfc 1320, rfc 1321, rfc 2104, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/md5crypt/md5crypt.n Index: embedded/man/files/modules/md5crypt/md5crypt.n ================================================================== --- /dev/null +++ embedded/man/files/modules/md5crypt/md5crypt.n @@ -0,0 +1,333 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/md5crypt/md5crypt.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "md5crypt" n 1.1.0 tcllib "MD5-based password encryption" +.BS +.SH NAME +md5crypt \- MD5-based password encryption +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBmd5 2.0\fR +.sp +package require \fBmd5crypt ?1.1.0?\fR +.sp +\fB::md5crypt::md5crypt\fR \fIpassword\fR \fIsalt\fR +.sp +\fB::md5crypt::aprcrypt\fR \fIpassword\fR \fIsalt\fR +.sp +\fB::md5crypt::salt\fR ?\fIlength\fR? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides an implementation of the MD5-crypt password +encryption algorithm as pioneered by FreeBSD and currently in use as a +replacement for the unix crypt(3) function in many modern +systems. An implementation of the closely related Apache MD5-crypt is +also available. +The output of these commands are compatible with the BSD and OpenSSL +implementation of md5crypt and the Apache 2 htpasswd program. +.SH COMMANDS +.TP +\fB::md5crypt::md5crypt\fR \fIpassword\fR \fIsalt\fR +Generate a BSD compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT). +.TP +\fB::md5crypt::aprcrypt\fR \fIpassword\fR \fIsalt\fR +Generate an Apache compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT). +.TP +\fB::md5crypt::salt\fR ?\fIlength\fR? +Generate a random salt string suitable for use with the \fBmd5crypt\fR and +\fBaprcrypt\fR commands. +.PP +.SH SALT +The salt passed to either of the encryption schemes implemented here +is checked to see if it begins with the encryption scheme magic string +(either "$1$" for MD5-crypt or "$apr1$" for Apache crypt). If so, this +is removed. The remaining characters up to the next $ and up to a +maximum of 8 characters are then used as the salt. The salt text +should probably be restricted the set of ASCII alphanumeric characters +plus "./" (dot and forward-slash) - this is to preserve maximum +compatability with the unix password file format. +.PP +If a password is being generated rather than checked from a password +file then the \fBsalt\fR command may be used to generate a random salt. +.SH EXAMPLES +.CS + + +% md5crypt::md5crypt password 01234567 +$1$01234567$b5lh2mHyD2PdJjFfALlEz1 + +.CE +.CS + + +% md5crypt::aprcrypt password 01234567 +$apr1$01234567$IXBaQywhAhc0d75ZbaSDp/ + +.CE +.CS + + +% md5crypt::md5crypt password [md5crypt::salt] +$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImd5crypt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md5 +.SH KEYWORDS +hashing, md5, md5crypt, message-digest, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/mime/mime.n Index: embedded/man/files/modules/mime/mime.n ================================================================== --- /dev/null +++ embedded/man/files/modules/mime/mime.n @@ -0,0 +1,569 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/mime/mime.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 1999-2000 Marshall T. Rose +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "mime" n 1.5.6 tcllib "Mime" +.BS +.SH NAME +mime \- Manipulation of MIME body parts +.SH SYNOPSIS +package require \fBTcl \fR +.sp +package require \fBmime ?1.5.6?\fR +.sp +\fB::mime::initialize\fR ?\fB-canonical\fR \fItype/subtype\fR ?\fB-param\fR {\fIkey value\fR}...? ?\fB-encoding\fR \fIvalue\fR? ?\fB-header\fR {\fIkey value\fR}...?? (\fB-file\fR \fIname\fR | \fB-string\fR \fIvalue\fR | \fB-parts\fR {\fItoken1\fR ... \fItokenN\fR}) +.sp +\fB::mime::finalize\fR \fItoken\fR ?\fB-subordinates\fR \fBall\fR | \fBdynamic\fR | \fBnone\fR? +.sp +\fB::mime::getproperty\fR \fItoken\fR ?\fIproperty\fR | \fB-names\fR? +.sp +\fB::mime::getheader\fR \fItoken\fR ?\fIkey\fR | \fB-names\fR? +.sp +\fB::mime::setheader\fR \fItoken\fR \fIkey value\fR ?\fB-mode\fR \fBwrite\fR | \fBappend\fR | \fBdelete\fR? +.sp +\fB::mime::getbody\fR \fItoken\fR ?\fB-decode\fR? ?\fB-command\fR \fIcallback\fR ?\fB-blocksize\fR \fIoctets\fR?? +.sp +\fB::mime::copymessage\fR \fItoken\fR \fIchannel\fR +.sp +\fB::mime::buildmessage\fR \fItoken\fR +.sp +\fB::mime::parseaddress\fR \fIstring\fR +.sp +\fB::mime::parsedatetime\fR (\fIstring\fR | \fB-now\fR) \fIproperty\fR +.sp +\fB::mime::mapencoding\fR \fIencoding_name\fR +.sp +\fB::mime::reversemapencoding\fR \fIcharset_type\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBmime\fR library package provides the commands to create and +manipulate MIME body parts. +.TP +\fB::mime::initialize\fR ?\fB-canonical\fR \fItype/subtype\fR ?\fB-param\fR {\fIkey value\fR}...? ?\fB-encoding\fR \fIvalue\fR? ?\fB-header\fR {\fIkey value\fR}...?? (\fB-file\fR \fIname\fR | \fB-string\fR \fIvalue\fR | \fB-parts\fR {\fItoken1\fR ... \fItokenN\fR}) +This command creates a MIME part and returns a token representing it. +.RS +.IP \(bu +If the \fB-canonical\fR option is present, then the body is in +canonical (raw) form and is found by consulting either the +\fB-file\fR, \fB-string\fR, or \fB-parts\fR option. +.sp +In addition, both the \fB-param\fR and \fB-header\fR options may +occur zero or more times to specify \fBContent-Type\fR parameters +(e.g., \fBcharset\fR) and header keyword/values (e.g., +\fBContent-Disposition\fR), respectively. +.sp +Also, \fB-encoding\fR, if present, specifies the +\fBContent-Transfer-Encoding\fR when copying the body. +.IP \(bu +If the \fB-canonical\fR option is not present, then the MIME part +contained in either the \fB-file\fR or the \fB-string\fR option +is parsed, dynamically generating subordinates as appropriate. +.RE +.TP +\fB::mime::finalize\fR \fItoken\fR ?\fB-subordinates\fR \fBall\fR | \fBdynamic\fR | \fBnone\fR? +This command destroys the MIME part represented by \fItoken\fR. It +returns an empty string. +.sp +If the \fB-subordinates\fR option is present, it specifies which +subordinates should also be destroyed. The default value is +\fBdynamic\fR, destroying all subordinates which were created by +\fB::mime::initialize\fR together with the containing body part. +.TP +\fB::mime::getproperty\fR \fItoken\fR ?\fIproperty\fR | \fB-names\fR? +This command returns a string or a list of strings containing the +properties of a MIME part. If the command is invoked with the name of +a specific property, then the corresponding value is returned; +instead, if \fB-names\fR is specified, a list of all properties is +returned; otherwise, a serialized array of properties and values is +returned. +.sp +The possible properties are: +.RS +.TP +\fBcontent\fR +The type/subtype describing the content +.TP +\fBencoding\fR +The "Content-Transfer-Encoding" +.TP +\fBparams\fR +A list of "Content-Type" parameters +.TP +\fBparts\fR +A list of tokens for the part's subordinates. This property is +present only if the MIME part has subordinates. +.TP +\fBsize\fR +The approximate size of the content (unencoded) +.RE +.TP +\fB::mime::getheader\fR \fItoken\fR ?\fIkey\fR | \fB-names\fR? +This command returns the header of a MIME part, as a list of strings. +.sp +A header consists of zero or more key/value pairs. Each value is a +list containing one or more strings. +.sp +If this command is invoked with the name of a specific \fIkey\fR, then +a list containing the corresponding value(s) is returned; instead, if +-names is specified, a list of all keys is returned; otherwise, a +serialized array of keys and values is returned. Note that when a key +is specified (e.g., "Subject"), the list returned usually contains +exactly one string; however, some keys (e.g., "Received") often occur +more than once in the header, accordingly the list returned usually +contains more than one string. +.TP +\fB::mime::setheader\fR \fItoken\fR \fIkey value\fR ?\fB-mode\fR \fBwrite\fR | \fBappend\fR | \fBdelete\fR? +This command writes, appends to, or deletes the \fIvalue\fR associated +with a \fIkey\fR in the header. It returns a list of strings +containing the previous value associated with the key. +.sp +The value for \fB-mode\fR is one of: +.RS +.TP +\fBwrite\fR +The \fIkey\fR/\fIvalue\fR is either created or overwritten (the default). +.TP +\fBappend\fR +A new \fIvalue\fR is appended for the \fIkey\fR (creating it as necessary). +.TP +\fBdelete\fR +All values associated with the key are removed (the \fIvalue\fR +parameter is ignored). +.RE +.TP +\fB::mime::getbody\fR \fItoken\fR ?\fB-decode\fR? ?\fB-command\fR \fIcallback\fR ?\fB-blocksize\fR \fIoctets\fR?? +This command returns a string containing the body of the leaf MIME +part represented by \fItoken\fR in canonical form. +.sp +If the \fB-command\fR option is present, then it is repeatedly +invoked with a fragment of the body as this: +.CS + + + uplevel #0 $callback [list "data" $fragment] + +.CE +.sp +(The \fB-blocksize\fR option, if present, specifies the maximum +size of each fragment passed to the callback.) +.sp +When the end of the body is reached, the callback is invoked as: +.CS + + + uplevel #0 $callback "end" + +.CE +.sp +Alternatively, if an error occurs, the callback is invoked as: +.CS + + + uplevel #0 $callback [list "error" reason] + +.CE +.sp +Regardless, the return value of the final invocation of the callback +is propagated upwards by \fB::mime::getbody\fR. +.sp +If the \fB-command\fR option is absent, then the return value of +\fB::mime::getbody\fR is a string containing the MIME part's entire +body. +.sp +If the option \fB-decode\fR is absent the return value computed +above is returned as is. This means that it will be in the charset +specified for the token and not the usual utf-8. +If the option \fB-decode\fR is present however the command will use +the charset information associated with the token to convert the +string from its encoding into utf-8 before returning it. +.TP +\fB::mime::copymessage\fR \fItoken\fR \fIchannel\fR +This command copies the MIME represented by \fItoken\fR part to the +specified \fIchannel\fR. The command operates synchronously, and uses +fileevent to allow asynchronous operations to proceed +independently. It returns an empty string. +.TP +\fB::mime::buildmessage\fR \fItoken\fR +This command returns the MIME part represented by \fItoken\fR as a +string. It is similar to \fB::mime::copymessage\fR, only it returns +the data as a return string instead of writing to a channel. +.TP +\fB::mime::parseaddress\fR \fIstring\fR +This command takes a string containing one or more 822-style address +specifications and returns a list of serialized arrays, one element +for each address specified in the argument. If the string contains +more than one address they will be separated by commas. +.sp +Each serialized array contains the properties below. Note that one or +more of these properties may be empty. +.RS +.TP +\fBaddress\fR +local@domain +.TP +\fBcomment\fR +822-style comment +.TP +\fBdomain\fR +the domain part (rhs) +.TP +\fBerror\fR +non-empty on a parse error +.TP +\fBgroup\fR +this address begins a group +.TP +\fBfriendly\fR +user-friendly rendering +.TP +\fBlocal\fR +the local part (lhs) +.TP +\fBmemberP\fR +this address belongs to a group +.TP +\fBphrase\fR +the phrase part +.TP +\fBproper\fR +822-style address specification +.TP +\fBroute\fR +822-style route specification (obsolete) +.RE +.TP +\fB::mime::parsedatetime\fR (\fIstring\fR | \fB-now\fR) \fIproperty\fR +This command takes a string containing an 822-style date-time +specification and returns the specified property as a serialized +array. +.sp +The list of properties and their ranges are: +.RS +.TP +\fBhour\fR +0 .. 23 +.TP +\fBlmonth\fR +January, February, ..., December +.TP +\fBlweekday\fR +Sunday, Monday, ... Saturday +.TP +\fBmday\fR +1 .. 31 +.TP +\fBmin\fR +0 .. 59 +.TP +\fBmon\fR +1 .. 12 +.TP +\fBmonth\fR +Jan, Feb, ..., Dec +.TP +\fBproper\fR +822-style date-time specification +.TP +\fBrclock\fR +elapsed seconds between then and now +.TP +\fBsec\fR +0 .. 59 +.TP +\fBwday\fR +0 .. 6 (Sun .. Mon) +.TP +\fBweekday\fR +Sun, Mon, ..., Sat +.TP +\fByday\fR +1 .. 366 +.TP +\fByear\fR +1900 ... +.TP +\fBzone\fR +-720 .. 720 (minutes east of GMT) +.RE +.TP +\fB::mime::mapencoding\fR \fIencoding_name\fR +This commansd maps tcl encodings onto the proper names for their MIME +charset type. This is only done for encodings whose charset types +were known. The remaining encodings return "" for now. +.TP +\fB::mime::reversemapencoding\fR \fIcharset_type\fR +This command maps MIME charset types onto tcl encoding names. Those +that are unknown return "". +.PP +.SH "KNOWN BUGS" +.TP +SourceForge Tcllib Bug #447037 +This problem affects only people which are using Tcl and Mime on a +64-bit system. The currently recommended fix for this problem is to +upgrade to Tcl version 8.4. This version has extended 64 bit support +and the bug does not appear anymore. +.sp +The problem could have been generally solved by requiring the use of +Tcl 8.4 for this package. We decided against this solution as it would +force a large number of unaffected users to upgrade their Tcl +interpreter for no reason. +.sp +See \fIhttp://sourceforge.net/tracker/?func=detail&aid=447037&group_id=12883&atid=112883\fR +for additional information. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImime\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ftp, http, pop3, smtp +.SH KEYWORDS +email, internet, mail, mime, net, rfc 2045, rfc 2046, rfc 2049, rfc 821, rfc 822, smtp +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 1999-2000 Marshall T. Rose + +.fi ADDED embedded/man/files/modules/mime/smtp.n Index: embedded/man/files/modules/mime/smtp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/mime/smtp.n @@ -0,0 +1,408 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/mime/smtp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 1999-2000 Marshall T. Rose and others +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "smtp" n 1.4.5 tcllib "smtp client" +.BS +.SH NAME +smtp \- Client-side tcl implementation of the smtp protocol +.SH SYNOPSIS +package require \fBTcl \fR +.sp +package require \fBmime ?1.5.4?\fR +.sp +package require \fBsmtp ?1.4.5?\fR +.sp +\fB::smtp::sendmessage\fR \fItoken\fR \fIoption\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBsmtp\fR library package provides the client side of the +Simple Mail Transfer Protocol (SMTP) (1) (2). +.TP +\fB::smtp::sendmessage\fR \fItoken\fR \fIoption\fR... +This command sends the MIME part (see package \fBmime\fR) +represented by \fItoken\fR to an SMTP server. \fIoptions\fR is a list +of options and their associated values. The recognized options are: +.RS +.TP +\fB-servers\fR +A list of SMTP servers. The default is \fBlocalhost\fR. +.TP +\fB-ports\fR +A list of SMTP ports. The default is \fB25\fR. +.TP +\fB-client\fR +The name to use as our hostname when connecting to the server. By +default this is either localhost if one of the servers is localhost, +or is set to the string returned by \fBinfo hostname\fR. +.TP +\fB-queue\fR +Indicates that the SMTP server should be asked to queue the message +for later processing. A boolean value. +.TP +\fB-atleastone\fR +Indicates that the SMTP server must find at least one recipient +acceptable for the message to be sent. A boolean value. +.TP +\fB-originator\fR +A string containing an 822-style address specification. If present the +header isn't examined for an originator address. +.TP +\fB-recipients\fR +A string containing one or more 822-style address specifications. If +present the header isn't examined for recipient addresses). If the +string contains more than one address they will be separated by +commas. +.TP +\fB-header\fR +A list containing two elements, an smtp header and its associated +value (the -header option may occur zero or more times). +.TP +\fB-usetls\fR +This package supports the RFC 3207 TLS extension (3) by default provided the +tls package is available. You can turn this off with this boolean option. +.TP +\fB-tlspolicy\fR +This option lets you specify a command to be called if an error occurs +during TLS setup. The command is called with the SMTP code and diagnostic +message appended. The command should return 'secure' or 'insecure' where +insecure will cause the package to continue on the unencrypted channel. +Returning 'secure' will cause the socket to be closed and the next server +in the \fB-servers\fR list to be tried. +.TP +\fB-username\fR +.TP +\fB-password\fR +If your SMTP server requires authentication (RFC 2554 (4)) before +accepting mail you can use \fB-username\fR and \fB-password\fR +to provide your authentication details to the server. Currently this +package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication +methods. The most secure method will be tried first and each method +tried in turn until we are either authorized or we run out of +methods. Note that if the server permits a TLS connection, then the +authorization will occur after we begin using the secure channel. +.sp +Please also read the section on \fBAuthentication\fR, it details +the necessary prequisites, i.e. packages needed to support these +options and authentication. +.RE +.sp +If the \fB-originator\fR option is not present, the originator +address is taken from \fBFrom\fR (or \fBResent-From\fR); +similarly, if the \fB-recipients\fR option is not present, +recipient addresses are taken from \fBTo\fR, \fBcc\fR, and +\fBBcc\fR (or \fBResent-To\fR, and so on). Note that the header +key/values supplied by the \fB-header\fR option (not those present +in the MIME part) are consulted. Regardless, header key/values are +added to the outgoing message as necessary to ensure that a valid +822-style message is sent. +.sp +The command returns a list indicating which recipients were +unacceptable to the SMTP server. Each element of the list is another +list, containing the address, an SMTP error code, and a textual +diagnostic. Depending on the \fB-atleastone\fR option and the +intended recipients, a non-empty list may still indicate that the +message was accepted by the server. +.PP +.SH AUTHENTICATION +Beware. SMTP authentication uses \fBSASL\fR. I.e. if the user +has to authenticate a connection, i.e. use the options \fB-user\fR +and \fB-password\fR (see above) it is necessary to have the +\fBsasl\fR package available so that \fBsmtp\fR can load it. +.PP +This is a soft dependency because not everybody requires authentication, +and \fBsasl\fR depends on a lot of the cryptographic (secure) hashes, +i.e. all of \fBmd5\fR, \fBotp\fR, \fBmd4\fR, \fBsha1\fR, +and \fBripemd160\fR. +.SH EXAMPLE +.CS + + +proc send_simple_message {recipient email_server subject body} { + package require smtp + package require mime + + set token [mime::initialize -canonical text/plain \\\\ + -string $body] + mime::setheader $token Subject $subject + smtp::sendmessage $token \\\\ + -recipients $recipient -servers $email_server + mime::finalize $token +} + +send_simple_message someone@somewhere.com localhost \\\\ + "This is the subject." "This is the message." + +.CE +.SH REFERENCES +.IP [1] +Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982. +(\fIhttp://www.rfc-editor.org/rfc/rfc821.txt\fR) +.IP [2] +J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001. +(\fIhttp://www.rfc-editor.org/rfc/rfc2821.txt\fR) +.IP [3] +P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport +Layer Security", RFC 3207, February 2002. +(\fIhttp://www.rfc-editor.org/rfc/rfc3207.txt\fR) +.IP [4] +J. Myers, "SMTP Service Extension for Authentication", +RFC 2554, March 1999. +(\fIhttp://www.rfc-editor.org/rfc/rfc2554.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsmtp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ftp, http, mime, pop3 +.SH KEYWORDS +email, internet, mail, mime, net, rfc 2554, rfc 2821, rfc 3207, rfc 821, rfc 822, smtp, tls +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 1999-2000 Marshall T. Rose and others + +.fi ADDED embedded/man/files/modules/multiplexer/multiplexer.n Index: embedded/man/files/modules/multiplexer/multiplexer.n ================================================================== --- /dev/null +++ embedded/man/files/modules/multiplexer/multiplexer.n @@ -0,0 +1,374 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/multiplexer/multiplexer.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "multiplexer" n 0.2 tcllib "One-to-many communication with sockets." +.BS +.SH NAME +multiplexer \- One-to-many communication with sockets. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBlogger \fR +.sp +package require \fBmultiplexer ?0.2?\fR +.sp +\fB::multiplexer::create\fR +.sp +\fB${multiplexer_instance}::Init\fR \fIport\fR +.sp +\fB${multiplexer_instance}::Config\fR \fIkey\fR \fIvalue\fR +.sp +\fB${multiplexer_instance}::AddFilter\fR \fIcmdprefix\fR +.sp +\fBcmdprefix\fR \fIdata\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +.sp +\fB${multiplexer_instance}::AddAccessFilter\fR \fIcmdprefix\fR +.sp +\fBcmdprefix\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +.sp +\fB${multiplexer_instance}::AddExitFilter\fR \fIcmdprefix\fR +.sp +\fBcmdprefix\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +.sp +.BE +.SH DESCRIPTION +The \fBmultiplexer\fR package provides a generic system for one-to-many +communication utilizing sockets. For example, think of a chat system +where one user sends a message which is then broadcast to all the +other connected users. +.PP +It is possible to have different multiplexers running concurrently. +.TP +\fB::multiplexer::create\fR +The \fBcreate\fR command creates a new multiplexer 'instance'. For +example: +.CS + +set mp [::multiplexer::create] +.CE +.IP +This instance can then be manipulated like so: +.CS + +${mp}::Init 35100 +.CE +.TP +\fB${multiplexer_instance}::Init\fR \fIport\fR +This starts the multiplexer listening on the specified port. +.TP +\fB${multiplexer_instance}::Config\fR \fIkey\fR \fIvalue\fR +Use \fBConfig\fR to configure the multiplexer instance. Configuration +options currently include: +.RS +.TP +\fBsendtoorigin\fR +A boolean flag. If \fBtrue\fR, the sender will receive a copy of the +sent message. Defaults to \fBfalse\fR. +.TP +\fBdebuglevel\fR +Sets the debug level to use for the multiplexer instance, according to +those specified by the \fBlogger\fR package (debug, info, notice, +warn, error, critical). +.RE +.TP +\fB${multiplexer_instance}::AddFilter\fR \fIcmdprefix\fR +Command to add a filter for data that passes through the multiplexer +instance. +The registered \fIcmdprefix\fR is called when data arrives at a +multiplexer instance. If there is more than one filter command +registered at the instance they will be called in the order of +registristation, and each filter will get the result of the preceding +filter as its argument. The first filter gets the incoming data as its +argument. The result returned by the last filter is the data which +will be broadcast to all clients of the multiplexer instance. +The command prefix is called as +.RS +.TP +\fBcmdprefix\fR \fIdata\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +Takes the incoming \fIdata\fR, modifies it, and returns that as its +result. The last three arguments contain information about the client +which sent the data to filter: The channel connecting us to the +client, its ip-address, and its ip-port. +.RE +.TP +\fB${multiplexer_instance}::AddAccessFilter\fR \fIcmdprefix\fR +Command to add an access filter. +The registered \fIcmdprefix\fR is called when a new client socket +tries to connect to the multixer instance. If there is more than one +access filter command registered at the instance they will be called +in the order of registristation. If any of the called commands returns +\fB-1\fR the access to the multiplexer instance is denied and the +client channel is closed immediately. Any other result grants the +client access to the multiplexer instance. +The command prefix is called as +.RS +.TP +\fBcmdprefix\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +The arguments contain information about the client which tries to +connected to the instance: The channel connecting us to the client, +its ip-address, and its ip-port. +.RE +.TP +\fB${multiplexer_instance}::AddExitFilter\fR \fIcmdprefix\fR +Adds filter to be run when client socket generates an EOF condition. +The registered \fIcmdprefix\fR is called when a client socket of the +multixer signals EOF. If there is more than one exit filter command +registered at the instance they will be called in the order of +registristation. Errors thrown by an exit filter are ignored, but +logged. Any result returned by an exit filter is ignored. +The command prefix is called as +.RS +.TP +\fBcmdprefix\fR \fIchan\fR \fIclientaddress\fR \fIclientport\fR +The arguments contain information about the client which signaled the +EOF: The channel connecting us to the client, its ip-address, and its +ip-port. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fImultiplexer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +chat, multiplexer +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/namespacex/namespacex.n Index: embedded/man/files/modules/namespacex/namespacex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/namespacex/namespacex.n @@ -0,0 +1,326 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/namespacex/namespacex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 200? Neil Madden (http://wiki.tcl.tk/12790) +'\" Copyright (c) 200? Various (http://wiki.tcl.tk/1489) +'\" Copyright (c) 2010 Documentation, Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "namespacex" n 0.1 tcllib "Namespace utility commands" +.BS +.SH NAME +namespacex \- Namespace utility commands +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBnamespacex ?0.1?\fR +.sp +\fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR +.sp +\fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR +.sp +\fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR +.sp +\fB::namespacex hook next\fR \fIarg\fR... +.sp +\fB::namespacex info allchildren\fR \fInamespace\fR +.sp +\fB::namespacex info allvars\fR \fInamespace\fR +.sp +\fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR? +.sp +\fB::namespacex state get\fR \fInamespace\fR +.sp +\fB::namespacex state set\fR \fInamespace\fR \fIdict\fR +.sp +\fB::namespacex state drop\fR \fInamespace\fR +.sp +.BE +.SH DESCRIPTION +This package provides a number of utility commands for working with +namespaces. +.SH API +.TP +\fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR +.TP +\fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR +.TP +\fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR +.TP +\fB::namespacex hook next\fR \fIarg\fR... +.TP +\fB::namespacex info allchildren\fR \fInamespace\fR +This command returns a list containing the names of all child +namespaces in the specified \fInamespace\fR and its children. The +names are all fully qualified. +.TP +\fB::namespacex info allvars\fR \fInamespace\fR +This command returns a list containing the names of all variables in +the specified \fInamespace\fR and its children. The names are all +relative to \fInamespace\fR, and \fInot\fR fully qualified. +.TP +\fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR? +This command returns a list containing the names of all variables in +the specified \fInamespace\fR. +.TP +\fB::namespacex state get\fR \fInamespace\fR +This command returns a dictionary holding the names and values of all +variables in the specified \fInamespace\fR and its child namespaces. +.sp +Note that the names are all relative to \fInamespace\fR, +and \fInot\fR fully qualified. +.TP +\fB::namespacex state set\fR \fInamespace\fR \fIdict\fR +This command takes a dictionary holding the names and values for a set +of variables and replaces the current state of the specified +\fInamespace\fR and its child namespaces with this state. +The result of the command is the empty string. +.TP +\fB::namespacex state drop\fR \fInamespace\fR +This command unsets all variables in the specified \fInamespace\fR and +its child namespaces. +The result of the command is the empty string. +.PP +.SH KEYWORDS +extended namespace, info, namespace unknown, namespace utilities, state (de)serialization, unknown hooking, utilities +.SH COPYRIGHT +.nf +Copyright (c) 200? Neil Madden (http://wiki.tcl.tk/12790) +Copyright (c) 200? Various (http://wiki.tcl.tk/1489) +Copyright (c) 2010 Documentation, Andreas Kupries + +.fi ADDED embedded/man/files/modules/ncgi/ncgi.n Index: embedded/man/files/modules/ncgi/ncgi.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ncgi/ncgi.n @@ -0,0 +1,559 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ncgi/ncgi.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ncgi" n 1.4.1 tcllib "CGI Support" +.BS +.SH NAME +ncgi \- Procedures to manipulate CGI values. +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBncgi ?1.4.1?\fR +.sp +\fB::ncgi::cookie\fR \fIcookie\fR +.sp +\fB::ncgi::decode\fR \fIstr\fR +.sp +\fB::ncgi::empty\fR \fIname\fR +.sp +\fB::ncgi::exists\fR \fIname\fR +.sp +\fB::ncgi::encode\fR \fIstring\fR +.sp +\fB::ncgi::header\fR ?\fItype\fR? \fIargs\fR +.sp +\fB::ncgi::import\fR \fIcginame\fR ?\fItclname\fR? +.sp +\fB::ncgi::importAll\fR \fIargs\fR +.sp +\fB::ncgi::importFile\fR \fIcmd\fR \fIcginame\fR ?\fIfilename\fR? +.sp +\fB::ncgi::input\fR ?\fIfakeinput\fR? ?\fIfakecookie\fR? +.sp +\fB::ncgi::multipart\fR \fItype query\fR +.sp +\fB::ncgi::nvlist\fR +.sp +\fB::ncgi::names\fR +.sp +\fB::ncgi::parse\fR +.sp +\fB::ncgi::parseMimeValue\fR \fIvalue\fR +.sp +\fB::ncgi::query\fR +.sp +\fB::ncgi::redirect\fR \fIurl\fR +.sp +\fB::ncgi::reset\fR \fIquery type\fR +.sp +\fB::ncgi::setCookie\fR \fIargs\fR +.sp +\fB::ncgi::setDefaultValue\fR \fIkey defvalue\fR +.sp +\fB::ncgi::setDefaultValueList\fR \fIkey defvaluelist\fR +.sp +\fB::ncgi::setValue\fR \fIkey value\fR +.sp +\fB::ncgi::setValueList\fR \fIkey valuelist\fR +.sp +\fB::ncgi::type\fR +.sp +\fB::ncgi::urlStub\fR ?\fIurl\fR? +.sp +\fB::ncgi::value\fR \fIkey\fR ?\fIdefault\fR? +.sp +\fB::ncgi::valueList\fR \fIkey\fR ?\fIdefault\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBncgi\fR package provides commands that manipulate CGI +values. These are values that come from Web forms and are processed +either by CGI scripts or web pages with embedded Tcl code. Use the +\fBncgi\fR package to query these values, set and get cookies, and +encode and decode www-url-encoded values. +.PP +In the simplest case, a CGI script first calls \fB::ncgi::parse\fR and +then calls \fB::ncgi::value\fR to get different form values. If a CGI +value is repeated, you should use \fB::ncgi::valueList\fR to get back +the complete list of values. +.PP +An alternative to \fB::ncgi::parse\fR is \fB::ncgi::input\fR, which +has semantics similar to Don Libes' \fBcgi_input\fR procedure. +\fB::ncgi::input\fR restricts repeated CGI values to have names that +end with "List". In this case, \fB::ncgi::value\fR will return the +complete list of values, and \fB::ncgi::input\fR will raise errors if +it find repeated form elements without the right name. +.PP +The \fB::ncgi::reset\fR procedure can be used in test suites and Web +servers to initialize the source of the CGI values. Otherwise the +values are read in from the CGI environment. +.PP +The complete set of procedures is described below. +.TP +\fB::ncgi::cookie\fR \fIcookie\fR +Return a list of values for \fIcookie\fR, if any. It is possible that +more than one cookie with the same name can be present, so this +procedure returns a list. +.TP +\fB::ncgi::decode\fR \fIstr\fR +Decode strings in www-url-encoding, which represents special +characters with a %xx sequence, where xx is the character code in hex. +.TP +\fB::ncgi::empty\fR \fIname\fR +Returns 1 if the CGI variable \fIname\fR is not present or has the +empty string as its value. +.TP +\fB::ncgi::exists\fR \fIname\fR +The return value is a boolean. It returns \fB0\fR if the CGI +variable \fIname\fR is not present, and \fB1\fR otherwise. +.TP +\fB::ncgi::encode\fR \fIstring\fR +Encode \fIstring\fR into www-url-encoded format. +.TP +\fB::ncgi::header\fR ?\fItype\fR? \fIargs\fR +Output the CGI header to standard output. This emits a Content-Type: +header and additional headers based on \fIargs\fR, which is a list of +header names and header values. The \fItype\fR defaults to +"text/html". +.TP +\fB::ncgi::import\fR \fIcginame\fR ?\fItclname\fR? +This creates a variable in the current scope with the value of the CGI +variable \fIcginame\fR. The name of the variable is \fItclname\fR, or +\fIcginame\fR if \fItclname\fR is empty (default). +.TP +\fB::ncgi::importAll\fR \fIargs\fR +This imports several CGI variables as Tcl variables. If \fIargs\fR is +empty, then every CGI value is imported. Otherwise each CGI variable +listed in \fIargs\fR is imported. +.TP +\fB::ncgi::importFile\fR \fIcmd\fR \fIcginame\fR ?\fIfilename\fR? +This provides information about an uploaded file from a form input +field of type \fBfile\fR with name \fIcginame\fR. \fIcmd\fR can be +one of \fB-server\fR \fB-client\fR, \fB-type\fR or +\fB-data\fR. +.RS +.TP +\fB-client\fR \fIcginame\fR +returns the filename as sent by the client. +.TP +\fB-type\fR \fIcginame\fR +returns the mime type of the uploaded file. +.TP +\fB-data\fR \fIcginame\fR +returns the contents of the file. +.TP +\fB-server\fR \fIcginame\fR \fIfilename\fR +writes the file contents to a local temporary file (or \fIfilename\fR +if supplied) and returns the name of the file. The caller is +responsible for deleting this file after use. +.RE +.TP +\fB::ncgi::input\fR ?\fIfakeinput\fR? ?\fIfakecookie\fR? +This reads and decodes the CGI values from the environment. It +restricts repeated form values to have a trailing "List" in their +name. The CGI values are obtained later with the \fB::ncgi::value\fR +procedure. +.TP +\fB::ncgi::multipart\fR \fItype query\fR +This procedure parses a multipart/form-data \fIquery\fR. This is used +by \fB::ncgi::nvlist\fR and not normally called directly. It returns +an alternating list of names and structured values. Each structure +value is in turn a list of two elements. The first element is +meta-data from the multipart/form-data structure. The second element +is the form value. If you use \fB::ncgi::value\fR you just get the +form value. If you use \fB::ncgi::valueList\fR you get the structured +value with meta data and the value. +.sp +The \fItype\fR is the whole Content-Type, including the parameters +like \fIboundary\fR. This returns a list of names and values that +describe the multipart data. The values are a nested list structure +that has some descriptive information first, and the actual form value +second. The descriptive information is list of header names and +values that describe the content. +.TP +\fB::ncgi::nvlist\fR +This returns all the query data as a name, value list. In the case of +multipart/form-data, the values are structured as described in +\fB::ncgi::multipart\fR. +.TP +\fB::ncgi::names\fR +This returns all names found in the query data, as a list. +\fB::ncgi::multipart\fR. +.TP +\fB::ncgi::parse\fR +This reads and decodes the CGI values from the environment. The CGI +values are obtained later with the \fB::ncgi::value\fR procedure. IF +a CGI value is repeated, then you should use \fB::ncgi::valueList\fR +to get the complete list of values. +.TP +\fB::ncgi::parseMimeValue\fR \fIvalue\fR +This decodes the Content-Type and other MIME headers that have the +form of "primary value; param=val; p2=v2" It returns a list, where the +first element is the primary value, and the second element is a list +of parameter names and values. +.TP +\fB::ncgi::query\fR +This returns the raw query data. +.TP +\fB::ncgi::redirect\fR \fIurl\fR +Generate a response that causes a 302 redirect by the Web server. The +\fIurl\fR is the new URL that is the target of the redirect. The URL +will be qualified with the current server and current directory, if +necessary, to convert it into a full URL. +.TP +\fB::ncgi::reset\fR \fIquery type\fR +Set the query data and Content-Type for the current CGI session. This +is used by the test suite and by Web servers to initialize the ncgi +module so it does not try to read standard input or use environment +variables to get its data. If neither \fIquery\fR or \fItype\fR are +specified, then the \fBncgi\fR module will look in the standard +CGI environment for its data. +.TP +\fB::ncgi::setCookie\fR \fIargs\fR +Set a cookie value that will be returned as part of the reply. This +must be done before \fB::ncgi::header\fR or \fB::ncgi::redirect\fR is +called in order for the cookie to be returned properly. The +\fIargs\fR are a set of flags and values: +.RS +.TP +\fB-name\fR \fIname\fR +.TP +\fB-value\fR \fIvalue\fR +.TP +\fB-expires\fR \fIdate\fR +.TP +\fB-path\fR \fIpath restriction\fR +.TP +\fB-domain\fR \fIdomain restriction\fR +.RE +.TP +\fB::ncgi::setDefaultValue\fR \fIkey defvalue\fR +Set a CGI value if it does not already exists. This affects future +calls to \fB::ncgi::value\fR (but not future calls to +\fB::ncgi::nvlist\fR). If the CGI value already is present, then this +procedure has no side effects. +.TP +\fB::ncgi::setDefaultValueList\fR \fIkey defvaluelist\fR +Like \fB::ncgi::setDefaultValue\fR except that the value already has +list structure to represent multiple checkboxes or a multi-selection. +.TP +\fB::ncgi::setValue\fR \fIkey value\fR +Set a CGI value, overriding whatever was present in the CGI +environment already. This affects future calls to \fB::ncgi::value\fR +(but not future calls to \fB::ncgi::nvlist\fR). +.TP +\fB::ncgi::setValueList\fR \fIkey valuelist\fR +Like \fB::ncgi::setValue\fR except that the value already has list +structure to represent multiple checkboxes or a multi-selection. +.TP +\fB::ncgi::type\fR +Returns the Content-Type of the current CGI values. +.TP +\fB::ncgi::urlStub\fR ?\fIurl\fR? +Returns the current URL, but without the protocol, server, and port. +If \fIurl\fR is specified, then it defines the URL for the current +session. That value will be returned by future calls to +\fB::ncgi::urlStub\fR +.TP +\fB::ncgi::value\fR \fIkey\fR ?\fIdefault\fR? +Return the CGI value identified by \fIkey\fR. If the CGI value is not +present, then the \fIdefault\fR value is returned instead. This value +defaults to the empty string. +.sp +If the form value \fIkey\fR is repeated, then there are two cases: if +\fB::ncgi::parse\fR was called, then \fB::ncgi::value\fR only returns +the first value associated with \fIkey\fR. If \fB::ncgi::input\fR was +called, then \fB::ncgi::value\fR returns a Tcl list value and +\fIkey\fR must end in "List" (e.g., "skuList"). In the case of +multipart/form-data, this procedure just returns the value of the form +element. If you want the meta-data associated with each form value, +then use \fB::ncgi::valueList\fR. +.TP +\fB::ncgi::valueList\fR \fIkey\fR ?\fIdefault\fR? +Like \fB::ncgi::value\fR, but this always returns a list of values +(even if there is only one value). In the case of +multipart/form-data, this procedure returns a list of two elements. +The first element is meta-data in the form of a parameter, value list. +The second element is the form value. +.PP +.SH EXAMPLES +Uploading a file +.CS + + +HTML: +<html> +<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data"> +Path: <input type="file" name="filedata"><br> +Name: <input type="text" name="filedesc"><br> +<input type="submit"> +</form> +</html> + +TCL: upload.cgi +#!/usr/local/bin/tclsh + +::ncgi::parse +set filedata [::ncgi::value filedata] +set filedesc [::ncgi::value filedesc] + +puts "<html> File uploaded at <a href=\\"/images/$filedesc\\">$filedesc</a> </html>" + +set filename /www/images/$filedesc + +set fh [open $filename w] +puts -nonewline $fh $filedata +close $fh + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIncgi\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +html +.SH KEYWORDS +CGI, cookie, form, html +.SH CATEGORY +CGI programming ADDED embedded/man/files/modules/nmea/nmea.n Index: embedded/man/files/modules/nmea/nmea.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nmea/nmea.n @@ -0,0 +1,379 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nmea/nmea.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009, Aaron Faupell <afaupell@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nmea" n 1.0.0 tcllib "NMEA protocol implementation" +.BS +.SH NAME +nmea \- Process NMEA data +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBnmea ?1.0.0?\fR +.sp +\fB::nmea::input\fR \fIsentence\fR +.sp +\fB::nmea::open_port\fR \fIport\fR ?speed? +.sp +\fB::nmea::close_port\fR +.sp +\fB::nmea::configure_port\fR \fIsettings\fR +.sp +\fB::nmea::open_file\fR \fIfile\fR ?rate? +.sp +\fB::nmea::close_file\fR +.sp +\fB::nmea::do_line\fR +.sp +\fB::nmea::rate\fR +.sp +\fB::nmea::log\fR ?file? +.sp +\fB::nmea::checksum\fR \fIdata\fR +.sp +\fB::nmea::write\fR \fIsentence\fR \fIdata\fR +.sp +\fB::nmea::event\fR \fIsetence\fR ?command? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a standard interface for writing software which recieves +NMEA standard input data. It allows for reading data from COM ports, files, +or programmatic input. It also supports the checksumming and logging of incoming data. +After parsing, input is dispatched to user defined handler commands for processing. +To define a handler, see the \fBevent\fR command. There are no GPS specific functions +in this package. NMEA data consists of a sentence type, followed by a list of data. +.SH COMMANDS +.TP +\fB::nmea::input\fR \fIsentence\fR +Processes and dispatches the supplied sentence. If \fIsentence\fR contains no commas it is treated as a Tcl list, otherwise it must be standard comma delimited NMEA data, with an optional checksum and leading \fB$\fR. +.CS + + +nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39} +nmea::input [list GPGSA A 3 04 05 09 12 "" "" 24 "" "" "" 2.5 1.3 2.1] + +.CE +.TP +\fB::nmea::open_port\fR \fIport\fR ?speed? +Open the specified COM port and read NMEA sentences when available. Port speed is set to +4800bps by default or to \fIspeed\fR. +.TP +\fB::nmea::close_port\fR +Close the com port connection if one is open. +.TP +\fB::nmea::configure_port\fR \fIsettings\fR +Changes the current port settings. \fIsettings\fR has the same format as fconfigure -mode. +.TP +\fB::nmea::open_file\fR \fIfile\fR ?rate? +Open file \fIfile\fR and read NMEA sentences, one per line, at the rate specified by ?rate? in milliseconds. +The file format may omit the leading \fB$\fR and/or the checksum. If rate is <= 0 (the default) then lines +will only be processed when a call to \fBdo_line\fR is made. +.TP +\fB::nmea::close_file\fR +Close the open file if one exists. +.TP +\fB::nmea::do_line\fR +If there is a currently open file, this command will read and process a single line from it. +Returns the number of lines read. +.TP +\fB::nmea::rate\fR +Sets the rate at which lines are processed from the open file, in milliseconds. The rate remains +consistant across files, there does not need to be a file currently open to use this command. +Set to 0 to disable automatic line processing. +.TP +\fB::nmea::log\fR ?file? +Starts or stops input logging. If a file name is specified then all NMEA data recieved on +the open port will be logged to the ?file? in append mode. If file is an empty string then +any logging will be stopped. If no file is specified then returns a boolean value indicating +if logging is currently enabled. Data written to the port by \fBwrite\fR, +data read from files, or input made using \fBinput\fR, is not logged. +.TP +\fB::nmea::checksum\fR \fIdata\fR +Returns the checksum of the supplied data. +.TP +\fB::nmea::write\fR \fIsentence\fR \fIdata\fR +If there is a currently open port, this command will write the specified sentence and data to the port +in proper NMEA checksummed format. +.TP +\fB::nmea::event\fR \fIsetence\fR ?command? +Registers a handler proc for a given NMEA \fIsentence\fR. There may be at most one handler per +sentence, any existing handler is replaced. +If no command is specified, returns the name of the current handler for the given \fIsetence\fR +or an empty string if none exists. In addition to the incoming sentences there are 2 builtin types, +EOF and DEFAULT. The handler for the DEFAULT setence is invoked if there is not a specific handler +for that sentence. The EOF handler is invoked when End Of File is reached on the open file or port. +.sp +The handler procedures, with the exception of the builtin types,must take exactly one argument, +which is a list of the data values. +The DEFAULT handler should have two arguments, the sentence type and the data values. +The EOF handler has no arguments. +.CS + + +nmea::event gpgsa parse_sat_detail +nmea::event default handle_unknown + +proc parse_sat_detail {data} { + puts [lindex $data 1] +} + +proc handle_unknown {name data} { + puts "unknown data type $name" +} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInmea\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +gps, nmea +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009, Aaron Faupell <afaupell@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_auto.n Index: embedded/man/files/modules/nns/nns_auto.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_auto.n @@ -0,0 +1,341 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_auto.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nameserv::auto" n 0.3 tcllib "Name service facility" +.BS +.SH NAME +nameserv::auto \- Name service facility, Client Extension +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBnameserv::auto ?0.3?\fR +.sp +package require \fBnameserv \fR +.sp +.BE +.SH DESCRIPTION +Please read the document \fIName service facility, introduction\fR +first. +.PP +This package provides the \fIexact\fR same API as is provided by +package \fBnameserv\fR, i.e the regular name service client. It +differs from the former by taking measures to ensure that longer-lived +data, i.e. bound names, continuous and unfulfilled async searches, +survive the loss of the connection to the name server as much as is +possible. +.PP +This means that the bound names and continuous and unfulfilled async +searches are remembered client-side and automatically re-entered into +the server when the connection comes back after its loss. For bound +names there is one important limitation to such restoration: It is +possible that a name of this client was bound by a different client +while the connection was gone. Such names are fully lost, and the best +the package can and will do is to inform the user of this. +.SH API +The user-visible API is mainly identical the API of \fBnameserv\fR +and is therefore not described here. Please read the documentation of +\fBnameserv\fR. +.PP +The differences are explained in the sections \fBOPTIONS\fR and +\fBEVENTS\fR. +.SH OPTIONS +This package supports all the option of package \fBnameserv\fR, +and one more. The additional option allows the user to specifies the +time interval between attempts to restore a lost connection. +.TP +\fB-delay\fR \fImilliseconds\fR +The value of this option is an integer value > 0 which specifies the +interval to wait between attempts to restore a lost connection, in +milliseconds. The default value is \fB1000\fR, i.e. one second. +.PP +.SH EVENTS +This package generates all of the events of package \fBnameserv\fR, +and two more. Both events are generated for the tag \fInameserv\fR. +.TP +\fIlost-name\fR +This event is generated when a bound name is truly lost, i.e. could +not be restored after the temporary loss of the connection to the name +server. It indicates that a different client took ownership of the +name while this client was out of contact. +.sp +The detail information of the event will be a Tcl dictionary +containing two keys, \fBname\fR, and \fBdata\fR. Their values hold +all the information about the lost name. +.TP +\fIre-connection\fR +This event is generated when the connection to the server is +restored. The remembered data has been restored when the event is +posted. +.sp +The event has no detail information. +.PP +.SH DESIGN +The package is implemented on top of the regular nameservice client, +i.e. package \fBnameserv\fR. It detects the loss of the +connection by listening for \fIlost-connection\fR events, on the tag +\fInameserv\fR. +.PP +It reacts to such events by starting a periodic timer and trying to +reconnect to the server whenver this timer triggers. On success the +timer is canceled, a \fIre-connection\fR event generated, and the +package proceeds to re-enter the remembered bound names and continous +searches. +.PP +Another loss of the connection, be it during or after re-entering the +remembered information simply restarts the timer and subsequent +reconnection attempts. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +nameserv(n) +.SH KEYWORDS +automatic, client, name service, reconnect, restore +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_client.n Index: embedded/man/files/modules/nns/nns_client.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_client.n @@ -0,0 +1,556 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_client.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nameserv" n 0.4.2 tcllib "Name service facility" +.BS +.SH NAME +nameserv \- Name service facility, Client +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBnameserv ?0.4.2?\fR +.sp +package require \fBcomm \fR +.sp +package require \fBlogger \fR +.sp +\fB::nameserv::bind\fR \fIname\fR \fIdata\fR +.sp +\fB::nameserv::release\fR +.sp +\fB::nameserv::search\fR ?\fB-async\fR|\fB-continuous\fR? ?\fIpattern\fR? +.sp +\fB::nameserv::protocol\fR +.sp +\fB::nameserv::server_protocol\fR +.sp +\fB::nameserv::server_features\fR +.sp +\fB::nameserv::cget\fR \fB-option\fR +.sp +\fB::nameserv::configure\fR +.sp +\fB::nameserv::configure\fR \fB-option\fR +.sp +\fB::nameserv::configure\fR \fB-option\fR \fIvalue\fR... +.sp +\fB$result\fR \fBdestroy\fR +.sp +\fB$result\fR \fBfilled\fR +.sp +\fB$result\fR \fBget\fR \fIname\fR +.sp +\fB$result\fR \fBnames\fR +.sp +\fB$result\fR \fBsize\fR +.sp +\fB$result\fR \fBgetall\fR ?\fIpattern\fR? +.sp +.BE +.SH DESCRIPTION +Please read \fIName service facility, introduction\fR first. +.PP +This package provides a client for the name service facility +implemented by the package \fBnameserv::server\fR. +.PP +This service is built in top of and for the package \fBcomm\fR. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages \fBdns\fR and \fBresolv\fR. +.SH API +The package exports eight commands, as specified below: +.TP +\fB::nameserv::bind\fR \fIname\fR \fIdata\fR +The caller of this command registers the given \fIname\fR as its name +in the configured name service, and additionally associates a piece of +\fIdata\fR with it. The service does nothing with this information +beyond storing it and delivering it as part of search results. The +meaning is entirely up to the applications using the name service. +.sp +A generally useful choice would for example be an identifier for a +communication endpoint managed by the package \fBcomm\fR. Anybody +retrieving the name becomes immediately able to talk to this endpoint, +i.e. the registering application. +.sp +Of further importance is that a caller can register itself under more +than one name, and each name can have its own piece of \fIdata\fR. +.sp +Note that the name service, and thwerefore this command, will throw an +error if the chosen name is already registered. +.TP +\fB::nameserv::release\fR +Invoking this command releases all names (and their data) registered +by all previous calls to \fB::nameserv::bind\fR of this client. Note +that the name service will run this command implicitly when it loses +the connection to this client. +.TP +\fB::nameserv::search\fR ?\fB-async\fR|\fB-continuous\fR? ?\fIpattern\fR? +This command searches the name service for all registered names +matching the specified glob-\fIpattern\fR. If not specified the +pattern defaults to \fB*\fR, matching everything. The result of the +command is a dictionary mapping the matching names to the data +associated with them at \fIbind\fR-time. +.sp +If either option \fB-async\fR or \fB-continuous\fR were +specified the result of this command changes and becomes the Tcl +command of an object holding the actual result. +These two options are supported if and only if the service the client +is connected to supports the protocol feature +\fISearch/Continuous\fR. +.sp +For \fB-async\fR the result object is asynchronously filled with +the entries matching the pattern at the time of the search and then +not modified any more. +The option \fB-continuous\fR extends this behaviour by additionally +continuously monitoring the service for the addition and removal of +entries which match the pattern, and updating the object's contents +appropriately. +.sp +\fINote\fR that the caller is responsible for configuring the object +with a callback for proper notification when the current result (or +further changes) arrive. +.sp +For more information about this object see section +\fBASYNCHRONOUS AND CONTINUOUS SEARCHES\fR. +.TP +\fB::nameserv::protocol\fR +This command returns the highest version of the name service protocol +supported by the package. +.TP +\fB::nameserv::server_protocol\fR +This command returns the highest version of the name service protocol +supported by the name service the client is currently connected to. +.TP +\fB::nameserv::server_features\fR +This command returns a list containing the names of the features of +the name service protocol which are supported by the name service the +client is currently connected to. +.TP +\fB::nameserv::cget\fR \fB-option\fR +This command returns the currently configured value for the specified +\fB-option\fR. The list of supported options and their meaning can +be found in section \fBOPTIONS\fR. +.TP +\fB::nameserv::configure\fR +In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section \fBOPTIONS\fR. +.TP +\fB::nameserv::configure\fR \fB-option\fR +In this form the command is an alias for +"\fB::nameserv::cget\fR \fB-option\fR]". +The list of supported options and their meaning can be found in +section \fBOPTIONS\fR. +.TP +\fB::nameserv::configure\fR \fB-option\fR \fIvalue\fR... +In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section \fBOPTIONS\fR. +.sp +This form can be used only as long as the client has not contacted the +name service yet. After contact has been made reconfiguration is not +possible anymore. This means that this form of the command is for the +initalization of the client before it use. +The command forcing a contact with the name service are +.RS +.TP +\fBbind\fR +.TP +\fBrelease\fR +.TP +\fBsearch\fR +.TP +\fBserver_protocol\fR +.TP +\fBserver_features\fR +.RE +.PP +.SH "CONNECTION HANDLING" +The client automatically connects to the service when one of the +commands below is run for the first time, or whenever one of the +commands is run after the connection was lost, when it was lost. +.PP +.TP +\fBbind\fR +.TP +\fBrelease\fR +.TP +\fBsearch\fR +.TP +\fBserver_protocol\fR +.TP +\fBserver_features\fR +.PP +.PP +Since version 0.2 of the client it will generate an event when the +connection is lost, allowing higher layers to perform additional +actions. This is done via the support package \fBuevent\fR. This +and all other name service related packages hereby reserve the +uevent-tag \fInameserv\fR. All their events will be posted to that +tag. +.SH EVENTS +This package generates only one event, \fIlost-connection\fR. The +detail information provided to that event is a Tcl dictionary. The +only key contained in the dictionnary is \fBreason\fR, and its value +will be a string describing why the connection was lost. +This string is supplied by the underlying communication package, +i.e. \fBcomm\fR. +.SH OPTIONS +The options supported by the client are for the specification of which +name service to contact, i.e. of the location of the name service. +They are: +.TP +\fB-host\fR \fIname\fR|\fIipaddress\fR +This option specifies the host name service to contact is running on, +either by \fIname\fR, or by \fIipaddress\fR. The initial default is +\fBlocalhost\fR, i.e. it is expected to contact a name service +running on the same host as the application using this package. +.TP +\fB-port\fR \fInumber\fR +This option specifies the port the name service to contact is +listening on. It has to be a positive integer number (> 0) not greater +than 65536 (unsigned short). The initial default is the number +returned by the command \fB::nameserv::common::port\fR, as provided by +the package \fB::nameserv::common\fR. +.PP +.SH "ASYNCHRONOUS AND CONTINUOUS SEARCHES" +Asynchronous and continuous searches are invoked by using either +option \fB-async\fR or \fB-continuous\fR as argument to the +command \fB::nameserv::search\fR. +.PP +\fINote\fR that these two options are supported if and only if the +service the client is connected to supports the protocol feature +\fISearch/Continuous\fR. The service provided by the package +\fB::nameserv::server\fR does this since version 0.3. +.PP +For such searches the result of the search command is the Tcl command +of an object holding the actual result. The API provided by these +objects is: +.TP +Options: +.RS +.TP +\fB-command\fR \fIcommand_prefix\fR +This option has to be set if a user of the result object wishes to get +asynchronous notifications when the search result or changes to it +arrive. +.sp +\fINote\fR that while it is possible to poll for the arrival of the +initial search result via the method \fBfilled\fR, and for +subsequent changes by comparing the output of method \fBgetall\fR +against a saved copy, this is not the recommended behaviour. Setting +the \fB-command\fR callback and processing the notifications as +they arrive is much more efficient. +.sp +The \fIcommand_prefix\fR is called with two arguments, the type of +change, and the data of the change. The type is either \fBadd\fR or +\fBremove\fR, indicating new data, or deleted data, respectively. +The data of the change is always a dictionary listing the +added/removed names and their associated data. +.sp +The first change reported for a search is always the set of matching +entries at the time of the search. +.RE +.TP +Methods: +.RS +.TP +\fB$result\fR \fBdestroy\fR +Destroys the object and cancels any continuous monitoring of the +service the object may have had active. +.TP +\fB$result\fR \fBfilled\fR +The result is a boolean value indicating whether the search result has +already arrived (\fBTrue\fR), or not (\fBFalse\fR). +.TP +\fB$result\fR \fBget\fR \fIname\fR +Returns the data associated with the given \fIname\fR at +\fIbind\fR-time. +.TP +\fB$result\fR \fBnames\fR +Returns a list containing all names known to the object at the time of +the invokation. +.TP +\fB$result\fR \fBsize\fR +Returns an integer value specifying the size of the result at the time +of the invokation. +.TP +\fB$result\fR \fBgetall\fR ?\fIpattern\fR? +Returns a dictionary containing the search result at the time of the +invokation, mapping the matching names to the data associated with +them at \fIbind\fR-time. +.RE +.PP +.SH HISTORY +.TP +0.3.1 +Fixed SF Bug 1954771. +.TP +0.3 +Extended the client with the ability to perform asynchronous and +continuous searches. +.TP +0.2 +Extended the client with the ability to generate events when it loses +its connection to the name service. Based on package \fBuevent\fR. +.TP +0.1 +Initial implementation of the client. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +nameserv::common(n), nameserv::server(n) +.SH KEYWORDS +client, name service +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_common.n Index: embedded/man/files/modules/nns/nns_common.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_common.n @@ -0,0 +1,290 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_common.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nameserv::common" n 0.1 tcllib "Name service facility" +.BS +.SH NAME +nameserv::common \- Name service facility, shared definitions +.SH SYNOPSIS +package require \fBTcl 8\fR +.sp +package require \fBnameserv::common ?0.1?\fR +.sp +\fB::nameserv::common::port\fR +.sp +.BE +.SH DESCRIPTION +Please read \fIName service facility, introduction\fR first. +.PP +This package is internal and of no interest to users. It provides the +commands of the name service facility which are shared by the client +and server implemented by the packages \fBnameserv::server\fR and +\fBnameserv\fR (the client). +.PP +This service is built in top of and for the package \fBcomm\fR. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages \fBdns\fR and \fBresolv\fR. +.SH API +The package exports a single command, as specified below: +.TP +\fB::nameserv::common::port\fR +The result returned by the command is the id of the default TCP/IP +port a nameservice server will listen on, and a name service client +will try to connect to. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +nameserv::client(n), nameserv::server(n) +.SH KEYWORDS +client, name service, server +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_intro.n Index: embedded/man/files/modules/nns/nns_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_intro.n @@ -0,0 +1,337 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nns_intro" n 1.0 tcllib "Name service facility" +.BS +.SH NAME +nns_intro \- Name service facility, introduction +.SH DESCRIPTION +.PP +\fInns\fR (short for \fInano nameservice\fR) is a facility built +for the package \fBcomm\fR, adding a simple name service to it. +It is also built on top of \fBcomm\fR, using it for the exchange +of messages between the client and server parts. +.PP +This name service facility has nothing to do with the Internet's +\fIDomain Name System\fR, otherwise known as \fIDNS\fR. If the +reader is looking for a package dealing with that please see either of +the packages \fBdns\fR and \fBresolv\fR, both found in Tcllib +too. +.PP +Tcllib provides 2 applications and 4 packages which are working +together and provide access to the facility at different levels. +.SH APPLICATIONS +The application \fBnnsd\fR provides a simple name server which can +be run by anybody anywhere on their system, as they see fit. +It is also an example on the use of the server-side package +\fBnameserv::server\fR. +.PP +Complementing this server is the \fBnns\fR client application. +A possible, but no very sensible use would be to enter name/port +bindings into a server from a shell script. Not sensible, as shell +scripts normally do not provide a \fBcomm\fR-based service. +.PP +The only case for this to make some sense would be in a shell script +wrapped around a Tcl script FOO which is using comm, to register the +listening port used by FOO. +However even there it would much more sensible to extend FOO to use +the nameservice directly. And in regard on how to that \fBnns\fR +can be used as both example and template. +Beyond that it may also be useful to perform nameservice queries from +shell scripts. +.PP +The third application, \fBnnslog\fR is a stripped down form of the +\fBnns\fR client application. It is reduced to perform a continuous +search for all changes and logs all received events to stdout. +.PP +Both clients use the \fBnameserv::auto\fR package to automatically +hande the loss and restoration of the connection to the server. +.SH PACKAGES +The two main packages implementing the service are \fBnameserv\fR +and \fBnameserv::server\fR, i.e. client and server. The latter has +not much of an API, just enough to start, stop, and configure it. See +the application \fBnnsd\fR on how to use it. +.PP +The basic client, in package \fBnameserv\fR, provides the main API +to manipulate and query the service. An example of its use is the +application \fBnns\fR. +.PP +The second client package, \fBnameserv::auto\fR is API compatible +to the basic client, but provides the additional functionality that it +will automatically restore data like bound names when the connection +to the name service was lost and then reestablished. I.e. it +automatically detects the loss of the server and re-enters the data +when the server comes back. +.PP +The package \fBnameserv::common\fR is of no interest to users. It +is an internal package containing code and definitions common to the +packages \fBnameserv\fR and \fBnameserv::server\fR. +.PP +All packages use the \fBuevent\fR package for the reporting of +special circumstances via events, and reserve the uevent-tag +\fInameserv\fR for their exclusive use. All their events will be +posted to that tag. +.SH INTERNALS +The document \fIName service facility, client/server protocol\fR +specifies the protocol used by the packages \fBnameserv\fR and +\fBnameserv::server\fR to talk to each other. It is of no interest +to users of either the packages or applications. +.PP +Developers wishing to modify and/or extend or to just understand the +internals of the nameservice facility however are strongly advised to +read it. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +Please also report any ideas for enhancements you may have. +.SH "SEE ALSO" +nameserv(n), nameserv::auto(n), nameserv::common(n), nameserv::protocol(n), nameserv::server(n), nnsd(n), nss(n) +.SH KEYWORDS +client, name service, server +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_protocol.n Index: embedded/man/files/modules/nns/nns_protocol.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_protocol.n @@ -0,0 +1,397 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_protocol.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nameserv::protocol" n 0.1 tcllib "Name service facility" +.BS +.SH NAME +nameserv::protocol \- Name service facility, client/server protocol +.SH SYNOPSIS +\fBBind\fR \fIname\fR \fIdata\fR +.sp +\fBRelease\fR +.sp +\fBSearch\fR \fIpattern\fR +.sp +\fBProtocolVersion\fR +.sp +\fBProtocolFeatures\fR +.sp +\fBSearch/Continuous/Start\fR \fItag\fR \fIpattern\fR +.sp +\fBSearch/Continuous/Stop\fR \fItag\fR +.sp +\fBSearch/Continuous/Change\fR \fItag\fR \fBadd\fR|\fBremove\fR \fIresponse\fR +.sp +.BE +.SH DESCRIPTION +The packages \fBnameserv::server\fR, \fBnameserv\fR, and +\fBnameserv::common\fR provide a simple unprotected name service +facility for use in small trusted environments. +.PP +Please read \fIName service facility, introduction\fR first. +.PP +This document contains the specification of the network protocol which +is used by client and server to talk to each other, enabling +implementations of the same protocol in other languages. +.SH "NANO NAME SERVICE PROTOCOL VERSION 1" +This protocol defines the basic set of messages to be supported by a +name service, also called the \fICore\fR feature. +.SS "BASIC LAYER" +The basic communication between client and server is done using the +remote-execution protocol specified by the Tcl package \fBcomm\fR. +The relevant document specifying its on-the-wire protocol can be found +in \fIcomm_wire\fR. +.PP +All the scripts exchanged via this protocol are single commands in +list form and thus can be interpreted as plain messages instead of as +Tcl commands. The commands/messages specified in the next section are +the only commands understood by the server-side. Command and variable +substitutions are not allowed within the messages, i.e. arguments have +to be literal values. +.PP +The protocol is synchronous. I.e. for each message sent a response is +expected, and has to be generated. All messages are sent by the client. +The server does not sent messages, only responses to messages. +.SS "MESSAGE LAYER" +.TP +\fBBind\fR \fIname\fR \fIdata\fR +The client sends this message when it registers itself at the service +with a \fIname\fR and some associated \fIdata\fR. The server has to +send an error response if the \fIname\fR is already in use. Otherwise +the response has to be an empty string. +.sp +The server has to accept multiple names for the same client. +.TP +\fBRelease\fR +The client sends this message to unregister all names it is known +under at the service. The response has to be an empty string, always. +.TP +\fBSearch\fR \fIpattern\fR +The client sends this message to search the service for names matching +the glob-\fIpattern\fR. The response has to be a dictionary containing +the matching names as keys, and mapping them to the data associated +with it at \fBBind\fR-time. +.TP +\fBProtocolVersion\fR +The client sends this message to query the service for the highest +version of the name service protocol it supports. The response has to +be a positive integer number. +.sp +Servers supporting only \fINano Name Service Protocol Version 1\fR +have to return \fB1\fR. +.TP +\fBProtocolFeatures\fR +The client sends this message to query the service for the features of +the name service protocol it supports. The response has to be a +list containing feature names. +.sp +Servers supporting only \fINano Name Service Protocol Version 1\fR +have to return \fB{Core}\fR. +.PP +.SH "NANO NAME SERVICE PROTOCOL EXTENSION: CONTINUOUS SEARCH" +This protocol defines an extended set of messages to be supported by a +name service, also called the \fISearch/Continuous\fR feature. This +feature defines additional messages between client and server, and is +otherwise identical to version 1 of the protocol. See the last section +for the details of our foundation. +.PP +A service supporting this feature has to put the feature name +\fBSearch/Continuous\fR into the list of features returned by the +message \fIProtocolFeatures\fR. +.PP +For this extension the protocol is asynchronous. No direct response is +expected for any of the messages in the extension. Furthermore the +server will start sending messages on its own, instead of only +responses to messages, and the client has to be able to handle these +notifications. +.TP +\fBSearch/Continuous/Start\fR \fItag\fR \fIpattern\fR +The client sends this message to start searching the service for names +matching the glob-\fIpattern\fR. +In contrast to the regular \fISearch\fR request this one asks the +server to continuously monitor the database for the addition and +removal of matching entries and to notify the client of all such +changes. The particular search is identified by the \fItag\fR. +.sp +No direct response is expected, rather the clients expect to be +notified of changes via explicit \fISearch/Continuous/Result\fR +messages generated by the service. +.sp +It is further expected that the \fItag\fR information is passed +unchanged to the \fISearch/Continuous/Result\fR messages. This +tagging of the results enables clients to start multiple searches and +distinguish between the different results. +.TP +\fBSearch/Continuous/Stop\fR \fItag\fR +The client sends this message to stop the continuous search identified +by the \fItag\fR. +.TP +\fBSearch/Continuous/Change\fR \fItag\fR \fBadd\fR|\fBremove\fR \fIresponse\fR +This message is sent by the service to clients with active continuous +searches to transfer found changes. The first such message for a new +continuous search has to contains the current set of matching entries. +.sp +To ensure this a service has to generate an \fBadd\fR-message with +an empty \fIresponse\fR if there were no matching entries at the time. +.sp +The \fIresponse\fR has to be a dictionary containing the matching +names as keys, and mapping them to the data associated with it at +\fBBind\fR-time. +The argument coming before the response tells the client whether the +names in the response were added or removed from the service. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +comm_wire(n), nameserv(n), nameserv::server(n) +.SH KEYWORDS +comm, name service, protocol +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nns/nns_server.n Index: embedded/man/files/modules/nns/nns_server.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nns/nns_server.n @@ -0,0 +1,382 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nns/nns_server.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nameserv::server" n 0.3.2 tcllib "Name service facility" +.BS +.SH NAME +nameserv::server \- Name service facility, Server +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBnameserv::server ?0.3.2?\fR +.sp +package require \fBcomm \fR +.sp +package require \fBinterp \fR +.sp +package require \fBlogger \fR +.sp +\fB::nameserv::server::start\fR +.sp +\fB::nameserv::server::stop\fR +.sp +\fB::nameserv::server::active?\fR +.sp +\fB::nameserv::server::cget\fR \fB-option\fR +.sp +\fB::nameserv::server::configure\fR +.sp +\fB::nameserv::server::configure\fR \fB-option\fR +.sp +\fB::nameserv::server::configure\fR \fB-option\fR \fIvalue\fR... +.sp +.BE +.SH DESCRIPTION +Please read \fIName service facility, introduction\fR first. +.PP +This package provides an implementation of the serviver side of the +name service facility queried by the client provided by the package +\fBnameserv\fR. All information required by the server will be +held in memory. There is no persistent state. +.PP +This service is built in top of and for the package \fBcomm\fR. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages \fBdns\fR and \fBresolv\fR. +.PP +This server supports the \fICore\fR protocol feature, and since +version 0.3 the \fISearch/Continuous\fR feature as well. +.SH API +The package exports five commands, as specified below: +.TP +\fB::nameserv::server::start\fR +This command starts the server and causes it to listen on the +configured port. From now on clients are able to connect and make +requests. The result of the command is the empty string. +.sp +Note that any incoming requests will only be handled if the +application the server is part of does enter an event loop after this +command has been run. +.TP +\fB::nameserv::server::stop\fR +Invoking this command stops the server and releases all information it +had. Existing connections are shut down, and no new connections will +be accepted any longer. The result of the command is the empty string. +.TP +\fB::nameserv::server::active?\fR +This command returns a boolean value indicating the state of the +server. The result will be \fBtrue\fR if the server is active, +i.e. has been started, and \fBfalse\fR otherwise. +.TP +\fB::nameserv::server::cget\fR \fB-option\fR +This command returns the currently configured value for the specified +\fB-option\fR. The list of supported options and their meaning can +be found in section \fBOPTIONS\fR. +.TP +\fB::nameserv::server::configure\fR +In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section \fBOPTIONS\fR. +.TP +\fB::nameserv::server::configure\fR \fB-option\fR +In this form the command is an alias for +"\fB::nameserv::server::cget\fR \fB-option\fR]". +The list of supported options and their meaning can be found in +section \fBOPTIONS\fR. +.TP +\fB::nameserv::server::configure\fR \fB-option\fR \fIvalue\fR... +In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section \fBOPTIONS\fR. +.sp +This form can be used only if the server is not active, i.e. has not +been started yet, or has been stopped. While the server is active it +cannot be reconfigured. +.PP +.SH OPTIONS +The options supported by the server are for the specification of the +TCP port to listen on, and whether to accept non-local connections or +not. +They are: +.TP +\fB-localonly\fR \fIbool\fR +This option specifies whether to accept only local connections +(-localonly 1) or remote connections as well (-localonly 0). The +default is to accept only local connections. +.TP +\fB-port\fR \fInumber\fR +This option specifies the port the name service will listen on after +it has been started. It has to be a positive integer number (> 0) not +greater than 65536 (unsigned short). The initial default is the number +returned by the command \fB::nameserv::server::common::port\fR, as +provided by the package \fB::nameserv::server::common\fR. +.PP +.SH HISTORY +.TP +0.3 +Extended the server with the ability to perform asynchronous and +continuous searches. +.TP +0.2 +Changed name of -local switch to -localonly. +.TP +0.1 +Initial implementation of the server. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInameserv\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +nameserv::client(n), nameserv::common(n) +.SH KEYWORDS +name service, server +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/nntp/nntp.n Index: embedded/man/files/modules/nntp/nntp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/nntp/nntp.n @@ -0,0 +1,612 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/nntp/nntp.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "nntp" n 1.5.1 tcllib "Tcl NNTP Client Library" +.BS +.SH NAME +nntp \- Tcl client for the NNTP protocol +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBnntp ?0.2.1?\fR +.sp +\fB::nntp::nntp\fR ?\fIhost\fR? ?\fIport\fR? ?\fInntpName\fR? +.sp +\fInntpName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fInntpName\fR \fBarticle\fR ?\fImsgid\fR? +.sp +\fInntpName\fR \fBauthinfo\fR ?\fIuser\fR? ?\fIpass\fR? +.sp +\fInntpName\fR \fBbody\fR ?\fImsgid\fR? +.sp +\fInntpName\fR \fBconfigure\fR +.sp +\fInntpName\fR \fBconfigure\fR \fIoption\fR +.sp +\fInntpName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ... +.sp +\fInntpName\fR \fBcget\fR \fIoption\fR +.sp +\fInntpName\fR \fBdate\fR +.sp +\fInntpName\fR \fBgroup\fR ?\fIgroup\fR? +.sp +\fInntpName\fR \fBhead\fR ?\fImsgid\fR? +.sp +\fInntpName\fR \fBhelp\fR +.sp +\fInntpName\fR \fBlast\fR +.sp +\fInntpName\fR \fBlist\fR +.sp +\fInntpName\fR \fBlistgroup\fR ?\fIgroup\fR? +.sp +\fInntpName\fR \fBmode_reader\fR +.sp +\fInntpName\fR \fBnewgroups\fR \fIsince\fR +.sp +\fInntpName\fR \fBnewnews\fR +.sp +\fInntpName\fR \fBnewnews\fR \fIsince\fR +.sp +\fInntpName\fR \fBnewnews\fR \fIgroup\fR ?\fIsince\fR? +.sp +\fInntpName\fR \fBnext\fR +.sp +\fInntpName\fR \fBpost\fR \fIarticle\fR +.sp +\fInntpName\fR \fBslave\fR +.sp +\fInntpName\fR \fBstat\fR ?\fImsgid\fR? +.sp +\fInntpName\fR \fBquit\fR +.sp +\fInntpName\fR \fBxgtitle\fR ?\fIgroup_pattern\fR? +.sp +\fInntpName\fR \fBxhdr\fR \fIfield\fR ?\fIrange\fR? +.sp +\fInntpName\fR \fBxover\fR ?\fIrange\fR? +.sp +\fInntpName\fR \fBxpat\fR \fIfield\fR \fIrange\fR ?\fIpattern_list\fR? +.sp +.BE +.SH DESCRIPTION +The package \fBnntp\fR provides a simple Tcl-only client library +for the NNTP protocol. It works by opening the standard NNTP socket +on the server, and then providing a Tcl API to access the NNTP +protocol commands. All server errors are returned as Tcl errors +(thrown) which must be caught with the Tcl \fBcatch\fR command. +.SH COMMANDS +.TP +\fB::nntp::nntp\fR ?\fIhost\fR? ?\fIport\fR? ?\fInntpName\fR? +The command opens a socket connection to the specified NNTP server and +creates a new nntp object with an associated global Tcl command whose +name is \fInntpName\fR. This command may be used to access the various +NNTP protocol commands for the new connection. The default \fIport\fR +number is "119" and the default \fIhost\fR is "news". These defaults +can be overridden with the environment variables \fBNNTPPORT\fR and +\fBNNTPHOST\fR respectively. +.sp +Some of the commands supported by this package are not part of the +nntp rfc 977 (\fIhttp://www.rfc-editor.org/rfc/rfc977.txt\fR) and will +not be available (or implemented) on all nntp servers. +.sp +The access command \fInntpName\fR has the following general form: +.RS +.TP +\fInntpName\fR \fBmethod\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.TP +\fInntpName\fR \fBarticle\fR ?\fImsgid\fR? +Query the server for article \fImsgid\fR from the current group. The article +is returned as a valid tcl list which contains the headers, followed by +a blank line, and then followed by the body of the article. Each element +in the list is one line of the article. +.TP +\fInntpName\fR \fBauthinfo\fR ?\fIuser\fR? ?\fIpass\fR? +Send authentication information (username and password) to the server. +.TP +\fInntpName\fR \fBbody\fR ?\fImsgid\fR? +Query the server for the body of the article \fImsgid\fR from the current +group. The body of the article is returned as a valid tcl list. Each element +in the list is one line of the body of the article. +.TP +\fInntpName\fR \fBconfigure\fR +.TP +\fInntpName\fR \fBconfigure\fR \fIoption\fR +.TP +\fInntpName\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR ... +.TP +\fInntpName\fR \fBcget\fR \fIoption\fR +Query and configure options of the nntp connection object. Currently +only one option is supported, \fB-binary\fR. When set articles are +retrieved as binary data instead of text. The only methods affected by +this are \fBarticle\fR and \fBbody\fR. +.sp +One application of this option would be the download of articles +containing yEnc encoded images. Although encoded the data is still +mostly binary and retrieving it as text will corrupt the information. +.sp +See package \fByencode\fR for both encoder and decoder of such data. +.TP +\fInntpName\fR \fBdate\fR +Query the server for the servers current date. The date is returned in the +format \fIYYYYMMDDHHMMSS\fR. +.TP +\fInntpName\fR \fBgroup\fR ?\fIgroup\fR? +Optionally set the current group, and retrieve information about the +currently selected group. Returns the estimated number of articles in +the group followed by the number of the first article in the group, followed +by the last article in the group, followed by the name of the group. +.TP +\fInntpName\fR \fBhead\fR ?\fImsgid\fR? +Query the server for the headers of the article \fImsgid\fR from the current +group. The headers of the article are returned as a valid tcl list. Each element +in the list is one line of the headers of the article. +.TP +\fInntpName\fR \fBhelp\fR +Retrieves a list of the commands that are supported by the news server that +is currently attached to. +.TP +\fInntpName\fR \fBlast\fR +Sets the current article pointer to point to the previous message (if there is +one) and returns the msgid of that message. +.TP +\fInntpName\fR \fBlist\fR +Returns a tcl list of valid newsgroups and associated information. Each +newsgroup is returned as an element in the tcl list with the following format: +.CS + + + group last first p + +.CE +.IP +where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n'). +.sp +The <first> and <last> fields will always be numeric. They may have +leading zeros. If the <last> field evaluates to less than the +<first> field, there are no articles currently on file in the +newsgroup. +.TP +\fInntpName\fR \fBlistgroup\fR ?\fIgroup\fR? +Query the server for a list of all the messages (message numbers) in the +group specified by the argument \fIgroup\fR or by the current group if +the \fIgroup\fR argument was not passed. +.TP +\fInntpName\fR \fBmode_reader\fR +Query the server for its nntp 'MODE READER' response string. +.TP +\fInntpName\fR \fBnewgroups\fR \fIsince\fR +Query the server for a list of all the new newsgroups created since the time +specified by the argument \fIsince\fR. The argument \fIsince\fR can be any +time string that is understood by \fBclock scan\fR. The tcl list of newsgroups +is returned in a similar form to the list of groups returned by the +\fBnntpName list\fR command. Each element of the list has the form: +.CS + + + group last first p + +.CE +.IP +where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n'). +.TP +\fInntpName\fR \fBnewnews\fR +Query the server for a list of new articles posted to the current group in the +last day. +.TP +\fInntpName\fR \fBnewnews\fR \fIsince\fR +Query the server for a list of new articles posted to the current group since +the time specified by the argument \fIsince\fR. The argument \fIsince\fR can +be any time string that is understood by \fBclock scan\fR. +.TP +\fInntpName\fR \fBnewnews\fR \fIgroup\fR ?\fIsince\fR? +Query the server for a list of new articles posted to the group specified by +the argument \fIgroup\fR since the time specified by the argument \fIsince\fR +(or in the past day if no \fIsince\fR argument is passed. The argument +\fIsince\fR can be any time string that is understood by \fBclock scan\fR. +.TP +\fInntpName\fR \fBnext\fR +Sets the current article pointer to point to the next message (if there is +one) and returns the msgid of that message. +.TP +\fInntpName\fR \fBpost\fR \fIarticle\fR +Posts an article of the form specified in +RFC 1036 (\fIhttp://www.rfc-editor.org/rfc/rfc1036.txt\fR, successor +to RFC 850) to the current news group. +.TP +\fInntpName\fR \fBslave\fR +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. +.TP +\fInntpName\fR \fBstat\fR ?\fImsgid\fR? +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" +.TP +\fInntpName\fR \fBquit\fR +Gracefully close the connection after sending a NNTP QUIT command down +the socket. +.TP +\fInntpName\fR \fBxgtitle\fR ?\fIgroup_pattern\fR? +Returns a tcl list where each element is of the form: +.CS + + +newsgroup description + +.CE +.IP +If a \fIgroup_pattern\fR is specified then only newsgroups that match +the pattern will have their name and description returned. +.TP +\fInntpName\fR \fBxhdr\fR \fIfield\fR ?\fIrange\fR? +Returns the specified header field value for the current message or for a +list of messages from the current group. \fIfield\fR is the title of a +field in the header such as from, subject, date, etc. If \fIrange\fR 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: +.CS + + + msgid value + +.CE +.IP +Where msgid is the number of the message and value is the value set for the +queried field. The \fIrange\fR argument can be in any of the following forms: +.RS +.TP +\fB""\fR +The current message is queried. +.TP +\fImsgid1\fR-\fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.TP +\fImsgid1\fR \fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.RE +.TP +\fInntpName\fR \fBxover\fR ?\fIrange\fR? +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: +.CS + + + msgid subject from date idstring bodysize headersize xref + +.CE +.IP +If \fIrange\fR is not specified or is "" then the current message is queried. +The \fIrange\fR argument can be in any of the following forms: +.RS +.TP +\fB""\fR +The current message is queried. +.TP +\fImsgid1\fR-\fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.TP +\fImsgid1\fR \fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.RE +.TP +\fInntpName\fR \fBxpat\fR \fIfield\fR \fIrange\fR ?\fIpattern_list\fR? +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. \fIfield\fR 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: +.CS + + + msgid value + +.CE +.IP +Where msgid is the number of the message and value is the value set for the +queried field. The \fIrange\fR argument can be in any of the following forms: +.RS +.TP +\fImsgid\fR +The message specified by \fImsgid\fR is queried. +.TP +\fImsgid1\fR-\fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.TP +\fImsgid1\fR \fImsgid2\fR +All messages between \fImsgid1\fR and \fImsgid2\fR +(including \fImsgid1\fR and \fImsgid2\fR) are queried. +.RE +.PP +.SH EXAMPLE +A bigger example for posting a single article. +.PP +.CS + + + 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" + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fInntp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +news, nntp, nntpclient, rfc 1036, rfc 977 +.SH CATEGORY +Networking ADDED embedded/man/files/modules/ntp/ntp_time.n Index: embedded/man/files/modules/ntp/ntp_time.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ntp/ntp_time.n @@ -0,0 +1,401 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ntp/ntp_time.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ntp_time" n 1.2.1 tcllib "Network Time Facilities" +.BS +.SH NAME +ntp_time \- Tcl Time Service Client +.SH SYNOPSIS +package require \fBTcl 8.0\fR +.sp +package require \fBtime ?1.2.1?\fR +.sp +\fB::time::gettime\fR ?\fIoptions\fR? \fItimeserver\fR ?\fIport\fR? +.sp +\fB::time::getsntp\fR ?\fIoptions\fR? \fItimeserver\fR ?\fIport\fR? +.sp +\fB::time::configure\fR ?\fIoptions\fR? +.sp +\fB::time::cget\fR \fIname\fR +.sp +\fB::time::unixtime\fR \fItoken\fR +.sp +\fB::time::status\fR \fItoken\fR +.sp +\fB::time::error\fR \fItoken\fR +.sp +\fB::time::reset\fR \fItoken\fR \fI?reason?\fR +.sp +\fB::time::wait\fR \fItoken\fR +.sp +\fB::time::cleanup\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package implements a client for the RFC 868 TIME protocol +(\fIhttp://www.rfc-editor.org/rfc/rfc868.txt\fR) and also a minimal +client for the RFC 2030 Simple Network Time Protocol +(\fIhttp://www.rfc-editor.org/rfc/rfc2030.txt\fR). +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. +.SH COMMANDS +.TP +\fB::time::gettime\fR ?\fIoptions\fR? \fItimeserver\fR ?\fIport\fR? +Get the time from \fItimeserver\fR. You may specify any of the options +listed for the \fBconfigure\fR 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 \fBcleanup\fR to +release all resources. The default port is \fB37\fR. +.TP +\fB::time::getsntp\fR ?\fIoptions\fR? \fItimeserver\fR ?\fIport\fR? +Get the time from an SNTP server. This accepts exactly the same +arguments as \fB::time::gettime\fR except that the default port is +\fB123\fR. The result is a token as per \fB::time::gettime\fR and +should be handled in the same way. +.sp +Note that it is unlikely that any SNTP server will reply using tcp so +you will require the \fBtcludp\fR or the \fBceptcl\fR +package. If a suitable package can be loaded then the udp protocol +will be used by default. +.TP +\fB::time::configure\fR ?\fIoptions\fR? +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. +.RS +.TP +\fB-protocol\fR \fInumber\fR +Set the default network protocol. This defaults to udp if the tcludp +package is available. Otherwise it will use tcp. +.TP +\fB-port\fR \fInumber\fR +Set the default port to use. RFC 868 uses port \fB37\fR, RFC 2030 uses +port \fB123\fR. +.TP +\fB-timeout\fR \fInumber\fR +Set the default timeout value in milliseconds. The default is 10 seconds. +.TP +\fB-command\fR \fInumber\fR +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. +.TP +\fB-loglevel\fR \fInumber\fR +Set the logging level. The default is 'warning'. +.RE +.TP +\fB::time::cget\fR \fIname\fR +Get the current value for the named configuration option. +.TP +\fB::time::unixtime\fR \fItoken\fR +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. +.TP +\fB::time::status\fR \fItoken\fR +Returns the status flag. For a successfully completed query this will be +\fIok\fR. May be \fIerror\fR or \fItimeout\fR or \fIeof\fR. +See also \fB::time::error\fR +.TP +\fB::time::error\fR \fItoken\fR +Returns the error message provided for requests whose status is \fIerror\fR. +If there is no error message then an empty string is returned. +.TP +\fB::time::reset\fR \fItoken\fR \fI?reason?\fR +Reset or cancel the query optionally specfying the reason to record +for the \fBerror\fR command. +.TP +\fB::time::wait\fR \fItoken\fR +Wait for a query to complete and return the status upon completion. +.TP +\fB::time::cleanup\fR \fItoken\fR +Remove all state variables associated with the request. +.PP +.CS + + +% set tok [::time::gettime ntp2a.mcc.ac.uk] +% set t [::time::unixtime $tok] +% ::time::cleanup $tok + +.CE +.CS + + +% set tok [::time::getsntp pool.ntp.org] +% set t [::time::unixtime $tok] +% ::time::cleanup $tok + +.CE +.CS + + +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 + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIntp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +ntp +.SH KEYWORDS +NTP, SNTP, rfc 2030, rfc 868, time +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2002, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/ooutil/ooutil.n Index: embedded/man/files/modules/ooutil/ooutil.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ooutil/ooutil.n @@ -0,0 +1,386 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ooutil/ooutil.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011-2013 Andreas Kupries, BSD licensed +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "oo::util" n 1.1 tcllib "Utility commands for TclOO" +.BS +.SH NAME +oo::util \- Utility commands for TclOO +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBoo::util ?1.1?\fR +.sp +\fBmymethod\fR \fImethod\fR ?\fIarg\fR...? +.sp +\fBclassmethod\fR \fIname\fR \fIarguments\fR \fIbody\fR +.sp +\fBclassvariable\fR ?\fIarg\fR...? +.sp +\fBooutil::singleton\fR ?\fIarg\fR...? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a convenience command for the easy specification +of instance methods as callback commands, like timers, file events, Tk +bindings, etc. +.SH COMMANDS +.TP +\fBmymethod\fR \fImethod\fR ?\fIarg\fR...? +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. +.sp +Note: The command is equivalent to and named after the command +provided by the OO package \fBsnit\fR for the same purpose. +.TP +\fBclassmethod\fR \fIname\fR \fIarguments\fR \fIbody\fR +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. +.sp +Note: The command is equivalent to the command \fBtypemethod\fR +provided by the OO package \fBsnit\fR for the same purpose. +.sp +Example +.CS + + +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 + +.CE +.TP +\fBclassvariable\fR ?\fIarg\fR...? +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. +.sp +Note: The command is roughly equivalent to the command +\fBtypevariable\fR provided by the OO package \fBsnit\fR for the +same purpose. The difference is that it cannot be used in the class +definition itself. +.sp +Example: +.CS + + +% 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 + +.CE +.TP +\fBooutil::singleton\fR ?\fIarg\fR...? +This command is a meta-class, i.e. a variant of the builtin +\fBoo::class\fR which ensures that it creates only a single +instance of the classes defined with it. +.sp +Syntax and results are like for \fBoo::class\fR. +.sp +Example: +.CS + + +% oo::class create example { + self mixin singleton + method foo {} {self} +} +::example +% [example new] foo +::oo::Obj22 +% [example new] foo +::oo::Obj22 + +.CE +.PP +.SH AUTHORS +Donal Fellows, Andreas Kupries +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIoo::util\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +snit(n) +.SH KEYWORDS +TclOO, callback, class methods, class variables, command prefix, currying, method reference, my method, singleton +.SH CATEGORY +Utility +.SH COPYRIGHT +.nf +Copyright (c) 2011-2013 Andreas Kupries, BSD licensed + +.fi ADDED embedded/man/files/modules/otp/otp.n Index: embedded/man/files/modules/otp/otp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/otp/otp.n @@ -0,0 +1,331 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/otp/otp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "otp" n 1.0.0 tcllib "RFC 2289 A One-Time Password System" +.BS +.SH NAME +otp \- One-Time Passwords +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBotp ?1.0.0?\fR +.sp +\fB::otp::otp-md4\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.sp +\fB::otp::otp-md5\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.sp +\fB::otp::otp-sha1\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.sp +\fB::otp::otp-rmd160\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +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). +.SH COMMANDS +.TP +\fB::otp::otp-md4\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.TP +\fB::otp::otp-md5\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.TP +\fB::otp::otp-sha1\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.TP +\fB::otp::otp-rmd160\fR ?\fI-hex\fR? ?\fI-words\fR? \fI-seed seed\fR \fI-count count\fR \fIdata\fR +.PP +.SH EXAMPLES +.CS + + +% 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 + +.CE +.SH REFERENCES +.IP [1] +Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998. +\fIhttp://www.rfc-editor.org/rfc/rfc2289.txt\fR +.IP [2] +Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and +RSA Data Security, Inc, April 1992. +(\fIhttp://www.rfc-editor.org/rfc/rfc1321.txt\fR) +.IP [3] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [4] +H. Dobbertin, A. Bosselaers, B. Preneel, +"RIPEMD-160, a strengthened version of RIPEMD" +\fIhttp://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf\fR +.IP [5] +"Secure Hash Standard", National Institute of Standards +and Technology, U.S. Department Of Commerce, April 1995. +(\fIhttp://www.itl.nist.gov/fipspubs/fip180-1.htm\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIotp\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +SASL, md4, md5, ripemd160, sha1 +.SH KEYWORDS +hashing, message-digest, password, rfc 2289, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2006, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_intro.n Index: embedded/man/files/modules/page/page_intro.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_intro.n @@ -0,0 +1,275 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_intro.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_intro" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_intro \- page introduction +.SH DESCRIPTION +.PP +\fIpage\fR (short for \fIparser generator\fR) stands for a set of +related packages which help in the construction of parser generators, +and other utilities doing text processing. +.PP +They are mainly geared towards supporting the Tcllib application +\fBpage\fR, with the package \fBpage::pluginmgr\fR 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 \fBpage\fR through +plugins. +.PP +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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +page, parser generator, text processing +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_pluginmgr.n Index: embedded/man/files/modules/page/page_pluginmgr.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_pluginmgr.n @@ -0,0 +1,1015 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_pluginmgr.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_pluginmgr" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_pluginmgr \- page plugin manager +.SH SYNOPSIS +package require \fBpage::pluginmgr ?0.2?\fR +.sp +package require \fBfileutil \fR +.sp +\fB::page::pluginmgr::reportvia\fR \fIcmd\fR +.sp +\fB::page::pluginmgr::report\fR \fIlevel\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fB::page::pluginmgr::log\fR \fIcmd\fR +.sp +\fB::page::pluginmgr::configuration\fR \fIname\fR +.sp +\fB::page::pluginmgr::reader\fR \fIname\fR +.sp +\fB::page::pluginmgr::rconfigure\fR \fIdict\fR +.sp +\fB::page::pluginmgr::rtimeable\fR +.sp +\fB::page::pluginmgr::rtime\fR +.sp +\fB::page::pluginmgr::rgettime\fR +.sp +\fB::page::pluginmgr::rhelp\fR +.sp +\fB::page::pluginmgr::rlabel\fR +.sp +\fB::page::pluginmgr::read\fR \fIread\fR \fIeof\fR ?\fIcomplete\fR? +.sp +\fIread\fR \fInum\fR +.sp +\fIeof\fR +.sp +\fIdone\fR +.sp +\fB::page::pluginmgr::writer\fR \fIname\fR +.sp +\fB::page::pluginmgr::wconfigure\fR \fIdict\fR +.sp +\fB::page::pluginmgr::wtimeable\fR +.sp +\fB::page::pluginmgr::wtime\fR +.sp +\fB::page::pluginmgr::wgettime\fR +.sp +\fB::page::pluginmgr::whelp\fR +.sp +\fB::page::pluginmgr::wlabel\fR +.sp +\fB::page::pluginmgr::write\fR \fIchan\fR \fIdata\fR +.sp +\fB::page::pluginmgr::transform\fR \fIname\fR +.sp +\fB::page::pluginmgr::tconfigure\fR \fIid\fR \fIdict\fR +.sp +\fB::page::pluginmgr::ttimeable\fR \fIid\fR +.sp +\fB::page::pluginmgr::ttime\fR \fIid\fR +.sp +\fB::page::pluginmgr::tgettime\fR \fIid\fR +.sp +\fB::page::pluginmgr::thelp\fR \fIid\fR +.sp +\fB::page::pluginmgr::tlabel\fR \fIid\fR +.sp +\fB::page::pluginmgr::transform_do\fR \fIid\fR \fIdata\fR +.sp +\fBpage_cdefinition\fR +.sp +\fBpage_rfeature\fR \fIname\fR +.sp +\fBpage_rtime\fR +.sp +\fBpage_rgettime\fR +.sp +\fBpage_rlabel\fR +.sp +\fBpage_rhelp\fR +.sp +\fBpage_roptions\fR +.sp +\fBpage_rconfigure\fR \fIoption\fR \fIvalue\fR +.sp +\fBpage_rrun\fR +.sp +\fBpage_read\fR \fInum\fR +.sp +\fBpage_read_done\fR +.sp +\fBpage_eof\fR +.sp +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_log_info\fR \fItext\fR +.sp +\fBpage_log_warning\fR \fItext\fR +.sp +\fBpage_log_error\fR \fItext\fR +.sp +\fBpage_wfeature\fR +.sp +\fBpage_wtime\fR +.sp +\fBpage_wgettime\fR +.sp +\fBpage_wlabel\fR +.sp +\fBpage_whelp\fR +.sp +\fBpage_woptions\fR +.sp +\fBpage_wconfigure\fR \fIoption\fR \fIvalue\fR +.sp +\fBpage_wrun\fR \fIchan\fR \fIdata\fR +.sp +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_log_info\fR \fItext\fR +.sp +\fBpage_log_warning\fR \fItext\fR +.sp +\fBpage_log_error\fR \fItext\fR +.sp +\fBpage_tfeature\fR +.sp +\fBpage_ttime\fR +.sp +\fBpage_tgettime\fR +.sp +\fBpage_tlabel\fR +.sp +\fBpage_thelp\fR +.sp +\fBpage_toptions\fR +.sp +\fBpage_tconfigure\fR \fIoption\fR \fIvalue\fR +.sp +\fBpage_trun\fR \fIchan\fR \fIdata\fR +.sp +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fBpage_log_info\fR \fItext\fR +.sp +\fBpage_log_warning\fR \fItext\fR +.sp +\fBpage_log_error\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides the plugin manager central to the \fBpage\fR +application. It manages the various reader, writer, configuration, and +transformation plugins which actually process the text (read, +transform, and write). +.PP +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 \fBPREDEFINED PLUGINS\fR, and not documented as regular +packages. It is expected that they follow the APIs specified in the +sections +.IP [1] +\fBCONFIG PLUGIN API\fR +.IP [2] +\fBREADER PLUGIN API\fR +.IP [3] +\fBWRITER PLUGIN API\fR +.IP [4] +\fBTRANSFORM PLUGIN API\fR +.PP +as per their type. +.SH API +.TP +\fB::page::pluginmgr::reportvia\fR \fIcmd\fR +This command defines the callback command used by +\fB::page::pluginmgr::report\fR (see below) to report input errors and +warnings. The default is to write such reports to the standard error +channel. +.TP +\fB::page::pluginmgr::report\fR \fIlevel\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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 +\fB::page::pluginmgr::reportvia\fR (see above). +.sp +The arguments \fIlevel\fR and \fItext\fR specify both the importance +of the message, and the message itself. For the former see the package +\fBlogger\fR for the allowed values. +.sp +The optional argument \fIfrom\fR and \fIto\fR 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. +.TP +\fB::page::pluginmgr::log\fR \fIcmd\fR +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. +.sp +Note: The \fIcmd\fR has to be created by the \fBlogger\fR package, +or follow the same API as such. +.sp +The command returns the empty string as its result. +.TP +\fB::page::pluginmgr::configuration\fR \fIname\fR +This command loads the named configuration plugin, retrieves the +options encoded in it, and then immediately unloads it again. +.sp +If the \fIname\fR 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. +.sp +See section \fBCONFIG PLUGIN API\fR for the API expected of +configuration plugins. +.sp +The result of the command is the list of options retrieved. +.TP +\fB::page::pluginmgr::reader\fR \fIname\fR +This command loads the named reader plugin and initializes it. The +result of the command is a list of options the plugin understands. +.sp +Only a single reader plugin can be loaded. Loading another reader +plugin causes the previously loaded reader plugin to be de-initialized +and unloaded. +.sp +See section \fBREADER PLUGIN API\fR for the API expected of +reader plugins. +.TP +\fB::page::pluginmgr::rconfigure\fR \fIdict\fR +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. +.TP +\fB::page::pluginmgr::rtimeable\fR +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 \fBtrue\fR if the plugin can be timed, and \fBfalse\fR +otherwise. +.TP +\fB::page::pluginmgr::rtime\fR +This command activates the collection of timing statistics in the +loaded reader plugin. +.TP +\fB::page::pluginmgr::rgettime\fR +This command retrieves the collected timing statistics of the loaded +reader plugin after it was executed. +.TP +\fB::page::pluginmgr::rhelp\fR +This command retrieves the help string of the loaded reader +plugin. This is expected to be in \fIdoctools\fR format. +.TP +\fB::page::pluginmgr::rlabel\fR +This command retrieves the human-readable name of the loaded reader +plugin. +.TP +\fB::page::pluginmgr::read\fR \fIread\fR \fIeof\fR ?\fIcomplete\fR? +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 \fIread\fR, and \fIeof\fR. The +optional \fIdone\fR can be used to intrecept when the plugin has +completed its processing. All arguments are command prefixes. +.sp +The plugin will invoke the various callbacks in the following +situations: +.RS +.TP +\fIread\fR \fInum\fR +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. +.TP +\fIeof\fR +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, \fBtrue\fR when +the input has hit EOF, and \fBfalse\fR otherwise. +.TP +\fIdone\fR +is invoked when the plugin has completed the processing of the input. +.RE +.TP +\fB::page::pluginmgr::writer\fR \fIname\fR +This command loads the named writer plugin and initializes it. The +result of the command is a list of options the plugin understands. +.sp +Only a single reader plugin can be loaded. Loading another reader +plugin causes the previously loaded reader plugin to be de-initialized +and unloaded. +.sp +See section \fBWRITER PLUGIN API\fR for the API expected of +writer plugins. +.TP +\fB::page::pluginmgr::wconfigure\fR \fIdict\fR +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. +.TP +\fB::page::pluginmgr::wtimeable\fR +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 \fBtrue\fR if the plugin can be timed, and \fBfalse\fR +otherwise. +.TP +\fB::page::pluginmgr::wtime\fR +This command activates the collection of timing statistics in the +loaded writer plugin. +.TP +\fB::page::pluginmgr::wgettime\fR +This command retrieves the collected timing statistics of the loaded +writer plugin after it was executed. +.TP +\fB::page::pluginmgr::whelp\fR +This command retrieves the help string of the loaded writer +plugin. This is expected to be in \fIdoctools\fR format. +.TP +\fB::page::pluginmgr::wlabel\fR +This command retrieves the human-readable name of the loaded writer +plugin. +.TP +\fB::page::pluginmgr::write\fR \fIchan\fR \fIdata\fR +The loaded writer plugin is invoked to generate the output. It is +given the \fIdata\fR to generate the outpout from, and the Tcl handle +\fIchan\fR of the channel to write the generated output to. The +command returns th empty string as its result. +.TP +\fB::page::pluginmgr::transform\fR \fIname\fR +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. +.sp +Multiple transformations plugins can be loaded and are identified by +handles. +.sp +See section \fBTRANSFORM PLUGIN API\fR for the API expected of +transformation plugins. +.TP +\fB::page::pluginmgr::tconfigure\fR \fIid\fR \fIdict\fR +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. +.TP +\fB::page::pluginmgr::ttimeable\fR \fIid\fR +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 \fBtrue\fR if the plugin can be timed, and +\fBfalse\fR otherwise. +.TP +\fB::page::pluginmgr::ttime\fR \fIid\fR +This command activates the collection of timing statistics in the +identified transformation plugin. +.TP +\fB::page::pluginmgr::tgettime\fR \fIid\fR +This command retrieves the collected timing statistics of the +identified transformation plugin after it was executed. +.TP +\fB::page::pluginmgr::thelp\fR \fIid\fR +This command retrieves the help string of the identified +transformation plugin. This is expected to be in \fIdoctools\fR +format. +.TP +\fB::page::pluginmgr::tlabel\fR \fIid\fR +This command retrieves the human-readable name of the identified +transformation plugin. +.TP +\fB::page::pluginmgr::transform_do\fR \fIid\fR \fIdata\fR +The identified transformation plugin is invoked to process the +specified \fIdata\fR. The result of the plugin is returned as the +result of the command. +.PP +.SH "CONFIG PLUGIN API" +Configuration plugins are expected to provide a single command, +described below. +.PP +.TP +\fBpage_cdefinition\fR +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. +.PP +.PP +Configuration plugins do not expect the environment to provide any +special commands. +.PP +It is expected that a configuration plugin \fBFOO\fR is implemented +by the package \fBpage::config::\fBFOO\fR\fR. +.PP +Configuration plugins are loaded, executed, and unloaded in one step, +they are not kept in memory. The command for doing this is +\fB::page::pluginmgr::configuration\fR. +.SH "READER PLUGIN API" +Reader plugins are expected to provide the following commands, +described below. +.PP +.TP +\fBpage_rfeature\fR \fIname\fR +This command takes a feature \fIname\fR and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be \fBtrue\fR if the feature is supported, and +\fBfalse\fR otherwise. +.sp +See section \fBFEATURES\fR for the possible features the plugin +manager will ask for. +.TP +\fBpage_rtime\fR +This command is invoked to activate the collection of timing +statistics. +.TP +\fBpage_rgettime\fR +This command is invoked to retrieve the collected timing statistics. +.TP +\fBpage_rlabel\fR +This command is invoked to retrieve a human-readable label for the +plugin. +.TP +\fBpage_rhelp\fR +This command is invoked to retrieve a help text for plugin. The text +is expected to be in \fIdoctools\fR format. +.TP +\fBpage_roptions\fR +This command is invoked to retrieve the options understood by the +plugin. +.TP +\fBpage_rconfigure\fR \fIoption\fR \fIvalue\fR +This command is invoked to reconfigure the plugin, specifically the +given \fIoption\fR is set to the new \fIvalue\fR. +.TP +\fBpage_rrun\fR +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. +.PP +.PP +Reader plugins expect the environment to provide the following special +commands. +.TP +\fBpage_read\fR \fInum\fR +This command is invoked to read \fInum\fR characters/bytes from the +input. Its result has to be read characters/bytes. +.TP +\fBpage_read_done\fR +This command is invoked to signal that the plugin has completed the +processing of the input. +.TP +\fBpage_eof\fR +This command is invoked to check if the input stream has reached its +end. Its result has to be a boolean flag, \fBtrue\fR when the input +has reached the end, \fBfalse\fR otherwise. +.TP +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_log_info\fR \fItext\fR +Invoked to report some internal information. +.TP +\fBpage_log_warning\fR \fItext\fR +Invoked to report an internal warning. +.TP +\fBpage_log_error\fR \fItext\fR +Invoked to report an internal error. +.PP +.PP +It is expected that a reader plugin \fBFOO\fR is implemented +by the package \fBpage::reader::\fBFOO\fR\fR. +.PP +Reader plugins are loaded by the command +\fB::page::pluginmgr::reader\fR. At most one reader plugin can be kept +in memory. +.SH "WRITER PLUGIN API" +Writer plugins are expected to provide the following commands, +described below. +.PP +.TP +\fBpage_wfeature\fR +This command takes a feature \fIname\fR and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be \fBtrue\fR if the feature is supported, and +\fBfalse\fR otherwise. +.sp +See section \fBFEATURES\fR for the possible features the plugin +manager will ask for. +.TP +\fBpage_wtime\fR +This command is invoked to activate the collection of timing +statistics. +.TP +\fBpage_wgettime\fR +This command is invoked to retrieve the collected timing statistics. +.TP +\fBpage_wlabel\fR +This command is invoked to retrieve a human-readable label for the +plugin. +.TP +\fBpage_whelp\fR +This command is invoked to retrieve a help text for plugin. The text +is expected to be in \fIdoctools\fR format. +.TP +\fBpage_woptions\fR +This command is invoked to retrieve the options understood by the +plugin. +.TP +\fBpage_wconfigure\fR \fIoption\fR \fIvalue\fR +This command is invoked to reconfigure the plugin, specifically the +given \fIoption\fR is set to the new \fIvalue\fR. +.TP +\fBpage_wrun\fR \fIchan\fR \fIdata\fR +This command is invoked to process the specified \fIdata\fR and write +it to the output stream \fIchan\fR. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string. +.PP +.PP +Writer plugins expect the environment to provide the following special +commands. +.TP +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_log_info\fR \fItext\fR +Invoked to report some internal information. +.TP +\fBpage_log_warning\fR \fItext\fR +Invoked to report an internal warning. +.TP +\fBpage_log_error\fR \fItext\fR +Invoked to report an internal error. +.PP +.PP +It is expected that a writer plugin \fBFOO\fR is implemented +by the package \fBpage::writer::\fBFOO\fR\fR. +.PP +Writer plugins are loaded by the command +\fB::page::pluginmgr::writer\fR. At most one writer plugin can be kept +in memory. +.SH "TRANSFORM PLUGIN API" page::transform::* +Transformation plugins are expected to provide the following commands, +described below. +.PP +.TP +\fBpage_tfeature\fR +This command takes a feature \fIname\fR and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be \fBtrue\fR if the feature is supported, and +\fBfalse\fR otherwise. +.sp +See section \fBFEATURES\fR for the possible features the plugin +manager will ask for. +.TP +\fBpage_ttime\fR +This command is invoked to activate the collection of timing +statistics. +.TP +\fBpage_tgettime\fR +This command is invoked to retrieve the collected timing statistics. +.TP +\fBpage_tlabel\fR +This command is invoked to retrieve a human-readable label for the +plugin. +.TP +\fBpage_thelp\fR +This command is invoked to retrieve a help text for plugin. The text +is expected to be in \fIdoctools\fR format. +.TP +\fBpage_toptions\fR +This command is invoked to retrieve the options understood by the +plugin. +.TP +\fBpage_tconfigure\fR \fIoption\fR \fIvalue\fR +This command is invoked to reconfigure the plugin, specifically the +given \fIoption\fR is set to the new \fIvalue\fR. +.TP +\fBpage_trun\fR \fIchan\fR \fIdata\fR +This command is invoked to process the specified \fIdata\fR and write +it to the output stream \fIchan\fR. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string. +.PP +.PP +Transformation plugins expect the environment to provide the following +special commands. +.TP +\fBpage_info\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_warning\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_error\fR \fItext\fR ?\fIfrom\fR ?\fIto\fR?? +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. +.TP +\fBpage_log_info\fR \fItext\fR +Invoked to report some internal information. +.TP +\fBpage_log_warning\fR \fItext\fR +Invoked to report an internal warning. +.TP +\fBpage_log_error\fR \fItext\fR +Invoked to report an internal error. +.PP +.PP +It is expected that a transformation plugin \fBFOO\fR is implemented +by the package \fBpage::transform::\fBFOO\fR\fR. +.PP +Transformation plugins are loaded by the command +\fB::page::pluginmgr::transform\fR. More than one transformation +plugin can be kept in memory. +.SH "PREDEFINED PLUGINS" +The following predefined plugins are known, i.e. provided by the page +module. +.TP +Configuration +.RS +.TP +peg +Returns a set of options to configure the \fBpage\fR application +for the processing of a PEG grammar and the generation of ME code. See +the packages \fBgrammar_peg\fR, \fBgrammar_me\fR and relations +for more details. +.RE +.TP +Reader +.RS +.TP +hb +Expects a so-called \fIhalf-baked PEG container\fR as input and +returns the equivalent abstract syntax tree. See the writer plugin +\fIhb\fR for the plugin generating this type of input. +.TP +lemon +Expects a grammar specification as understood by Richar Hipp's LEMON +parser generator and returns an abstract syntax tree for it. +.TP +peg +Expects a grammar specification in the form of a parsing expression +grammar (PEG) and returns an abstract syntax tree for it. +.TP +ser +Expect the serialized form of a parsing expression grammar as +generated by the package \fBgrammar::peg\fR as input, converts it +into an equivalent abstract syntax tree and returns that. +.TP +treeser +Expects the serialized form of a tree as generated by the package +\fBstruct::tree\fR as input and returns it, after validation. +.RE +.TP +Writer +.RS +.TP +hb +Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out in the form of a so-called +\fIhalf-baked PEG container\fR. +.TP +identity +Takes any input and writes it as is. +.TP +mecpu +Expects symbolic assembler code for the MatchEngine CPU (See the +package \fBgrammar::me::cpu\fR and relatives) and writes it out as +Tcl code for a parser. +.TP +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 \fBgrammar::me\fR and relatives) which parses input in +that grammar. +.TP +null +Takes any input and writes nothing. The logical equivalent of +/dev/null. +.TP +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 \fIpeg\fR. +.TP +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 \fIser\fR. +.TP +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 \fBgrammar::peg\fR. +.TP +tree +Takes any serialized tree (per package \fBstruct::tree\fR) as +input and writes it out in a generic indented format. +.RE +.TP +Transformation +.RS +.TP +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 \fBgrammar::me::cpu\fR +and relatives). +.TP +reachable +Takes an abstract syntax tree for a parsing expression grammer as +input, performs a reachability analysis, and returns the modified and +annotated tree. +.TP +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. +.RE +.PP +.SH FEATURES +The plugin manager currently checks the plugins for only one feature, +\fBtimeable\fR. A plugin supporting this feature is assumed to be +able to collect timing statistics on request. +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +page, parser generator, text processing +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_util_flow.n Index: embedded/man/files/modules/page/page_util_flow.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_util_flow.n @@ -0,0 +1,327 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_util_flow.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_util_flow" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_util_flow \- page dataflow/treewalker utility +.SH SYNOPSIS +package require \fBpage::util::flow ?0.1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::page::util::flow\fR \fIstart\fR \fIflowvar\fR \fInodevar\fR \fIscript\fR +.sp +\fIflow\fR \fBvisit\fR \fInode\fR +.sp +\fIflow\fR \fBvisitl\fR \fInodelist\fR +.sp +\fIflow\fR \fBvisita\fR \fInode\fR... +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a single utility command for easy dataflow based +manipulation of arbitrary data structures, especially abstract syntax +trees. +.SH API +.TP +\fB::page::util::flow\fR \fIstart\fR \fIflowvar\fR \fInodevar\fR \fIscript\fR +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. +.sp +The command makes no assumptions at all about the API of the structure +to be walked, except that that its parts, here called \fInodes\fR, +are identified by strings. These strings are taken as is, from the +arguments, and the body, and handed back to the body, without +modification. +.sp +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 \fIscript\fR. +.sp +The body is invoked first for the nodes in the start-set specified via +\fIstart\fR), 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. +.sp +The body is invoked in the context of the caller. The variable named +by \fInodevar\fR will be set to the current node, and the variable +named by \fIflowvar\fR 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, +\fBFLOW API\fR. +.sp +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. +.PP +.SH "FLOW API" +This section describes the API provided by the flow object made +accessible to the body script of \fB::page::util::flow\fR. +.TP +\fIflow\fR \fBvisit\fR \fInode\fR +Invoking this method requests that the node \fIn\fR is visited after +the current iteration. +.TP +\fIflow\fR \fBvisitl\fR \fInodelist\fR +Invoking this method requests that all the nodes found in the list +\fInodelist\fR are visited after the current iteration. +.TP +\fIflow\fR \fBvisita\fR \fInode\fR... +This is the variadic arguments form of the method \fBvisitl\fR, see +above. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +dataflow, graph walking, page, parser generator, text processing, tree walking +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_util_norm_lemon.n Index: embedded/man/files/modules/page/page_util_norm_lemon.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_util_norm_lemon.n @@ -0,0 +1,283 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_util_norm_lemon.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_util_norm_lemon" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_util_norm_lemon \- page AST normalization, LEMON +.SH SYNOPSIS +package require \fBpage::util::norm_lemon ?0.1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::page::util::norm::lemon\fR \fItree\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fINormalized Lemon Grammar Tree\fR. +.PP +\fINote\fR that this package can only be used from within a plugin +managed by the package \fBpage::pluginmgr\fR. +.SH API +.TP +\fB::page::util::norm::lemon\fR \fItree\fR +This command assumes the \fItree\fR object contains for a lemon +grammar. It normalizes this tree in place. The result is called a +\fINormalized Lemon Grammar Tree\fR. +.sp +The exact operations performed are left undocumented for the moment. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +graph walking, lemon, normalization, page, parser generator, text processing, tree walking +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_util_norm_peg.n Index: embedded/man/files/modules/page/page_util_norm_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_util_norm_peg.n @@ -0,0 +1,332 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_util_norm_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_util_norm_peg" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_util_norm_peg \- page AST normalization, PEG +.SH SYNOPSIS +package require \fBpage::util::norm_peg ?0.1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::page::util::norm::peg\fR \fItree\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fINormalized PE Grammar Tree\fR. +.PP +\fINote\fR that this package can only be used from within a plugin +managed by the package \fBpage::pluginmgr\fR. +.SH API +.TP +\fB::page::util::norm::peg\fR \fItree\fR +This command assumes the \fItree\fR object contains for a +parsing expression grammar. It normalizes this tree in place. +The result is called a \fINormalized PE Grammar Tree\fR. +.sp +The following operations are performd +.RS +.IP [1] +The data for all terminals is stored in their grandparental +nodes. The terminal nodes and their parents are removed. Type +information is dropped. +.IP [2] +All nodes which have exactly one child are irrelevant and are +removed, with the exception of the root node. The immediate +child of the root is irrelevant as well, and removed as well. +.IP [3] +The name of the grammar is moved from the tree node it is stored +in to an attribute of the root node, and the tree node removed. +.sp +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. +.IP [4] +Nonterminal hint information is moved from nodes into attributes, +and the now irrelevant nodes are deleted. +.sp +\fINote:\fR 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. +.sp +The default mode given to the nonterminals is \fBvalue\fR. +.sp +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. +.sp +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. +.IP [5] +The remaining nodes under all definitions are transformed +into proper expression trees. First character ranges, followed +by unary operations, characters, and nonterminals. At last the +tree is flattened by the removal of superfluous inner nodes. +.sp +The order matters, to shed as much nodes as possible early, and +to avoid unnecessary work later. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +PEG, graph walking, normalization, page, parser generator, text processing, tree walking +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_util_peg.n Index: embedded/man/files/modules/page/page_util_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_util_peg.n @@ -0,0 +1,354 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_util_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_util_peg" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_util_peg \- page PEG transformation utilities +.SH SYNOPSIS +package require \fBpage::util::peg ?0.1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::page::util::peg::symbolNodeOf\fR \fItree\fR \fInode\fR +.sp +\fB::page::util::peg::symbolOf\fR \fItree\fR \fInode\fR +.sp +\fB::page::util::peg::updateUndefinedDueRemoval\fR \fItree\fR +.sp +\fB::page::util::peg::flatten\fR \fItreequery\fR \fItree\fR +.sp +\fB::page::util::peg::getWarnings\fR \fItree\fR +.sp +\fB::page::util::peg::printWarnings\fR \fImsg\fR +.sp +\fB::page::util::peg::peOf\fR \fItree\fR \fIeroot\fR +.sp +\fB::page::util::peg::printTclExpr\fR \fIpe\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a few common operations to PEG transformations. +They assume a \fINormalized PE Grammar Tree\fR as input, see the +package \fBpage::util::norm::peg\fR, possibly augmented with +attributes coming from transformations not in conflict with the base +definition. +.PP +.SH API +.TP +\fB::page::util::peg::symbolNodeOf\fR \fItree\fR \fInode\fR +Given an arbitrary expression \fInode\fR in the AST \fItree\fR 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. +.TP +\fB::page::util::peg::symbolOf\fR \fItree\fR \fInode\fR +As \fB::page::util::peg::symbolNodeOf\fR, but returns the symbol name +instead of the node. +.TP +\fB::page::util::peg::updateUndefinedDueRemoval\fR \fItree\fR +The removal of nodes in the AST \fItree\fR can cause symbols to lose +one or more users. +.CS + + + 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. + +.CE +.IP +This command updates the cross-references and which nonterminals are +now undefined. +.TP +\fB::page::util::peg::flatten\fR \fItreequery\fR \fItree\fR +This commands flattens nested sequence and choice operators in the AST +\fItree\fR, re-using the \fBtreeql\fR object \fItreequery\fR to +run the query determining which nodes to cut. +.TP +\fB::page::util::peg::getWarnings\fR \fItree\fR +This command looks at the attributes of the AST \fItree\fR 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. +.sp +The result of the command is a dictionary mapping nonterminal names to +their associated warnings. +.TP +\fB::page::util::peg::printWarnings\fR \fImsg\fR +The argument of the command is a dictionary mapping nonterminal names +to their associated warnings, as generated by, for example, the +command \fB::page::util::peg::getWarnings\fR. +.sp +The warnings contained therein are formatted and then printed via the +log command \fBpage_info\fR. This means that this command can be used +only from within a plugin managed by the package +\fBpage::pluginmgr\fR. +.TP +\fB::page::util::peg::peOf\fR \fItree\fR \fIeroot\fR +This command converts the parsing expression starting at the node +\fIeroot\fR in the AST \fItree\fR into a nested list. The exact syntax +of this list specified by the package \fBgrammar::peg\fR. +.TP +\fB::page::util::peg::printTclExpr\fR \fIpe\fR +This command converts the parsing expression contained in the nested +list \fIpe\fR into a Tcl string which can be placed into a Tcl script. +See the package \fBgrammar::peg\fR for the exact syntax of +\fIpe\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +PEG, page, parser generator, parsing expression grammar, text processing, transformation +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/page/page_util_quote.n Index: embedded/man/files/modules/page/page_util_quote.n ================================================================== --- /dev/null +++ embedded/man/files/modules/page/page_util_quote.n @@ -0,0 +1,308 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/page/page_util_quote.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "page_util_quote" n 1.0 tcllib "Parser generator tools" +.BS +.SH NAME +page_util_quote \- page character quoting utilities +.SH SYNOPSIS +package require \fBpage::util::quote ?0.1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::page::util::quote::unquote\fR \fIchar\fR +.sp +\fB::page::util::quote::quote'tcl\fR \fIchar\fR +.sp +\fB::page::util::quote::quote'tclstr\fR \fIchar\fR +.sp +\fB::page::util::quote::quote'tclcom\fR \fIchar\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides a few utility commands to convert characters +into various forms. +.SH API +.TP +\fB::page::util::quote::unquote\fR \fIchar\fR +A character, as stored in an abstract syntax tree by a PEG processor +(See the packages \fBgrammar::peg::interpreter\fR, +\fBgrammar::me\fR, 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. +.TP +\fB::page::util::quote::quote'tcl\fR \fIchar\fR +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. +.TP +\fB::page::util::quote::quote'tclstr\fR \fIchar\fR +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. +.sp +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. +.TP +\fB::page::util::quote::quote'tclcom\fR \fIchar\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, will undoubtedly contain bugs and other problems. +Please report such in the category \fIpage\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have. +.SH KEYWORDS +page, parser generator, quoting, text processing +.SH CATEGORY +Page Parser Generator +.SH COPYRIGHT +.nf +Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pki/pki.n Index: embedded/man/files/modules/pki/pki.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pki/pki.n @@ -0,0 +1,466 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pki/pki.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pki" n 0.6 tcllib "public key encryption" +.BS +.SH NAME +pki \- Implementation of the public key cipher +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpki ?0.6?\fR +.sp +\fB::pki::encrypt\fR ?\fI-binary\fR? ?\fI-hex\fR? ?\fI-pad\fR? ?\fI-nopad\fR? ?\fI-priv\fR? ?\fI-pub\fR? ?\fI--\fR? \fIinput\fR \fIkey\fR +.sp +\fB::pki::decrypt\fR ?\fI-binary\fR? ?\fI-hex\fR? ?\fI-unpad\fR? ?\fI-nounpad\fR? ?\fI-priv\fR? ?\fI-pub\fR? ?\fI--\fR? \fIinput\fR \fIkey\fR +.sp +\fB::pki::sign\fR \fIinput\fR \fIkey\fR ?\fIalgo\fR? +.sp +\fB::pki::verify\fR \fIsignedmessage\fR \fIplaintext\fR \fIkey\fR ?\fIalgo\fR? +.sp +\fB::pki::key\fR \fIkey\fR ?\fIpassword\fR? ?\fIencodePem\fR? +.sp +\fB::pki::pkcs::parse_key\fR \fIkey\fR ?\fIpassword\fR? +.sp +\fB::pki::x509::parse_cert\fR \fIcert\fR +.sp +\fB::pki::rsa::generate\fR \fIbitlength\fR ?\fIexponent\fR? +.sp +\fB::pki::x509::verify_cert\fR \fIcert\fR \fItrustedcerts\fR ?\fIintermediatecerts\fR? +.sp +\fB::pki::x509::validate_cert\fR \fIcert\fR ?\fB-sign_message\fR \fIdn_of_signer\fR? ?\fB-encrypt_message\fR \fIdn_of_signer\fR? ?\fB-sign_cert\fR \fIdn_to_be_signed\fR \fIca_depth\fR? ?\fB-ssl\fR \fIdn\fR? +.sp +\fB::pki::pkcs::create_csr\fR \fIkeylist\fR \fInamelist\fR ?\fIencodePem\fR? ?\fIalgo\fR? +.sp +\fB::pki::pkcs::parse_csr\fR \fIcsr\fR +.sp +\fB::pki::x509::create_cert\fR \fIsignreqlist\fR \fIcakeylist\fR \fIserial_number\fR \fInotBefore\fR \fInotAfter\fR \fIisCA\fR \fIextensions\fR ?\fIencodePem\fR? ?\fIalgo\fR? +.sp +.BE +.SH DESCRIPTION +.PP +.SH COMMANDS +.TP +\fB::pki::encrypt\fR ?\fI-binary\fR? ?\fI-hex\fR? ?\fI-pad\fR? ?\fI-nopad\fR? ?\fI-priv\fR? ?\fI-pub\fR? ?\fI--\fR? \fIinput\fR \fIkey\fR +Encrypt a message using PKI (probably RSA). +Requires the caller to specify either \fB-priv\fR to encrypt with +the private key or \fB-pub\fR to encrypt with the public key. The +default option is to pad and return in hex. One of \fB-pub\fR or +\fB-priv\fR must be specified. +The \fB-hex\fR option causes the data to be returned in encoded as +a hexidecimal string, while the \fB-binary\fR option causes the data +to be returned as a binary string. If they are specified multiple +times, the last one specified is used. +The \fB-pad\fR option causes the data to be padded per PKCS#1 prior +to being encrypted. The \fB-nopad\fR inhibits this behaviour. If +they are specified multiple times, the last one specified is used. +The input to encrypt is specified as \fIinput\fR. +The \fIkey\fR parameter, holding the key to use, is a return value +from either +\fB::pki::pkcs::parse_key\fR, +\fB::pki::x509::parse_cert\fR, or +\fB::pki::rsa::generate\fR. +.sp +Mapping to OpenSSL's \fBopenssl\fR application: +.RS +.IP [1] +"openssl rsautl -encrypt" == "::pki::encrypt -binary -pub" +.IP [2] +"openssl rsautl -sign" == "::pki::encrypt -binary -priv" +.RE +.TP +\fB::pki::decrypt\fR ?\fI-binary\fR? ?\fI-hex\fR? ?\fI-unpad\fR? ?\fI-nounpad\fR? ?\fI-priv\fR? ?\fI-pub\fR? ?\fI--\fR? \fIinput\fR \fIkey\fR +Decrypt a message using PKI (probably RSA). See \fB::pki::encrypt\fR for option handling. +.sp +Mapping to OpenSSL's \fBopenssl\fR application: +.RS +.IP [1] +"openssl rsautl -decrypt" == "::pki::decrypt -binary -priv" +.IP [2] +"openssl rsautl -verify" == "::pki::decrypt -binary -pub" +.RE +.TP +\fB::pki::sign\fR \fIinput\fR \fIkey\fR ?\fIalgo\fR? +Digitally sign message \fIinput\fR using the private \fIkey\fR. If \fIalgo\fR +is ommited "sha1" is assumed. Possible values for \fIalgo\fR include +"md5", "sha1", "sha256", and "raw". Specifyin "raw" for \fIalgo\fR will +inhibit the building of an ASN.1 structure to encode which hashing +algorithm was chosen. +The \fIinput\fR should be the plain text, hashing will be performed on it. +The \fIkey\fR should include the private key. +.TP +\fB::pki::verify\fR \fIsignedmessage\fR \fIplaintext\fR \fIkey\fR ?\fIalgo\fR? +Verify a digital signature using a public \fIkey\fR. Returns true or false. +.TP +\fB::pki::key\fR \fIkey\fR ?\fIpassword\fR? ?\fIencodePem\fR? +Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications. For RSA keys this means PKCS#1. +.TP +\fB::pki::pkcs::parse_key\fR \fIkey\fR ?\fIpassword\fR? +Convert a PKCS#1 private \fIkey\fR into a usable key, i.e. one which +can be used as argument for +\fB::pki::encrypt\fR, +\fB::pki::decrypt\fR, +\fB::pki::sign\fR, and +\fB::pki::verify\fR. +.TP +\fB::pki::x509::parse_cert\fR \fIcert\fR +Convert an X.509 certificate to a usable (public) key, i.e. one which +can be used as argument for +\fB::pki:encrypt\fR, +\fB::pki::decrypt\fR, and +\fB::pki::verify\fR. +The \fIcert\fR argument can be either PEM or DER encoded. +.TP +\fB::pki::rsa::generate\fR \fIbitlength\fR ?\fIexponent\fR? +Generate a new RSA key pair, the parts of which can be used as +argument for +\fB::pki::encrypt\fR, +\fB::pki::decrypt\fR, +\fB::pki::sign\fR, and +\fB::pki::verify\fR. +The \fIbitlength\fR argument is the length of the public key modulus. +The \fIexponent\fR argument should generally not be specified unless +you really know what you are doing. +.TP +\fB::pki::x509::verify_cert\fR \fIcert\fR \fItrustedcerts\fR ?\fIintermediatecerts\fR? +Verify that a trust can be found between the certificate specified in the +\fIcert\fR argument and one of the certificates specified in the list +of certificates in the \fItrustedcerts\fR argument. (Eventually the +chain can be through untrusted certificates listed in the \fIintermediatecerts\fR +argument, but this is currently unimplemented). +The certificates specified in the \fIcert\fR and \fItrustedcerts\fR option +should be parsed (from \fB::pki::x509::parse_cert\fR). +.TP +\fB::pki::x509::validate_cert\fR \fIcert\fR ?\fB-sign_message\fR \fIdn_of_signer\fR? ?\fB-encrypt_message\fR \fIdn_of_signer\fR? ?\fB-sign_cert\fR \fIdn_to_be_signed\fR \fIca_depth\fR? ?\fB-ssl\fR \fIdn\fR? +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 \fB-sign_cert\fR option is functional. +Arguments for the \fB-sign_cert\fR option are \fIdn_to_be_signed\fR +and \fIca_depth\fR. The \fIdn_to_be_signed\fR is the distinguished from +the subject of a certificate to verify that the certificate specified in +the \fIcert\fR argument can sign. The \fIca_depth\fR 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. +.TP +\fB::pki::pkcs::create_csr\fR \fIkeylist\fR \fInamelist\fR ?\fIencodePem\fR? ?\fIalgo\fR? +Generate a certificate signing request from a key pair specified in +the \fIkeylist\fR argument. +The \fInamelist\fR argument is a list of "name" followed by "value" +pairs to encoding as the requested distinguished name in the CSR. +The \fIencodePem\fR 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 \fIalgo\fR 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". +.TP +\fB::pki::pkcs::parse_csr\fR \fIcsr\fR +Parse a Certificate Signing Request. The \fIcsr\fR argument can be +either PEM or DER encoded. +.TP +\fB::pki::x509::create_cert\fR \fIsignreqlist\fR \fIcakeylist\fR \fIserial_number\fR \fInotBefore\fR \fInotAfter\fR \fIisCA\fR \fIextensions\fR ?\fIencodePem\fR? ?\fIalgo\fR? +Sign a signing request (usually from \fB::pki::pkcs::create_csr\fR or +\fB::pki::pkcs::parse_csr\fR) with a Certificate Authority (CA) certificate. +The \fIsignreqlist\fR argument should be the parsed signing request. +The \fIcakeylist\fR argument should be the parsed CA certificate. +The \fIserial_number\fR argument should be a serial number unique to +this certificate from this certificate authority. +The \fInotBefore\fR and \fInotAfter\fR arguments should contain the +time before and after which (respectively) the certificate should +be considered invalid. The time should be encoded as something +\fBclock format\fR will accept (i.e., the results of \fBclock seconds\fR +and \fBclock add\fR). +The \fIisCA\fR 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 \fIextensions\fR 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 \fIcritical\fR \fIallowCA\fR \fIcaDepth\fR. The \fIcritical\fR +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 \fIallowCA\fR argument is used to specify +as a boolean value whether or not we can be used a certificate +authority (CA). The \fIcaDepth\fR argument indicates how many children +CAs can be children of this CA in a depth-wise fashion. A value of "0" +for the \fIcaDepth\fR argument means that this CA cannot sign a CA +certificate and have the result be valid. A value of "-1" indicates +infinite depth. +.PP +.SH EXAMPLES +.CS + + + +.CE +.CS + + + +.CE +.SH REFERENCES +.IP [1] +.PP +.SH AUTHORS +Roy Keene +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIrsa\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +aes(n), blowfish(n), des(n), md5(n), sha1(n) +.SH KEYWORDS +cipher, data integrity, encryption, public key cipher, rsa, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries + +.fi ADDED embedded/man/files/modules/pluginmgr/pluginmgr.n Index: embedded/man/files/modules/pluginmgr/pluginmgr.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pluginmgr/pluginmgr.n @@ -0,0 +1,599 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pluginmgr/pluginmgr.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pluginmgr" n 0.3 tcllib "Plugin management" +.BS +.SH NAME +pluginmgr \- Manage a plugin +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBpluginmgr ?0.3?\fR +.sp +\fB::pluginmgr\fR \fIobjectName\fR ?\fIoption value\fR...? +.sp +\fB::pluginmgr::paths\fR \fIobjectName\fR \fIname\fR... +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBclone\fR +.sp +\fIobjectName\fR \fBconfigure\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +.sp +\fIobjectName\fR \fBcget\fR \fB-option\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBdo\fR \fIarg\fR... +.sp +\fIobjectName\fR \fBinterpreter\fR +.sp +\fIobjectName\fR \fBplugin\fR +.sp +\fIobjectName\fR \fBload\fR \fIstring\fR +.sp +\fIobjectName\fR \fBunload\fR +.sp +\fIobjectName\fR \fBlist\fR +.sp +\fIobjectName\fR \fBpath\fR \fIpath\fR +.sp +\fIobjectName\fR \fBpaths\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands and objects for the generic management +of plugins which can be loaded into an application. +.PP +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 \fBpackage require\fR 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. +.PP +The main contribution of this package is a generic framework which +allows the easy declaration of +.IP [1] +How to translate a plugin name to the name of the package implementing +it, and vice versa. +.IP [2] +The list of commands a plugin has to provide as API, and also of more +complex checks as code. +.IP [3] +The list of commands expected by the plugin from the environment. +.PP +This then allows the easy generation of plugin managers customized to +particular types of plugins for an application. +.PP +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. +.SH "PUBLIC API" +.SS "PACKAGE COMMANDS" +.TP +\fB::pluginmgr\fR \fIobjectName\fR ?\fIoption value\fR...? +This command creates a new plugin manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBOBJECT COMMAND\fR +and \fBOBJECT METHODS\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.sp +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. +.TP +\fB::pluginmgr::paths\fR \fIobjectName\fR \fIname\fR... +This utility command adds a set of paths to the specified object, +based on the given \fIname\fRs. +It will search for: +.RS +.IP [1] +The environment variable \fB\fIname\fR_PLUGINS\fR. Its contents will +be interpreted as a list of package paths. The entries have to be +separated by either \fB:\fR (unix) or \fB;\fR (windows). +.sp +The name will be converted to upper-case letters. +.IP [2] +The registry entry "HKEY_LOCAL_MACHINE\\SOFTWARE\\\fIname\fR\\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by \fB;\fR. This item is considered +only when on Windows (tm). +.sp +The casing of letters is not changed. +.IP [3] +The registry entry "HKEY_CURRENT_USER\\SOFTWARE\\\fIname\fR\\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by \fB;\fR. This item is considered +only when on Windows (tm). +.sp +The casing of letters is not changed. +.IP [4] +The directory "\fI~/.\fIname\fR/plugin\fR". +.IP [5] +The directory "\fI~/.\fIname\fR/plugins\fR". +.sp +The casing of letters is not changed. +.RE +.sp +and add all the paths found that way to the list of package paths +maintained by the object. +.sp +If \fIname\fR is namespaced each item in the list will be repeated per +prefix of \fIname\fR, with conversion of :-sequences into the proper +separator (underscore for environment variables, backslash for +registry entries, and / for directories). +.sp +Examples: +.sp +.CS + + + ::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 + +.CE +.PP +.SS "OBJECT COMMAND" +All commands created by the command \fB::pluginmgr\fR (See section +\fBPACKAGE COMMANDS\fR) have the following general form and may +be used to invoke various operations on their plugin manager object. +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the exact +behavior of the command. See section \fBOBJECT METHODS\fR for +the detailed specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBclone\fR +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. +.TP +\fIobjectName\fR \fBconfigure\fR +The method returns a list of all known options and their current +values when called without any arguments. +.TP +\fIobjectName\fR \fBconfigure\fR \fIoption\fR +The method behaves like the method \fBcget\fR when called with a +single argument and returns the value of the option specified by said +argument. +.TP +\fIobjectName\fR \fBconfigure\fR \fB-option\fR \fIvalue\fR... +The method reconfigures the specified \fBoption\fRs of the object, +setting them to the associated \fIvalue\fRs, when called with an even +number of arguments, at least two. +.sp +The legal options are described in the section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBcget\fR \fB-option\fR +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. +.sp +The legal configuration options are described in section +\fBOBJECT CONFIGURATION\fR. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBdo\fR \fIarg\fR... +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. +.TP +\fIobjectName\fR \fBinterpreter\fR +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. +.TP +\fIobjectName\fR \fBplugin\fR +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. +.TP +\fIobjectName\fR \fBload\fR \fIstring\fR +This method loads, validates, and initializes a named plugin into the +manager object. +.sp +The algorithm to locate and load the plugin employed is: +.RS +.IP [1] +If the \fIstring\fR contains the path to an existing file then this +file is taken as the implementation of the plugin. +.IP [2] +Otherwise the plugin name is translated into a package name via the value +of the option \fB-pattern\fR and then loaded through the +regular package management. +.IP [3] +The load fails. +.RE +.sp +The algorithm to validate and initialize the loaded code is: +.RS +.IP [1] +If the option \fB-api\fR is non-empty introspection commands are +used to ascertain that the plugin provides the listed commands. +.IP [2] +If the option \fB-check\fR is non-empty the specified command +prefix is called. +.IP [3] +If either of the above fails the candidate plugin is unloaded again +.IP [4] +Otherwise all the commands specified via the option +\fB-cmds\fR are installed in the plugin. +.RE +.sp +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. +.TP +\fIobjectName\fR \fBunload\fR +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. +.TP +\fIobjectName\fR \fBlist\fR +This method uses the contents of the option \fB-pattern\fR 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. +.TP +\fIobjectName\fR \fBpath\fR \fIpath\fR +This methods adds the specified \fIpath\fR 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. +.TP +\fIobjectName\fR \fBpaths\fR +This method returns a list containing all additional paths which have +been added to the plugin manager object since its creation. +.PP +.SS "OBJECT CONFIGURATION" +All plugin manager objects understand the following configuration options: +.TP +\fB-pattern\fR \fIstring\fR +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. +.sp +This option has no default, except if option \fB-name\fR was set. +It has to be set before attempting to load a plugin, either directly, +or through option \fB-name\fR. +.TP +\fB-api\fR \fIlist\fR +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. +.TP +\fB-check\fR \fIcmdprefix\fR +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. +.sp +It is called with the manager object command as the only argument and +has to return a boolean value. A value of \fBtrue\fR 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 \fB-api\fR. +.sp +The default value is the empty list, which causes the manager object +to suppress the call and to assume the candidate plugin passes. +.TP +\fB-cmds\fR \fIdict\fR +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 \fB-cmdip\fR. +The default value is the empty dictionary. +.TP +\fB-cmdip\fR \fIipspec\fR +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. +.TP +\fB-setup\fR \fIcmdprefix\fR +The value of this option is interpreted as a command prefix. +.sp +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. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpluginmgr\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +plugin management, plugin search +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/png/png.n Index: embedded/man/files/modules/png/png.n ================================================================== --- /dev/null +++ embedded/man/files/modules/png/png.n @@ -0,0 +1,401 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/png/png.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net> +'\" Copyright (c) 2004, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "png" n 0.1.2 tcllib "Image manipulation" +.BS +.SH NAME +png \- PNG querying and manipulation of meta data +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBcrc32 \fR +.sp +package require \fBpng ?0.1.2?\fR +.sp +\fB::png::validate\fR \fIfile\fR +.sp +\fB::png::isPNG\fR \fIfile\fR +.sp +\fB::png::imageInfo\fR \fIfile\fR +.sp +\fB::png::getTimestamp\fR \fIfile\fR +.sp +\fB::png::setTimestamp\fR \fIfile\fR \fItime\fR +.sp +\fB::png::getComments\fR \fIfile\fR +.sp +\fB::png::removeComments\fR \fIfile\fR +.sp +\fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fItext\fR +.sp +\fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fIlang\fR \fIkeyword2\fR \fItext\fR +.sp +\fB::png::image\fR \fIfile\fR +.sp +\fB::png::write\fR \fIfile\fR \fIdata\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides commands to query and modify PNG images. PNG +stands for \fIPortable Network Graphics\fR and is specified at +\fIhttp://www.libpng.org/pub/png/spec/1.2\fR. +.SH COMMANDS +.TP +\fB::png::validate\fR \fIfile\fR +Returns a value indicating if \fIfile\fR 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 \fInot\fR 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. +.sp +Possible return values: +.RS +.TP +OK +File is a valid PNG file. +.TP +SIG +no/broken PNG signature. +.TP +BADLEN +corrupt chunk length. +.TP +EOF +premature end of file. +.TP +NOHDR +missing header chunk. +.TP +CKSUM +crc mismatch. +.TP +NODATA +missing data chunk(s). +.TP +NOEND +missing end marker. +.RE +.TP +\fB::png::isPNG\fR \fIfile\fR +Returns a boolean value indicating if the file \fIfile\fR starts with +a PNG signature. This is a much faster and less intensive check than +\fB::png::validate\fR as it does not check if the PNG data is valid. +.TP +\fB::png::imageInfo\fR \fIfile\fR +Returns a dictionary with keys \fBwidth\fR, \fBheight\fR, +\fBdepth\fR, \fBcolor\fR, \fBcompression\fR, \fBfilter\fR, and +\fBinterlace\fR. The values are the associated properties of the PNG +image in \fIfile\fR. +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 +\fIhttp://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html\fR. +.TP +\fB::png::getTimestamp\fR \fIfile\fR +Returns the epoch time if a timestamp chunk is found in the PNG image +contained in the \fIfile\fR, otherwise returns the empty string. Does +not attempt to verify the checksum of the timestamp chunk. +Throws an error if the \fIfile\fR is not a valid PNG image. +.TP +\fB::png::setTimestamp\fR \fIfile\fR \fItime\fR +Writes a new timestamp to the \fIfile\fR, either replacing the old +timestamp, or adding one just before the data chunks if there was no +previous timestamp. \fItime\fR is the new time in the gmt epoch +format. +Throws an error if \fIfile\fR is not a valid PNG image. +.TP +\fB::png::getComments\fR \fIfile\fR +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 \fIfile\fR is not a valid PNG image. +.TP +\fB::png::removeComments\fR \fIfile\fR +Removes all comments from the PNG image in \fIfile\fR. Beware - This +uses memory equal to the file size minus comments, to hold the +intermediate result. +Throws an error if \fIfile\fR is not a valid PNG image. +.TP +\fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fItext\fR +Adds a plain \fItext\fR comment to the PNG image in \fIfile\fR, just +before the first data chunk. Will throw an error if no data chunk is +found. \fIkeyword\fR has to be less than 80 characters long to conform +to the PNG specification. +.TP +\fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fIlang\fR \fIkeyword2\fR \fItext\fR +Adds a unicode (international) comment to the PNG image in \fIfile\fR, +just before the first data chunk. Will throw an error if no data chunk +is found. \fIkeyword\fR has to be less than 80 characters long to +conform to the PNG specification. \fIkeyword2\fR is the translated +\fIkeyword\fR, in the language specified by the language identifier +\fIlang\fR. +.TP +\fB::png::image\fR \fIfile\fR +Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor. +.TP +\fB::png::write\fR \fIfile\fR \fIdata\fR +Takes a list of scanlines in the Tk_GetColor format and writes the represented image +to \fIfile\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpng\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +comment, image, png, timestamp +.SH CATEGORY +File formats +.SH COPYRIGHT +.nf +Copyright (c) 2004, Code: Aaron Faupell <afaupell@users.sourceforge.net> +Copyright (c) 2004, Doc: Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pop3/pop3.n Index: embedded/man/files/modules/pop3/pop3.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pop3/pop3.n @@ -0,0 +1,481 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pop3/pop3.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pop3" n 1.9 tcllib "Tcl POP3 Client Library" +.BS +.SH NAME +pop3 \- Tcl client for POP3 email protocol +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBpop3 ?1.9?\fR +.sp +\fB::pop3::open\fR ?\fB-msex\fR 0|1? ?\fB-retr-mode\fR retr|list|slow? ?\fB-socketcmd\fR cmdprefix? ?\fB-stls\fR 0|1? ?\fB-tls-callback\fR stls-callback-command? \fIhost username password\fR ?\fIport\fR? +.sp +\fB::pop3::config\fR \fIchan\fR +.sp +\fB::pop3::status\fR \fIchan\fR +.sp +\fB::pop3::last\fR \fIchan\fR +.sp +\fB::pop3::retrieve\fR \fIchan startIndex\fR ?\fIendIndex\fR? +.sp +\fB::pop3::delete\fR \fIchan startIndex\fR ?\fIendIndex\fR? +.sp +\fB::pop3::list\fR \fIchan\fR ?\fImsg\fR? +.sp +\fB::pop3::top\fR \fIchan\fR \fImsg\fR \fIn\fR +.sp +\fB::pop3::uidl\fR \fIchan\fR ?\fImsg\fR? +.sp +\fB::pop3::capa\fR \fIchan\fR +.sp +\fB::pop3::close\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +The \fBpop3\fR package provides a simple Tcl-only client library +for the POP3 email protocol as specified in +\fIRFC 1939\fR [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 \fBcatch\fR +command. +.SH API +.TP +\fB::pop3::open\fR ?\fB-msex\fR 0|1? ?\fB-retr-mode\fR retr|list|slow? ?\fB-socketcmd\fR cmdprefix? ?\fB-stls\fR 0|1? ?\fB-tls-callback\fR stls-callback-command? \fIhost username password\fR ?\fIport\fR? +Open a socket connection to the server specified by \fIhost\fR, +transmit the \fIusername\fR and \fIpassword\fR as login information to +the server. The default port number is \fB110\fR, which can be +overridden using the optional \fIport\fR argument. The return value +is a channel used by all of the other ::pop3 functions. +.sp +The command recognizes three options +.RS +.TP +\fB-msex\fR 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 \fBFalse\fR. +.TP +\fB-retr-mode\fR retr|list|slow +The retrieval mode determines how exactly messages are read from the +server. +The allowed values are \fBretr\fR, \fBlist\fR and \fBslow\fR. +The default is \fBretr\fR. See \fB::pop3::retrieve\fR for more +information. +.TP +\fB-socketcmd\fR cmdprefix +This option allows the user to overide the use of the builtin +\fBsocket\fR 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 \fBtls::socket\fR. This command is +specially recognized as well, changing the default port of the +connection to \fB995\fR. +.TP +\fB-stls\fR 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 +.TP +\fB-tls-callback\fR stls-callback-command +This option allows the user to overide the \fBtls::callback\fR used during +the \fB-stls\fR SSL/TLS handshake. See the TLS manual for details on how +to implement this callback. +.RE +.TP +\fB::pop3::config\fR \fIchan\fR +Returns the configuration of the pop3 connection identified by the +channel handle \fIchan\fR as a serialized array. +.TP +\fB::pop3::status\fR \fIchan\fR +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. +.TP +\fB::pop3::last\fR \fIchan\fR +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. +.TP +\fB::pop3::retrieve\fR \fIchan startIndex\fR ?\fIendIndex\fR? +Retrieve a range of messages from the server. If the \fIendIndex\fR +is not specified, only one message will be retrieved. The return +value is a list containing each message as a separate element. See +the \fIstartIndex\fR and \fIendIndex\fR descriptions below. +.sp +The retrieval mode determines how exactly messages are read from the +server. The mode \fBretr\fR 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 \fBlist\fR 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, \fBslow\fR, 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. +.sp +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. +.TP +\fB::pop3::delete\fR \fIchan startIndex\fR ?\fIendIndex\fR? +Delete a range of messages from the server. If the \fIendIndex\fR 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 \fIstartIndex\fR and \fIendIndex\fR descriptions +below. +.RS +.TP +\fIstartIndex\fR +The \fIstartIndex\fR may be an index of a specific message starting +with the index 1, or it have any of the following values: +.RS +.TP +\fBstart\fR +This is a logical value for the first message in the spool, equivalent +to the value 1. +.TP +\fBnext\fR +The message immediately following the last message read, see +\fB::pop3::last\fR. +.TP +\fBend\fR +The most recent message in the spool (the end of the spool). This is +useful to retrieve only the most recent message. +.RE +.TP +\fIendIndex\fR +The \fIendIndex\fR is an optional parameter and defaults to the value +"-1", which indicates to only retrieve the one message specified by +\fIstartIndex\fR. 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: +.RS +.TP +\fBlast\fR +The message is the last message read by a POP3 client, see +\fB::pop3::last\fR. +.TP +\fBend\fR +The most recent message in the spool (the end of the spool). +.RE +.RE +.TP +\fB::pop3::list\fR \fIchan\fR ?\fImsg\fR? +Returns the scan listing of the mailbox. If parameter \fImsg\fR is +given, then the listing only for that message is returned. +.TP +\fB::pop3::top\fR \fIchan\fR \fImsg\fR \fIn\fR +Optional POP3 command, not all servers may support this. +\fB::pop3::top\fR retrieves headers of a message, specified by +parameter \fImsg\fR, and number of \fIn\fR lines from the message +body. +.TP +\fB::pop3::uidl\fR \fIchan\fR ?\fImsg\fR? +Optional POP3 command, not all servers may support this. +\fB::pop3::uidl\fR returns the uid listing of the mailbox. If the +parameter \fImsg\fR is specified, then the listing only for that +message is returned. +.TP +\fB::pop3::capa\fR \fIchan\fR +Optional POP3 command, not all servers may support this. +\fB::pop3::capa\fR returns a list of the capabilities of the server. +TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities. +See IETF RFC 2449. +.TP +\fB::pop3::close\fR \fIchan\fR +Gracefully close the connect after sending a POP3 QUIT command down +the socket. +.PP +.SH "SECURE MAIL TRANSFER" +A pop3 connection can be secured with SSL/TLS by requiring the package +\fBTLS\fR and then using either the option \fB-socketcmd\fR or +the option \fB-stls\fR of the command \fBpop3::open\fR. +The first method, option \fB-socketcmd\fR, will force the use +of the \fBtls::socket\fR command when opening the connection. This is +suitable for POP3 servers which expect SSL connections only. These will +generally be listening on port 995. +.CS + + + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create secured pop3 channel + pop3::open -socketcmd tls::socket \\\\ + $thehost $theuser $thepassword + + ... + +.CE +The second method, option \fB-stls\fR, 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. +.CS + + + package require tls + tls::init -cafile /path/to/ca/cert -keyfile ... + + # Create secured pop3 channel + pop3::open -stls 1 \\\\ + $thehost $theuser $thepassword + + ... + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpop3\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +email, mail, pop, pop3, rfc 1939, secure, ssl, tls +.SH CATEGORY +Networking ADDED embedded/man/files/modules/pop3d/pop3d.n Index: embedded/man/files/modules/pop3d/pop3d.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pop3d/pop3d.n @@ -0,0 +1,489 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pop3d/pop3d.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2005 Reinhard Max <max@suse.de> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pop3d" n 1.1.0 tcllib "Tcl POP3 Server Package" +.BS +.SH NAME +pop3d \- Tcl POP3 server implementation +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBpop3d ?1.1.0?\fR +.sp +\fB::pop3d::new\fR ?\fIserverName\fR? +.sp +\fBserverName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIserverName\fR \fBup\fR +.sp +\fIserverName\fR \fBdown\fR +.sp +\fIserverName\fR \fBdestroy\fR ?\fImode\fR? +.sp +\fIserverName\fR \fBconfigure\fR +.sp +\fIserverName\fR \fBconfigure\fR \fI-option\fR +.sp +\fIserverName\fR \fBconfigure\fR \fI-option value\fR... +.sp +\fIserverName\fR \fBcget\fR \fI-option\fR +.sp +\fIserverName\fR \fBconn\fR list +.sp +\fIserverName\fR \fBconn\fR state \fIid\fR +.sp +\fIauthCmd\fR \fBexists\fR \fIname\fR +.sp +\fIauthCmd\fR \fBlookup\fR \fIname\fR +.sp +\fIstorageCmd\fR \fBdele\fR \fImbox\fR \fImsgList\fR +.sp +\fIstorageCmd\fR \fBlock\fR \fImbox\fR +.sp +\fIstorageCmd\fR \fBunlock\fR \fImbox\fR +.sp +\fIstorageCmd\fR \fBsize\fR \fImbox\fR ?\fImsgId\fR? +.sp +\fIstorageCmd\fR \fBstat\fR \fImbox\fR +.sp +\fIstorageCmd\fR \fBget\fR \fImbox\fR \fImsgId\fR +.sp +.BE +.SH DESCRIPTION +.PP +.TP +\fB::pop3d::new\fR ?\fIserverName\fR? +This command creates a new server object with an associated global Tcl +command whose name is \fIserverName\fR. +.PP +The command \fBserverName\fR may be used to invoke various operations +on the server. It has the following general form: +.TP +\fBserverName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +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 (\fIhttp://www.rfc-editor.org/rfc/rfc1939.txt\fR). +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. +.PP +\fINote:\fR 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. +.PP +The following commands are possible for server objects: +.TP +\fIserverName\fR \fBup\fR +After this call the server will listen for connections on its configured port. +.TP +\fIserverName\fR \fBdown\fR +After this call the server will stop listening for connections. This +does not affect existing connections. +.TP +\fIserverName\fR \fBdestroy\fR ?\fImode\fR? +Destroys the server object. Currently open connections are handled +depending on the chosen mode. +The provided \fImode\fRs are: +.RS +.TP +\fBkill\fR +Destroys the server immediately, and forcefully closes all currently +open connections. This is the default mode. +.TP +\fBdefer\fR +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. +.RE +.TP +\fIserverName\fR \fBconfigure\fR +Returns a list containing all options and their current values in a +format suitable for use by the command \fBarray set\fR. The options +themselves are described in section \fBOptions\fR. +.TP +\fIserverName\fR \fBconfigure\fR \fI-option\fR +Returns the current value of the specified option. This is an alias +for the method \fBcget\fR. The options themselves are described in +section \fBOptions\fR. +.TP +\fIserverName\fR \fBconfigure\fR \fI-option value\fR... +Sets the specified option to the provided value. The options +themselves are described in section \fBOptions\fR. +.TP +\fIserverName\fR \fBcget\fR \fI-option\fR +Returns the current value of the specified option. The options +themselves are described in section \fBOptions\fR. +.TP +\fIserverName\fR \fBconn\fR list +Returns a list containing the ids of all connections currently open. +.TP +\fIserverName\fR \fBconn\fR state \fIid\fR +Returns a list suitable for [\fBarray set\fR] containing the +state of the connection referenced by \fIid\fR. +.PP +.SH OPTIONS +The following options are available to pop3 server objects. +.TP +\fB-port\fR \fIport\fR +Defines the \fIport\fR to listen on for new connections. Default is +110. This option is a bit special. If \fIport\fR is set to "0" the +server, or rather the operating system, will select a free port on its +own. When querying \fB-port\fR 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 +\fBdown\fR followed by a call to \fBup\fR will the new port take +effect. It is at that time that the value returned when querying +\fB-port\fR will change too. +.TP +\fB-auth\fR \fIcommand\fR +Defines a \fIcommand\fR 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 \fBAuthentication\fR. +.TP +\fB-storage\fR \fIcommand\fR +Defines a \fIcommand\fR 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 +\fBMailboxes\fR. +.TP +\fB-socket\fR \fIcommand\fR +Defines a \fIcommand\fR 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 \fBtls\fR package, see the command \fBtls::socket\fR. +.PP +.SH 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. +.TP +\fIauthCmd\fR \fBexists\fR \fIname\fR +This method is given a user\fIname\fR and has to return a boolean +value telling whether or not the specified user exists. +.TP +\fIauthCmd\fR \fBlookup\fR \fIname\fR +This method is given a user\fIname\fR and has to return a two-element +list containing the password for this user and a storage reference, in +this order. +.sp +The storage reference is passed unchanged to the storage callback, see +sections \fBOptions\fR and \fBMailboxes\fR for either the +option defining it and or the interface to provide, respectively. +.PP +.SH 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 \fImbox\fR argument is the storage reference +as returned by the \fBlookup\fR method of the authentication +command, see section \fBAuthentication\fR. +.TP +\fIstorageCmd\fR \fBdele\fR \fImbox\fR \fImsgList\fR +] +Deletes the messages whose numeric ids are contained in the +\fImsgList\fR from the mailbox specified via \fImbox\fR. +.TP +\fIstorageCmd\fR \fBlock\fR \fImbox\fR +This method locks the specified mailbox for use by a single connection +to the server. This is necessary to prevent havoc if several +connections to the same mailbox are open. The complementary method is +\fBunlock\fR. The command will return true if the lock could be set +successfully or false if not. +.TP +\fIstorageCmd\fR \fBunlock\fR \fImbox\fR +This is the complementary method to \fBlock\fR, it revokes the lock +on the specified mailbox. +.TP +\fIstorageCmd\fR \fBsize\fR \fImbox\fR ?\fImsgId\fR? +Determines the size of the message specified through its id in +\fImsgId\fR, in bytes, and returns this number. The command will +return the size of the whole maildrop if no message id was specified. +.TP +\fIstorageCmd\fR \fBstat\fR \fImbox\fR +Determines the number of messages in the specified mailbox and returns +this number. +.TP +\fIstorageCmd\fR \fBget\fR \fImbox\fR \fImsgId\fR +Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package \fBmime\fR. 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. +.PP +.SH "SECURE MAIL TRANSFER" +The option \fB-socket\fR (see \fBOptions\fR) enables users of +the package to override how the server opens its listening socket. +The envisioned main use is the specification of the \fBtls::socket\fR +command, see package \fBtls\fR, to secure the communication. +.CS + + + package require tls + tls::init \\\\ + ... + + pop3d::new S -socket tls::socket + ... + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpop3d\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +internet, network, pop3, protocol, rfc 1939, secure, ssl, tls +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2005 Reinhard Max <max@suse.de> + +.fi ADDED embedded/man/files/modules/pop3d/pop3d_dbox.n Index: embedded/man/files/modules/pop3d/pop3d_dbox.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pop3d/pop3d_dbox.n @@ -0,0 +1,408 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pop3d/pop3d_dbox.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pop3d::dbox" n 1.0.2 tcllib "Tcl POP3 Server Package" +.BS +.SH NAME +pop3d::dbox \- Simple mailbox database for pop3d +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBpop3d::dbox ?1.0.2?\fR +.sp +\fB::pop3d::dbox::new\fR ?\fIdbName\fR? +.sp +\fBdbName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIdbName\fR \fBdestroy\fR +.sp +\fIdbName\fR \fBbase\fR \fIbase\fR +.sp +\fIdbName\fR \fBadd\fR \fImbox\fR +.sp +\fIdbName\fR \fBremove\fR \fImbox\fR +.sp +\fIdbName\fR \fBmove\fR \fIold new\fR +.sp +\fIdbName\fR \fBlist\fR +.sp +\fIdbName\fR \fBexists\fR \fImbox\fR +.sp +\fIdbName\fR \fBlocked\fR \fImbox\fR +.sp +\fIdbName\fR \fBlock\fR \fImbox\fR +.sp +\fIdbName\fR \fBunlock\fR \fImbox\fR +.sp +\fIdbName\fR \fBstat\fR \fImbox\fR +.sp +\fIdbName\fR \fBsize\fR \fImbox\fR ?\fImsgId\fR? +.sp +\fIdbName\fR \fBdele\fR \fImbox msgList\fR +.sp +\fIstorageCmd\fR \fBget\fR \fImbox\fR \fImsgId\fR +.sp +.BE +.SH DESCRIPTION +.PP +The package \fBpop3d::dbox\fR 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 (\fIhttp://www.rfc-editor.org/rfc/rfc822.txt\fR) conformant +format. +.PP +Any mailbox object following the interface described below can be used +in conjunction with the pop3 server core provided by the package +\fBpop3d\fR. 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 +\fBpop3d\fR. +.PP +.TP +\fB::pop3d::dbox::new\fR ?\fIdbName\fR? +This command creates a new database object with an associated global +Tcl command whose name is \fIdbName\fR. +.PP +The command \fBdbName\fR may be used to invoke various operations on +the database. It has the following general form: +.TP +\fBdbName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +The following commands are possible for database objects: +.TP +\fIdbName\fR \fBdestroy\fR +Destroys the mailbox database and all transient data. The directory +associated with the object is not destroyed. +.TP +\fIdbName\fR \fBbase\fR \fIbase\fR +Defines the base directory containing the mailboxes to manage. If this +method is not called none of the following methods will work. +.TP +\fIdbName\fR \fBadd\fR \fImbox\fR +Adds a mailbox of name \fImbox\fR to the database. The name must be a +valid path component. +.TP +\fIdbName\fR \fBremove\fR \fImbox\fR +Removes the mailbox specified through \fImbox\fR, and the mails +contained therein, from the database. This method will fail if the +specified mailbox is locked. +.TP +\fIdbName\fR \fBmove\fR \fIold new\fR +Changes the name of the mailbox \fIold\fR to \fInew\fR. +.TP +\fIdbName\fR \fBlist\fR +Returns a list containing the names of all mailboxes in the directory +associated with the database. +.TP +\fIdbName\fR \fBexists\fR \fImbox\fR +Returns true if the mailbox with name \fImbox\fR exists in the +database, or false if not. +.TP +\fIdbName\fR \fBlocked\fR \fImbox\fR +Checks if the mailbox specified through \fImbox\fR is currently locked. +.TP +\fIdbName\fR \fBlock\fR \fImbox\fR +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 +\fBunlock\fR. The command will return true if the lock could be set +successfully or false if not. +.TP +\fIdbName\fR \fBunlock\fR \fImbox\fR +This is the complementary method to \fBlock\fR, it revokes the lock +on the specified mailbox. +.TP +\fIdbName\fR \fBstat\fR \fImbox\fR +Determines the number of messages in the specified mailbox and returns +this number. This method fails if the mailbox \fImbox\fR is not +locked. +.TP +\fIdbName\fR \fBsize\fR \fImbox\fR ?\fImsgId\fR? +Determines the size of the message specified through its id in +\fImsgId\fR, 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 \fImsgId\fR has to be in the range "1 ... [\fIdbName\fR \fBstat\fR]" +or this call will fail. If \fBstat\fR was not called before this +call, \fBsize\fR will assume that there are zero messages in the +mailbox. +.TP +\fIdbName\fR \fBdele\fR \fImbox msgList\fR +Deletes the messages whose numeric ids are contained in the +\fImsgList\fR from the mailbox specified via \fImbox\fR. +The \fImsgList\fR must not be empty or this call will fail. +The numeric ids in \fImsgList\fR have to be in the range "1 ... +[\fIdbName\fR \fBstat\fR]" or this +call will fail. If \fBstat\fR was not called +before this call, \fBdele\fR will assume +that there are zero messages in the mailbox. +.TP +\fIstorageCmd\fR \fBget\fR \fImbox\fR \fImsgId\fR +Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package \fBmime\fR. The token is \fIread-only\fR. In other +words, the caller is allowed to do anything with the token except to +modify it. +The \fImsgId\fR has to be in the range "1 ... +[\fIdbName\fR \fBstat\fR]" or this +call will fail. If \fBstat\fR was not called +before this call, \fBget\fR will assume +that there are zero messages in the mailbox. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpop3d\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +internet, network, pop3, protocol, rfc 822 +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pop3d/pop3d_udb.n Index: embedded/man/files/modules/pop3d/pop3d_udb.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pop3d/pop3d_udb.n @@ -0,0 +1,357 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pop3d/pop3d_udb.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pop3d::udb" n 1.0.1 tcllib "Tcl POP3 Server Package" +.BS +.SH NAME +pop3d::udb \- Simple user database for pop3d +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBpop3d::udb ?1.0.1?\fR +.sp +\fB::pop3d::udb::new\fR ?\fIdbName\fR? +.sp +\fBdbName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIdbName\fR \fBdestroy\fR +.sp +\fIdbName\fR \fBadd\fR \fIuser pwd storage\fR +.sp +\fIdbName\fR \fBremove\fR \fIuser\fR +.sp +\fIdbName\fR \fBrename\fR \fIuser newName\fR +.sp +\fIdbName\fR \fBlookup\fR \fIuser\fR +.sp +\fIdbName\fR \fBexists\fR \fIuser\fR +.sp +\fIdbName\fR \fBwho\fR +.sp +\fIdbName\fR \fBsave\fR ?\fIfile\fR? +.sp +\fIdbName\fR \fBread\fR \fIfile\fR +.sp +.BE +.SH DESCRIPTION +.PP +The package \fBpop3d::udb\fR provides simple in memory databases +which can be used in conjunction with the pop3 server core provided by +the package \fBpop3d\fR. The databases will use the names of users +as keys and associates passwords and storage references with them. +.PP +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 \fBpop3d\fR. +.PP +.TP +\fB::pop3d::udb::new\fR ?\fIdbName\fR? +This command creates a new database object with an associated global +Tcl command whose name is \fIdbName\fR. +.PP +The command \fBdbName\fR may be used to invoke various operations on +the database. It has the following general form: +.TP +\fBdbName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +The following commands are possible for database objects: +.TP +\fIdbName\fR \fBdestroy\fR +Destroys the database object. +.TP +\fIdbName\fR \fBadd\fR \fIuser pwd storage\fR +Add a new user or changes the data of an existing user. Stores +\fIpassword\fR and \fIstorage\fR reference for the given \fIuser\fR. +.TP +\fIdbName\fR \fBremove\fR \fIuser\fR +Removes the specified \fIuser\fR from the database. +.TP +\fIdbName\fR \fBrename\fR \fIuser newName\fR +Changes the name of the specified \fIuser\fR to \fInewName\fR. +.TP +\fIdbName\fR \fBlookup\fR \fIuser\fR +Searches the database for the specified \fIuser\fR 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 \fBpop3d\fR. +.TP +\fIdbName\fR \fBexists\fR \fIuser\fR +Returns true if the specified \fIuser\fR is known to the database, +else false. +.TP +\fIdbName\fR \fBwho\fR +Returns a list of users known to the database. +.TP +\fIdbName\fR \fBsave\fR ?\fIfile\fR? +Saves the contents of the database into the given \fIfile\fR. If the +file is not specified the system will use the path last used in a call +to \fIdbName\fR \fBread\fR. The generated file can be read by the +\fBread\fR method. +.TP +\fIdbName\fR \fBread\fR \fIfile\fR +Reads the specified \fIfile\fR and adds the contained user definitions +to the database. As the file is actually \fBsource\fR'd a safe +interpreter is employed to safeguard against malicious code. This +interpreter knows the \fBadd\fR command for adding users and their +associated data to this database. This command has the same argument +signature as the method \fBadd\fR. The path of the \fIfile\fR is +remembered internally so that it can be used in the next call of +\fIdbName\fR \fBsave\fR without an argument. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpop3d\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +internet, network, pop3, protocol +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/profiler/profiler.n Index: embedded/man/files/modules/profiler/profiler.n ================================================================== --- /dev/null +++ embedded/man/files/modules/profiler/profiler.n @@ -0,0 +1,356 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/profiler/profiler.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "profiler" n 0.3 tcllib "Tcl Profiler" +.BS +.SH NAME +profiler \- Tcl source code profiler +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBprofiler ?0.3?\fR +.sp +\fB::profiler::init\fR +.sp +\fB::profiler::dump\fR \fIpattern\fR +.sp +\fB::profiler::print\fR ?\fIpattern\fR? +.sp +\fB::profiler::reset\fR ?\fIpattern\fR? +.sp +\fB::profiler::suspend\fR ?\fIpattern\fR? +.sp +\fB::profiler::resume\fR ?\fIpattern\fR? +.sp +\fB::profiler::sortFunctions\fR \fIkey\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBprofiler\fR 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 \fBproc\fR command. +Profiling is initiated via the \fB::profiler::init\fR command. +.SH COMMANDS +.TP +\fB::profiler::init\fR +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. +.TP +\fB::profiler::dump\fR \fIpattern\fR +Dump profiling information for the all functions matching +\fIpattern\fR. 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: +.RS +.TP +\fBtotalCalls\fR +The total number of times \fIfunctionName\fR was called. +.TP +\fBcallerDist\fR +A list of key/value pairs mapping each calling function that called +\fIfunctionName\fR to the number of times it called +\fIfunctionName\fR. +.TP +\fBcompileTime\fR +The runtime, in clock clicks, of \fIfunctionName\fR the first time +that it was called. +.TP +\fBtotalRuntime\fR +The sum of the runtimes of all calls of \fIfunctionName\fR. +.TP +\fBaverageRuntime\fR +Average runtime of \fIfunctionName\fR. +.TP +\fBdescendantTime\fR +Sum of the time spent in descendants of \fIfunctionName\fR. +.TP +\fBaverageDescendantTime\fR +Average time spent in descendants of \fIfunctionName\fR. +.RE +.TP +\fB::profiler::print\fR ?\fIpattern\fR? +Print profiling information for all functions matching \fIpattern\fR. +If no pattern is specified, information about all functions will be +displayed. The return result is a human readable display of the +profiling information. +.TP +\fB::profiler::reset\fR ?\fIpattern\fR? +Reset profiling information for all functions matching \fIpattern\fR. +If no pattern is specified, information will be reset for all +functions. +.TP +\fB::profiler::suspend\fR ?\fIpattern\fR? +Suspend profiling for all functions matching \fIpattern\fR. 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. +.TP +\fB::profiler::resume\fR ?\fIpattern\fR? +Resume profiling for all functions matching \fIpattern\fR. If no +pattern is specified, profiling will be resumed for all functions. +This command should be invoked after suspending the profiler in the +code. +.TP +\fB::profiler::sortFunctions\fR \fIkey\fR +Return a list of functions sorted by a particular profiling statistic. +Supported values for \fIkey\fR are: \fBcalls\fR, +\fBexclusiveTime\fR, \fBcompileTime\fR, \fBnonCompileTime\fR, +\fBtotalRuntime\fR, \fBavgExclusiveTime\fR, and +\fBavgRuntime\fR. The return result is a list of lists, where each +sublist consists of a function name and the value of \fIkey\fR for +that function. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIprofiler\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +performance, profile, speed +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/pt/pt.n Index: embedded/man/files/modules/pt/pt.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt.n @@ -0,0 +1,920 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt \- Parser Tools Application +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +\fBpt\fR \fBgenerate\fR \fIresultformat\fR ?\fIoptions...\fR? \fIresultfile\fR \fIinputformat\fR \fIinputfile\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This document describes \fBpt\fR, the main application of the module, +a \fIparser generator\fR. 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 \fBInternals\fR for the basic references. +.PP +It resides in the User Application Layer of Parser Tools. +.PP +IMAGE: arch_user_app +.PP +.SH "COMMAND LINE" +.TP +\fBpt\fR \fBgenerate\fR \fIresultformat\fR ?\fIoptions...\fR? \fIresultfile\fR \fIinputformat\fR \fIinputfile\fR +This sub-command of the application reads the parsing expression +grammar stored in the \fIinputfile\fR in the format \fIinputformat\fR, +converts it to the \fIresultformat\fR under the direction of the +(format-specific) set of options specified by the user and stores the +result in the \fIresultfile\fR. +.sp +The \fIinputfile\fR has to exist, while the \fIresultfile\fR may be +created, overwriting any pre-existing content of the file. Any missing +directory in the path to the \fIresultfile\fR will be created as well. +.sp +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: +.sp +.RS +.TP +\fBc\fR +A \fIresultformat\fR. See section \fBC Parser\fR. +.TP +\fBcontainer\fR +A \fIresultformat\fR. See section \fBGrammar Container\fR. +.TP +\fBcritcl\fR +A \fIresultformat\fR. See section \fBC Parser Embedded In Tcl\fR. +.TP +\fBjson\fR +A \fIinput\fR- and \fIresultformat\fR. See section \fBJSON Grammar Exchange\fR. +.TP +\fBoo\fR +A \fIresultformat\fR. See section \fBTclOO Parser\fR. +.TP +\fBpeg\fR +A \fIinput\fR- and \fIresultformat\fR. See section \fBPEG Specification Language\fR. +.TP +\fBsnit\fR +A \fIresultformat\fR. See section \fBSnit Parser\fR. +.RE +.PP +Of the seven possible results four are parsers outright (\fBc\fR, +\fBcritcl\fR, \fBoo\fR, and \fBsnit\fR), one (\fBcontainer\fR) +provides code which can be used in conjunction with a generic parser +(also known as a grammar interpreter), and the last two (\fBjson\fR +and \fBpeg\fR) are doing double-duty as input formats, allowing the +transformation of grammars for exchange, reformatting, and the like. +.PP +The created parsers fall into three categories: +.PP +.PS +.nf + + --- C ---> critcl, c + | + + --- specialized -+ + | | + ---+ + --- Tcl -> snit, oo + | + + --- interpreted (Tcl) ------> container +.fi +.PE +.PP +.TP +\fBSpecialized parsers implemented in C\fR +The fastest parsers are created when using the result formats +\fBc\fR and \fBcritcl\fR. The first returns the raw C code for the +parser, while the latter wraps it into a Tcl package using +\fICriTcl\fR. +.sp +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 \fBcritcl\fR format +doesn't support. As such the \fBc\fR format is meant for more +advanced users, or users with special needs. +.sp +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. +.TP +\fBSpecialized parsers implemented in Tcl\fR +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. +.sp +The relevant formats are \fBsnit\fR and \fBoo\fR. Both place their +result into a Tcl package containing a \fBsnit::type\fR, or TclOO +\fBclass\fR respectively. +.sp +Of the supporting runtime, which is the package \fBpt::rde\fR, 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 \fInot\fR required by the parsers' users. +.TP +\fBInterpreted parsing implemented in Tcl\fR +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. +.sp +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. +.sp +The relevant result format is \fBcontainer\fR. +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 \fBpt::peg::interp\fR. +.PP +All the parsers generated by \fBcritcl\fR, \fBsnit\fR, and +\fBoo\fR, 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 \fIParser API\fR specification document. +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +For either an introduction to or the formal specification of the +language, please go and read the \fIPEG Language Tutorial\fR. +.PP +When used as a result-format this format supports the following +options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBPEG\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated text. +.RE +.PP +.SH "JSON GRAMMAR EXCHANGE" +The \fBjson\fR 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. +.PP +For the formal specification of the JSON grammar exchange format, +please go and read \fIThe JSON Grammar Exchange Format\fR. +.PP +When used as a result-format this format supports the following +options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-indented\fR 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. +.sp +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. +.TP +\fB-aligned\fR 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 \fB-indented\fR is set. +.sp +If the option is not set (the default), the output is formatted as per +the value of \fBindented\fR, without trying to align the values for +dictionary keys. +.PP +.SH "C PARSER EMBEDDED IN TCL" +The \fBcritcl\fR 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 \fBcritcl\fR package. +.PP +This result-format supports the following options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-class\fR string +The value of this option is the name of the class to generate, without +leading colons. +The default value is \fBCLASS\fR. +.sp +For a simple value \fBX\fR without colons, like CLASS, the parser +command will be \fBX\fR::\fBX\fR. Whereas for a namespaced value +\fBX::Y\fR the parser command will be \fBX::Y\fR. +.TP +\fB-package\fR string +The value of this option is the name of the package to generate. +The default value is \fBPACKAGE\fR. +.PP +.SH "C PARSER" +The \fBc\fR 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. +.PP +The \fBcritcl\fR format, for example, is implemented as a canned +configuration of these options on top of the generator for \fBc\fR. +.PP +This result-format supports the following options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBC/PARAM\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated Tcl code. +.RE +.IP +The following options are special, in that they will +occur within the generated code, and are replaced there as well. +.RS +.TP +\fB@statedecl@\fR +To be replaced with the value of the option \fBstate-decl\fR. +.TP +\fB@stateref@\fR +To be replaced with the value of the option \fBstate-ref\fR. +.TP +\fB@strings@\fR +To be replaced with the value of the option \fBstring-varname\fR. +.TP +\fB@self@\fR +To be replaced with the value of the option \fBself-command\fR. +.TP +\fB@def@\fR +To be replaced with the value of the option \fBfun-qualifier\fR. +.TP +\fB@ns@\fR +To be replaced with the value of the option \fBnamespace\fR. +.TP +\fB@main@\fR +To be replaced with the value of the option \fBmain\fR. +.TP +\fB@prelude@\fR +To be replaced with the value of the option \fBprelude\fR. +.RE +.TP +\fB-state-decl\fR 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 \fBRDE_PARAM p\fR. +.TP +\fB-state-ref\fR 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 \fBp\fR. +.TP +\fB-self-command\fR 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. +.TP +\fB-fun-qualifier\fR string +A C string containing the attributes to give to the generated +functions (methods ...), per the chosen framework (template). +The default value is \fBstatic\fR. +.TP +\fB-namespace\fR 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. +.TP +\fB-main\fR string +The name of the main function (method, ...) to be called by the chosen +framework (template) to start parsing input. +The default value is \fB__main\fR. +.TP +\fB-string-varname\fR 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 \fBp_string\fR. +.TP +\fB-prelude\fR string +A snippet of code to be inserted at the head of each generated parsing +function. +The default value is the empty string. +.TP +\fB-indent\fR integer +The number of characters to indent each line of the generated code by. +The default value is \fB0\fR. +.PP +.SH "SNIT PARSER" +The \fBsnit\fR format is executable code, a parser for the +grammar. It is a Tcl package holding a \fBsnit::type\fR, i.e. a class, +whose instances are parsers for the input grammar. +.PP +This result-format supports the following options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-class\fR 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 \fB-package\fR is not specified, see below. +The default value is \fBCLASS\fR, applying if neither option +\fB-class\fR nor \fB-package\fR were specified. +.TP +\fB-package\fR 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 \fB-class\fR is not specified, see above. +The default value is \fBPACKAGE\fR, applying if neither option +\fB-package\fR nor \fB-class\fR were specified. +.PP +.SH "TCLOO PARSER" +The \fBoo\fR format is executable code, a parser for the grammar. It +is a Tcl package holding a \fBTclOO\fR class, whose instances are +parsers for the input grammar. +.PP +This result-format supports the following options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-class\fR 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 \fB-package\fR is not specified, see below. +The default value is \fBCLASS\fR, applying if neither option +\fB-class\fR nor \fB-package\fR were specified. +.TP +\fB-package\fR 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 \fB-class\fR is not specified, see above. +The default value is \fBPACKAGE\fR, applying if neither option +\fB-package\fR nor \fB-class\fR were specified. +.PP +.SH "GRAMMAR CONTAINER" +The \fBcontainer\fR 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 \fBpt::peg::interp\fR, a grammar +interpreter. +.PP +The format represents grammars by a \fBsnit::type\fR, i.e. class, +whose instances are API-compatible to the instances of the +\fBpt::peg::container\fR package, and which are preloaded with the +grammar in question. +.PP +This result-format supports the following options: +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-mode\fR \fBbulk\fR|\fBincremental\fR +The value of this option controls which methods of +\fBpt::peg::container\fR 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 \fBbulk\fR. +.RS +.TP +\fBbulk\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmodes\fR, +and \fBrules\fR 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. +.sp +This mode is the default. +.TP +\fBincremental\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmode\fR, +and \fBrule\fR are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands. +.RE +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBCONTAINER\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@mode@\fR +To be replaced with the value of the option \fB-mode\fR. +.TP +\fB@code@\fR +To be replaced with the generated code. +.RE +.PP +.SH 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: +.PP +IMAGE: flow +.PP +Our grammar, assumed to the stored in the file "\fIcalculator.peg\fR" +is +.CS + + +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; + +.CE +From this we create a snit-based parser +via +.CS + + +pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg + +.CE +which leaves us with the parser package and class written to the file +"\fIcalculator.tcl\fR". +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 +.CS + + + 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 ... + +.CE +where the abstract syntax tree stored in the variable will look like +.PP +.CS + + +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} + } + } + } +} + +.CE +.PP +assuming that the input file and channel contained the text +.CS + + 120+5 +.CE +A more graphical representation of the tree would be +.PP +.PS +.nf + +- Digit 0 0 | 1 + | | + +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 + | | | + | +- Digit 2 2 | 0 + | | +Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + + | | + +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 +.fi +.PE +.PP +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 \fBpt::ast\fR should be of help +here, providing commands to walk such ASTs structures in various ways. +.PP +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 \fIno\fR callbacks during the +parsing process, i.e. no \fIparsing actions\fR, as most other +parsers will have. +.PP +Going back to the last snippet of code, the execution of the parser +for some input, note how the parser instance follows the specified +\fIParser API\fR. +.SH 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. +.PP +The main functionality of the application is encapsulated in the +package \fBpt::pgen\fR. Please read it for more information. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_astree.n Index: embedded/man/files/modules/pt/pt_astree.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_astree.n @@ -0,0 +1,526 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_astree.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::ast" n 1.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::ast \- Abstract Syntax Tree Serialization +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::ast ?1.1?\fR +.sp +\fB::pt::ast\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +.sp +\fB::pt::ast\fR \fBverify-as-canonical\fR \fIserial\fR +.sp +\fB::pt::ast\fR \fBcanonicalize\fR \fIserial\fR +.sp +\fB::pt::ast\fR \fBprint\fR \fIserial\fR +.sp +\fB::pt::ast\fR \fBbottomup\fR \fIcmdprefix\fR \fIast\fR +.sp +\fBcmdprefix\fR \fIast\fR +.sp +\fB::pt::ast\fR \fBtopdown\fR \fIcmdprefix\fR \fIpe\fR +.sp +\fB::pt::ast\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +.sp +\fB::pt::ast\fR \fBterminal\fR \fIloc\fR +.sp +\fB::pt::ast\fR \fBnonterminal\fR \fIs\fR \fIstart\fR \fIend\fR ?\fIchild\fR...? +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package provides commands to work with the serializations of +abstract syntax trees as managed by the Parser Tools, and specified in +section \fBAST serialization format\fR. +.PP +This is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::ast\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +This command verifies that the content of \fIserial\fR 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. +.sp +If the argument \fIcanonvar\fR 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 \fIserial\fR is a valid regular +serialization. Its value will be a boolean, with \fBTrue\fR +indicating that the serialization is not only valid, but also +\fIcanonical\fR. \fBFalse\fR will be written for a valid, but +non-canonical serialization. +.sp +For the specification of serializations see the section +\fBAST serialization format\fR. +.TP +\fB::pt::ast\fR \fBverify-as-canonical\fR \fIserial\fR +This command verifies that the content of \fIserial\fR is a valid +\fIcanonical\fR 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. +.sp +For the specification of canonical serializations see the section +\fBAST serialization format\fR. +.TP +\fB::pt::ast\fR \fBcanonicalize\fR \fIserial\fR +This command assumes that the content of \fIserial\fR is a valid +\fIregular\fR serialization of an abstract syntax and will throw an +error if that is not the case. +.sp +It will then convert the input into the \fIcanonical\fR serialization +of the contained tree and return it as its result. If the input is +already canonical it will be returned unchanged. +.sp +For the specification of regular and canonical serializations see the +section \fBAST serialization format\fR. +.TP +\fB::pt::ast\fR \fBprint\fR \fIserial\fR +This command assumes that the argument \fIserial\fR contains a valid +serialization of an abstract syntax tree and returns a string +containing that tree in a human readable form. +.sp +The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities. +.sp +For the specification of serializations see the section +\fBAST serialization format\fR. +.TP +\fB::pt::ast\fR \fBbottomup\fR \fIcmdprefix\fR \fIast\fR +This command walks the abstract syntax tree \fIast\fR from the bottom +up to the root, invoking the command prefix \fIcmdprefix\fR for each +node. This implies that the children of a node N are handled before N. +.sp +The command prefix has the signature +.RS +.TP +\fBcmdprefix\fR \fIast\fR +I.e. it is invoked with the ast node the walk is currently at. +.sp +The result returned by the command prefix replaces \fIast\fR in the +node it was a child of, allowing transformations of the tree. +.sp +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. +.RE +.TP +\fB::pt::ast\fR \fBtopdown\fR \fIcmdprefix\fR \fIpe\fR +This command walks the abstract syntax tree \fIast\fR from the root +down to the leaves, invoking the command prefix \fIcmdprefix\fR for +each node. This implies that the children of a node N are handled +after N. +.sp +The command prefix has the same signature as for \fBbottomup\fR, +see above. +.sp +The result returned by the command prefix is \fIignored\fR. +.TP +\fB::pt::ast\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +This command tests the two sbstract syntax trees \fIseriala\fR and +\fIserialb\fR for structural equality. The result of the command is a +boolean value. It will be set to \fBtrue\fR if the trees are +identical, and \fBfalse\fR otherwise. +.sp +String equality is usable only if we can assume that the two trees are +pure Tcl lists. +.TP +\fB::pt::ast\fR \fBterminal\fR \fIloc\fR +This command command constructs the ast for a terminal node refering +to the position \fIloc\fR in the input, and returns it as the result +of the command. +.TP +\fB::pt::ast\fR \fBnonterminal\fR \fIs\fR \fIstart\fR \fIend\fR ?\fIchild\fR...? +This command command constructs the ast for a nonterminal node +refering to the symbol \fIs\fR covering the range of positions +\fIstart\fR to \fIend\fR in the input, and the set of child nodes +\fIchild\fR ..., from left right. The latter may be empty. The +constructed node is returned as the result of the command. +.PP +.SH "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. +.PP +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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.IP [1] +The serialization of any AST is the serialization of its root node. +.IP [2] +The serialization of any node is a Tcl list containing at least three +elements. +.RS +.IP [1] +The first element is the name of the nonterminal symbol stored in the +node. +.IP [2] +The second and third element are the locations of the first and last +token in the token stream the node represents (covers). +.RS +.IP [1] +Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero). +.IP [2] +The end location has to be equal to or larger than the start location. +.RE +.IP [3] +All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression grammar below +.PP +.CS + + +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; + +.CE +.PP +and the input string +.CS + + 120+5 +.CE +then a parser should deliver the abstract syntax tree below (except for whitespace) +.PP +.CS + + +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} + } + } + } +} + +.CE +.PP +Or, more graphical +.PP +.PS +.nf + +- Digit 0 0 | 1 + | | + +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 + | | | + | +- Digit 2 2 | 0 + | | +Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + + | | + +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 +.fi +.PE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_cparam_config_critcl.n Index: embedded/man/files/modules/pt/pt_cparam_config_critcl.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_cparam_config_critcl.n @@ -0,0 +1,302 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_cparam_config_critcl.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::cparam::configuration::critcl" n 1.0.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::cparam::configuration::critcl \- C/PARAM, Canned configuration, Critcl +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::cparam::configuration::critcl ?1.0.1?\fR +.sp +\fB::pt::cparam::configuration::critcl\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package is an adjunct to \fBpt::peg::to::cparam\fR, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package \fBpt::peg::to::cparam\fR to generate +\fBcritcl\fR-based parser packages. +.PP +It is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::cparam::configuration::critcl\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +The command applies the configuration provided by this package to the +\fIcmdprefix\fR, causing the creation of \fBcritcl\fR-based parsers +whose class is \fIname\fR. +.sp +The use of a command prefix as API allows application of the +configuration to not only \fBpt::peg::to::cparam\fR +(\fBpt::peg::to::cparam configure\fR), but also export manager +instances and PEG containers (\fB$export configuration set\fR and +\fB[$container exporter] configuration set\fR respectively). +.sp +Or anything other command prefix accepting two arguments, option and +value. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_from_api.n Index: embedded/man/files/modules/pt/pt_from_api.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_from_api.n @@ -0,0 +1,739 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_from_api.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt_import_api" i 1 tcllib "Parser Tools" +.BS +.SH NAME +pt_import_api \- Parser Tools Import API +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +\fBCONVERTER\fR \fBconvert\fR \fItext\fR +.sp +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +.sp +\fB::import\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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. +.PP +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. +.PP +It resides in the Import section of the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_import +.PP +.SH "CONVERTER API" +Any (grammar) import converter has to follow the rules set out below: +.IP [1] +A converter is a package. Its name is arbitrary, however it is +recommended to put it under the \fB::pt::peg::from\fR +namespace. +.IP [2] +The package provides either a single Tcl command following the +API outlined below, or a class command whose instances follow +the same API. The commands which follow the API are called +\fIconverter commands\fR. +.IP [3] +A converter command has to provide the following single method +with the given signature and semantic. Converter commands +are allowed to provide more methods of their own, but not +less, and they may not provide different semantics for the +standardized method. +.RS +.TP +\fBCONVERTER\fR \fBconvert\fR \fItext\fR +This method has to accept some \fItext\fR, 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 +\fBPEG serialization format\fR, the result of reading and +converting the input text. +.RE +.PP +.SH "PLUGIN API" +Any (grammar) import plugin has to follow the rules set out below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +pt::peg::import::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +accept input for. +.IP [3] +The plugin can expect that the package +\fBpt::peg::import::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.sp +It is recommended that a plugin does check for the presence of +this package. +.IP [4] +The plugin can expect that a command named \fBIncludeFile\fR +is present, with the signature +.RS +.TP +\fBIncludeFile\fR \fIcurrentfile\fR \fIpath\fR +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. +.sp +The plugin has to supply the following arguments +.RS +.TP +string \fIcurrentfile\fR +The path of the file it is currently processing. This may be the empty +string if no such is known. +.TP +string \fIpath\fR +The path of the include file as specified in the include directive +being processed. +.RE +.IP +The result of the command will be a 5-element list containing +.RS +.IP [1] +A boolean flag indicating the success (\fBTrue\fR) or failure +(\fBFalse\fR) of the operation. +.IP [2] +In case of success the contents of the included file, and the +empty string otherwise. +.IP [3] +The resolved, i.e. absolute path of the included file, if +possible, or the unchanged \fIpath\fR argument. This is for +display in an error message, or as the \fIcurrentfile\fR +argument of another call to \fBIncludeFile\fR should this file +contain more files. +.IP [4] +In case of success an empty string, and for failure a code +indicating the reason for it, one of +.RS +.TP +notfound +The specified file could not be found. +.TP +notread +The specified file was found, but not be read into memory. +.RE +.IP [5] +An empty string in case of success of a \fBnotfound\fR +failure, and an additional error message describing the reason +for a \fBnotread\fR error in more detail. +.RE +.RE +.IP [5] +A plugin has to provide a single command, in the global +namespace, with the signature shown below. Plugins are allowed +to provide more commands of their own, but not less, and they +may not provide different semantics for the standardized +command. +.RS +.TP +\fB::import\fR \fItext\fR +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. +.RS +.TP +string \fItext\fR +This argument will contain the parsing expression grammar for which to +generate the serialization. +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBPEG serialization format\fR. +.RE +.RE +.IP [6] +A single usage cycle of a plugin consists of an invokation of +the command \fBimport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH USAGE +To use a converter do +.CS + + + # Get the converter (single command here, not class) + package require the-converter-package + + # Perform the conversion + set serial [theconverter convert $thegrammartext] + + ... process the result ... + +.CE +To use a plugin \fBFOO\fR do +.CS + + + # 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 ... + +.CE +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_introduction.n Index: embedded/man/files/modules/pt/pt_introduction.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_introduction.n @@ -0,0 +1,411 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_introduction.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt_introduction" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt_introduction \- Introduction to Parser Tools +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +Welcome to the Parser Tools, a system for the creation and +manipulation of parsers and the grammars driving them. +.PP +What are your goals which drove you here ? +.IP [1] +Do you simply wish to create a parser for some language ? +.sp +In that case have a look at our parser generator application, +\fBpt\fR, or, for a slightly deeper access, the package underneath it, +\fBpt::pgen\fR. +.IP [2] +Do you wish to know more about the architecture of the system ? +.sp +This is described in the section +\fBParser Tools Architecture\fR, below +.IP [3] +Is your interest in the theoretical background upon which the packages +and tools are build ? +.sp +See the \fIIntroduction to Parsing Expression Grammars\fR. +.PP +.SH "PARSER TOOLS ARCHITECTURE" +The system can be split into roughly three layers, as seen in the +figure below +.PP +IMAGE: architecture +.PP +These layers are, from high to low: +.IP [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 \fBpt::pgen\fR which provides a parser generator. +.sp +The list of packages belonging to this layer can be found in section +\fBUser Packages\fR +.IP [2] +In this layer we have the packages which provide the core of the +functionality for the whole system. They are, in essence, a set of +blocks which can be combined in myriad ways, like Lego (tm). The +packages in the previous level are 'just' pre-fabricated combinations +to cover the most important use cases. +.sp +The list of packages belonging to this layer can be found in section +\fBCore Packages\fR +.IP [3] +Last, but not least is the layer containing support packages providing +generic functionality which not necessarily belong into the module. +.sp +The list of packages belonging to this layer can be found in section +\fBSupport Packages\fR +.PP +.SS "USER PACKAGES" +.TP +\fBpt::pgen\fR +.PP +.SS "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. +.TP +Storage +.RS +.TP +\fBpt::peg::container\fR +.RE +.TP +Export +.RS +.TP +\fBpt::peg::export\fR +.TP +\fBpt::peg::export::container\fR +.TP +\fBpt::peg::export::json\fR +.TP +\fBpt::peg::export::peg\fR +.TP +\fBpt::peg::to::container\fR +.TP +\fBpt::peg::to::json\fR +.TP +\fBpt::peg::to::peg\fR +.TP +\fBpt::peg::to::param\fR +.TP +\fBpt::peg::to::tclparam\fR +.TP +\fBpt::peg::to::cparam\fR +.RE +.TP +Import +.RS +.TP +\fBpt::peg::import\fR +.TP +\fBpt::peg::import::container\fR +.TP +\fBpt::peg::import::json\fR +.TP +\fBpt::peg::import::peg\fR +.TP +\fBpt::peg::from::container\fR +.TP +\fBpt::peg::from::json\fR +.TP +\fBpt::peg::from::peg\fR +.RE +.TP +Transformation +.TP +Execution +.RS +.TP +\fBpt::peg::interp\fR +.TP +\fBpt::rde\fR +.RE +.TP +Support +.RS +.TP +\fBpt::tclparam::configuration::snit\fR +.TP +\fBpt::tclparam::configuration::tcloo\fR +.TP +\fBpt::cparam::configuration::critcl\fR +.TP +\fBpt::ast\fR +.TP +\fBpt::pe\fR +.TP +\fBpt::peg\fR +.RE +.PP +.SS "SUPPORT PACKAGES" +.TP +\fBpt::peg::container::peg\fR +.TP +\fBtext::write\fR +.TP +\fBconfiguration\fR +.TP +\fBpaths\fR +.TP +\fBchar\fR +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_json_language.n Index: embedded/man/files/modules/pt/pt_json_language.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_json_language.n @@ -0,0 +1,732 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_json_language.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::json_language" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::json_language \- The JSON Grammar Exchange Format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +The \fBjson\fR 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. +.PP +It is formally specified by the rules below: +.IP [1] +The JSON of any PEG is a JSON object. +.IP [2] +This object holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section \fBPE serialization format\fR. +.TP +\fBmode\fR +The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +\fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.PP +.PP +As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +\fBPEG serialization format\fR, 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. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +a JSON serialization for it is +.PP +.CS + + +{ + "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" + } +} + +.CE +.PP +and a Tcl serialization of the same is +.PP +.CS + + +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} +} + +.CE +.PP +The similarity of the latter to the JSON should be quite obvious. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_param.n Index: embedded/man/files/modules/pt/pt_param.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_param.n @@ -0,0 +1,757 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_param.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::param" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::param \- PackRat Machine Specification +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +Welcome to the PackRat Machine (short: \fIPARAM\fR), 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. +.PP +This document specifies the machine in terms of its architectural +state and instruction set. +.SH "ARCHITECTURAL STATE" +Any PARAM implementation has to manage at least the following state: +.TP +\fIInput\fR (IN) +This is the channel the characters to process are read from. +.sp +This part of the machine's state is used and modified by the +instructions defined in the section \fBInput Handling\fR. +.TP +\fICurrent Character\fR (CC) +The character from the \fIinput\fR currently tested against its +possible alternatives. +.sp +This part of the machine's state is used and modified by the +instructions defined in the section \fBCharacter Processing\fR. +.TP +\fICurrent Location\fR (CL) +The location of the \fIcurrent character\fR in the \fIinput\fR, as +offset relative to the beginning of the input. Character offsets are +counted from \fB0\fR. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBCharacter Processing\fR, +\fBLocation Handling\fR, and \fBNonterminal Execution\fR. +.TP +\fILocation Stack\fR (LS) +A stack of locations in the \fIinput\fR, saved for possible +backtracking. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBCharacter Processing\fR, +\fBLocation Handling\fR, and \fBNonterminal Execution\fR. +.TP +\fIStatus\fR (ST) +The status of the last attempt of testing the \fIinput\fR, indicating +either success or failure. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBStatus Control\fR, +\fBCharacter Processing\fR, and \fBNonterminal Execution\fR. +.TP +\fISemantic Value\fR (SV) +The current semantic value, either empty, or a node for AST +constructed from the input. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBValue Construction\fR, and +\fBAST Construction\fR. +.TP +\fIAST Reduction Stack\fR (ARS) +The stack of partial ASTs constructed during the processing of +nonterminal symbols. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBValue Construction\fR, and +\fBAST Construction\fR. +.TP +\fIAST Stack\fR (AS) +The stack of reduction stacks, saved for possible backtracking. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBValue Construction\fR, and +\fBAST Construction\fR. +.TP +\fIError Status\fR (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. +.sp +\fINote\fR that this part of the machine's state can be set even if +the last test of the \fIcurrent character\fR 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. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBError Handling\fR, +\fBCharacter Processing\fR, and \fBNonterminal Execution\fR. +.TP +\fIError Stack\fR (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. +.sp +This part of the machine's state is used and modified by the +instructions defined in the sections \fBError Handling\fR, +\fBCharacter Processing\fR, and \fBNonterminal Execution\fR. +.TP +\fINonterminal Cache\fR (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. +.sp +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. +.sp +This part of the machine's state is used and modified by the +instructions defined in the section \fBNonterminal Execution\fR. +.TP +\fITerminal Cache\fR (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. +.sp +This part of the machine's state is used and modified by the +instructions defined in the section \fBInput Handling\fR. +.PP +.SH "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. +.SS "INPUT HANDLING" +The instructions in this section mainly access IN, pulling the +characters to process into the machine. +.TP +\fBinput_next\fR \fImsg\fR +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. +.sp +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. +.sp +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 +\fImsg\fR becomes the new ES. +.PP +.SS "CHARACTER PROCESSING" +The instructions in this section mainly access CC, testing it against +character classes, ranges, and individual characters. +.TP +\fBtest_alnum\fR +This instruction implements the special PE operator "alnum", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_alpha\fR +This instruction implements the special PE operator "alpha", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_ascii\fR +This instruction implements the special PE operator "ascii", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_char\fR \fIchar\fR +This instruction implements the character matching operator, i.e. it +checks if CC is \fIchar\fR. +.sp +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. +.TP +\fBtest_ddigit\fR +This instruction implements the special PE operator "ddigit", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_digit\fR +This instruction implements the special PE operator "digit", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_graph\fR +This instruction implements the special PE operator "graph", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_lower\fR +This instruction implements the special PE operator "lower", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_print\fR +This instruction implements the special PE operator "print", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_punct\fR +This instruction implements the special PE operator "punct", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_range\fR \fIchars\fR \fIchare\fR +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 \fIchars\fR to \fIchare\fR, both inclusive. +.sp +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. +.TP +\fBtest_space\fR +This instruction implements the special PE operator "space", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_upper\fR +This instruction implements the special PE operator "upper", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_wordchar\fR +This instruction implements the special PE operator "wordchar", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.TP +\fBtest_xdigit\fR +This instruction implements the special PE operator "xdigit", which +checks if CC falls into the character class of the same name, or not. +.sp +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. +.PP +.SS "ERROR HANDLING" +The instructions in this section mainly access ER and ES. +.TP +\fBerror_clear\fR +This instruction clears ER. +.TP +\fBerror_push\fR +This instruction makes a copy of ER and pushes it on ES. +.TP +\fBerror_pop_merge\fR +This instruction takes the topmost entry of ES and merges the error +status it contains with ES, making the result the new ES. +.sp +The merge is governed by four rules, with the merge result +.RS +.IP [1] +Empty if both states are empty. +.IP [2] +The non-empty state if only one of the two states is non-empty. +.IP [3] +The state with the larger location, if the two states specify +different locations. +.IP [4] +The pair of the location shared by the two states, and the set-union +of their messages for states at the same location. +.RE +.TP +\fBerror_nonterminal\fR \fIsymbol\fR +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 +\fIsymbol\fR as the new ES. +.sp +\fINote\fR: In the above "just past" means "that location plus one", +or also "the location of the next character after that location". +.PP +.SS "STATUS CONTROL" +The instructions in this section directly manipulate ST. +.TP +\fBstatus_ok\fR +This instruction sets ST to \fBtrue\fR, recording a success. +.TP +\fBstatus_fail\fR +This instruction sets ST to \fBfalse\fR, recording a failure. +.TP +\fBstatus_negate\fR +This instruction negates ST, turning a failure into a success and vice +versa. +.PP +.SS "LOCATION HANDLING" +The instructions in this section access CL and LS. +.TP +\fBloc_push\fR +This instruction makes a copy of CL and pushes it on LS. +.TP +\fBloc_pop_discard\fR +This instructions pops the last saved location from LS. +.TP +\fBloc_pop_rewind\fR +This instruction pops the last saved location from LS and restores it +as CL. +.PP +.SS "NONTERMINAL EXECUTION" +The instructions in this section access and manipulate NC. +.TP +\fBsymbol_restore\fR \fIsymbol\fR +This instruction checks if NC contains data for the nonterminal +\fIsymbol\fR at CL, or not. The result of the instruction is a boolean +flag, with \fBTrue\fR 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. +.sp +The method with which the instruction's result is transformed into +control flow is left undefined and the responsibility of the +implementation. +.TP +\fBsymbol_save\fR \fIsymbol\fR +This instructions saves the current settings of CL, ST, ER, and SV in +NC, using the pair of nonterminal \fIsymbol\fR and the last location +saved in LS as key. +.PP +.SS "VALUE CONSTRUCTION" +The instructions in this section manipulate SV. +.TP +\fBvalue_clear\fR +This instruction clears SV. +.TP +\fBvalue_leaf\fR \fIsymbol\fR +This instruction constructs an AST node for \fIsymbol\fR covering the +range of IN from one character after the last location saved on LS to +CL and stores it in SV. ... +.TP +\fBvalue_reduce\fR \fIsymbol\fR +This instruction generally behaves like \fBvalue_nonterminal_leaf\fR, +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. +.PP +.SS "AST CONSTRUCTION" +The instructions in this section manipulate ARS and AS. +.TP +\fBast_value_push\fR +This instruction makes a copy of SV and pushes it on ARS. +.TP +\fBast_push\fR +This instruction pushes the current state of ARS on AS and then clears +ARS. +.TP +\fBast_pop_rewind\fR +This instruction pops the last entry saved on AS and restores it as +the new state of ARS. +.TP +\fBast_pop_discard\fR +This instruction pops the last entry saved on AS. +.PP +.SS "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. +.PP +The implementation of this machine in Parser Tools, i.e the package +\fBpt::rde\fR, is not only coded in Tcl, but also relies on Tcl +commands to provide it with control flow (instructions). +.SH "INTERACTION OF THE INSTRUCTIONS WITH THE ARCHITECTURAL STATE" +.CS + + +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 +======================= ======================= ==================== + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_parser_api.n Index: embedded/man/files/modules/pt/pt_parser_api.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_parser_api.n @@ -0,0 +1,687 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_parser_api.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt_parser_api" i 1 tcllib "Parser Tools" +.BS +.SH NAME +pt_parser_api \- Parser API +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +\fBclassName\fR ?\fIobjectName\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBparse\fR \fIchan\fR +.sp +\fIobjectName\fR \fBparset\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This document describes the API shared by the grammar interpreter +provided by the package \fBpt::peg::interp\fR and the parsers +generated by the \fBpt\fR application for the result formats +\fBcritcl\fR, \fBsnit\fR, and \fBoo\fR regarding access +to the actual parsing functionality. +.PP +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. +.PP +It resides in the User Layer of Parser Tools. +.PP +IMAGE: arch_user_pkg +.PP +.SH "CLASS API" +.TP +\fBclassName\fR ?\fIobjectName\fR? +The class command constructs parser instances, i.e. objects. The +result of the command is the fully-qualified name of the instance +command. +.sp +If no \fIobjectName\fR is specified the class will generate and use an +automatic name. If the \fIobjectName\fR was specified, but is not +fully qualified the command will be created in the curent namespace. +.PP +.SH "INSTANCE API" +All parser instances provide at least the methods shown below: +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command. +.sp +The result of the command is the empty string. +.TP +\fIobjectName\fR \fBparse\fR \fIchan\fR +This method runs the parser using the contents of \fIchan\fR 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. +.sp +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 \fIreflected channels\fR available. +.sp +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 \fBcoroutine::auto\fR to wrap it +into a coroutine where \fBread\fR is properly changed for +push-operation. +.sp +Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +\fBAST serialization format\fR. +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 \fBpt::ast\fR 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. +.sp +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: +.RS +.IP [1] +The string \fBpt::rde\fR identifying it as parser runtime error. +.IP [2] +The location of the parse error, as character offset from the +beginning of the parsed input. +.IP [3] +The location of parse error, now as a 2-element list containing +line-number and column in the line. +.IP [4] +A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. +For the specification of atomic parsing expressions please see the +section \fBPE serialization format\fR. +.RE +.TP +\fIobjectName\fR \fBparset\fR \fItext\fR +This method runs the parser using the string in \fItext\fR as input. +In all other ways it behaves like the method \fBparse\fR, shown +above. +.PP +.SH USAGE +A generated parser is used like this +.CS + + + 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 ... + +.CE +When using a grammar interpreter for parsing some differences creep in +.CS + + + 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 ... + +.CE +.SH "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. +.PP +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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.IP [1] +The serialization of any AST is the serialization of its root node. +.IP [2] +The serialization of any node is a Tcl list containing at least three +elements. +.RS +.IP [1] +The first element is the name of the nonterminal symbol stored in the +node. +.IP [2] +The second and third element are the locations of the first and last +token in the token stream the node represents (covers). +.RS +.IP [1] +Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero). +.IP [2] +The end location has to be equal to or larger than the start location. +.RE +.IP [3] +All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression grammar below +.PP +.CS + + +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; + +.CE +.PP +and the input string +.CS + + 120+5 +.CE +then a parser should deliver the abstract syntax tree below (except for whitespace) +.PP +.CS + + +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} + } + } + } +} + +.CE +.PP +Or, more graphical +.PP +.PS +.nf + +- Digit 0 0 | 1 + | | + +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 + | | | + | +- Digit 2 2 | 0 + | | +Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + + | | + +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 +.fi +.PE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_container.n Index: embedded/man/files/modules/pt/pt_peg_container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_container.n @@ -0,0 +1,920 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::container" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::container \- PEG Storage +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsnit \fR +.sp +package require \fBpt::peg::container ?1?\fR +.sp +\fB::pt::peg\fR \fIobjectName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBclear\fR +.sp +\fIobjectName\fR \fBimporter\fR +.sp +\fIobjectName\fR \fBimporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fBexporter\fR +.sp +\fIobjectName\fR \fBexporter\fR \fIobject\fR +.sp +\fIobjectName\fR \fB=\fR \fIsource\fR +.sp +\fIobjectName\fR \fB-->\fR \fIdestination\fR +.sp +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBstart\fR +.sp +\fIobjectName\fR \fBstart\fR \fIpe\fR +.sp +\fIobjectName\fR \fBnonterminals\fR +.sp +\fIobjectName\fR \fBmodes\fR +.sp +\fIobjectName\fR \fBmodes\fR \fIdict\fR +.sp +\fIobjectName\fR \fBrules\fR +.sp +\fIobjectName\fR \fBrules\fR \fIdict\fR +.sp +\fIobjectName\fR \fBadd\fR ?\fInt\fR...? +.sp +\fIobjectName\fR \fBremove\fR ?\fInt\fR...? +.sp +\fIobjectName\fR \fBexists\fR \fInt\fR +.sp +\fIobjectName\fR \fBrename\fR \fIntold\fR \fIntnew\fR +.sp +\fIobjectName\fR \fBmode\fR \fInt\fR +.sp +\fIobjectName\fR \fBmode\fR \fInt\fR \fImode\fR +.sp +\fIobjectName\fR \fBrule\fR \fInt\fR +.sp +\fIobjectName\fR \fBrule\fR \fInt\fR \fIpe\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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. +.PP +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. +.PP +IMAGE: arch_core_container +.PP +The other two pillars are, as shown above +.IP [1] +\fIPEG Import\fR, and +.IP [2] +\fIPEG Export\fR +.PP +.PP +Packages related to this are: +.TP +\fBpt::rde\fR +This package provides an implementation of PARAM, a virtual machine +for the parsing of a channel, geared towards the needs of handling +PEGs. +.TP +\fBpt::peg::interp\fR +This package implements an interpreter for PEGs on top of the virtual +machine provided by \fBpt::peg::rde\fR +.PP +.SS "CLASS API" +The package exports the API described here. +.TP +\fB::pt::peg\fR \fIobjectName\fR ?\fB=\fR|\fB:=\fR|\fB<--\fR|\fBas\fR|\fBdeserialize\fR \fIsrc\fR? +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 +\fBObject API\fR. It may be used to invoke various operations on +the object. +.sp +The new container will be empty if no \fIsrc\fR is specified. Otherwise +it will contain a copy of the grammar contained in the \fIsrc\fR. +All operators except \fBdeserialize\fR interpret \fIsrc\fR as a +container object command. The \fBdeserialize\fR operator interprets +\fIsrc\fR as the serialization of a parsing expression grammar +instead, as specified in section \fBPEG serialization format\fR. +.sp +An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is \fIvalid\fR, but not +\fIuseful\fR. +.PP +.SS "OBJECT API" +.PP +All objects created by this package provide the following methods for +the manipulation and querying of their contents: +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object, releasing all claimed memory, and +deleting the associated object command. +.TP +\fIobjectName\fR \fBclear\fR +This method resets the object to contain the empty grammar. It does +\fInot\fR destroy the object itself. +.TP +\fIobjectName\fR \fBimporter\fR +This method returns the import manager object currently attached to +the container, if any. +.TP +\fIobjectName\fR \fBimporter\fR \fIobject\fR +This method attaches the \fIobject\fR as import manager to the +container, and returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBimport text\fR 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. +.TP +\fIobjectName\fR \fBexporter\fR +This method returns the export manager object currently attached to +the container, if any. +.TP +\fIobjectName\fR \fBexporter\fR \fIobject\fR +This method attaches the \fIobject\fR as export manager to the +container, and returns it as the result of the command. +Note that the \fIobject\fR is \fInot\fR put into ownership of the +container. I.e., destruction of the container will \fInot\fR destroy +the \fIobject\fR. +.sp +It is expected that \fIobject\fR provides a method named +\fBexport object\fR 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 \fIobject\fR will +use the container's method \fBserialize\fR to obtain the +serialization of the table of contents from which to generate the text. +.TP +\fIobjectName\fR \fB=\fR \fIsource\fR +This method assigns the contents of the PEG object \fIsource\fR to +ourselves, overwriting the existing definition. This is the assignment +operator for grammars. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIobjectName\fR \fBdeserialize =\fR [\fIsource\fR \fBserialize\fR] + +.CE +.TP +\fIobjectName\fR \fB-->\fR \fIdestination\fR +This method assigns our contents to the PEG object \fIdestination\fR, +overwriting the existing definition. This is the reverse assignment +operator for grammars. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdestination\fR \fBdeserialize =\fR [\fIobjectName\fR \fBserialize\fR] + +.CE +.TP +\fIobjectName\fR \fBserialize\fR ?\fIformat\fR? +This method returns our grammar in some textual form usable for +transfer, persistent storage, etc. If no \fIformat\fR is not specified +the returned result is the canonical serialization of the grammar, as +specified in the section \fBPEG serialization format\fR. +.sp +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. +.TP +\fIobjectName\fR \fBdeserialize =\fR \fIdata\fR ?\fIformat\fR? +This is the complementary method to \fBserialize\fR. +It replaces the current definition with the grammar contained in the +\fIdata\fR. If no \fIformat\fR was specified it is assumed to be the +regular serialization of a grammar, as specified in the section +\fBPEG serialization format\fR +.sp +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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBdeserialize +=\fR \fIdata\fR ?\fIformat\fR? +This method behaves like \fBdeserialize =\fR in its essentials, +except that it merges the grammar in the \fIdata\fR 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. +.sp +The result of the method is the empty string. +.TP +\fIobjectName\fR \fBstart\fR +This method returns the current start expression of the grammar. +.TP +\fIobjectName\fR \fBstart\fR \fIpe\fR +This method defines the \fIstart expression\fR of the grammar. It +replaces the current start expression with the parsing expression +\fIpe\fR, and returns the new start expression. +.sp +The method will fail with an error and leave the grammar unchanged if +\fIpe\fR does not contain a valid parsing expression as specified in +the section \fBPE serialization format\fR. +.TP +\fIobjectName\fR \fBnonterminals\fR +This method returns the set of all nonterminal symbols known to the +grammar. +.TP +\fIobjectName\fR \fBmodes\fR +This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their semantic modes. +.TP +\fIobjectName\fR \fBmodes\fR \fIdict\fR +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. +.sp +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 \fImode\fRs +is not one of the legal values. +.TP +\fIobjectName\fR \fBrules\fR +This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their parsing expressions (right-hand +sides). +.TP +\fIobjectName\fR \fBrules\fR \fIdict\fR +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. +.sp +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 \fBPE serialization format\fR. +.TP +\fIobjectName\fR \fBadd\fR ?\fInt\fR...? +This method adds the nonterminal symbols \fInt\fR, etc. to the +grammar, and defines default semantic mode and expression for it +(\fBvalue\fR and \fBepsilon\fR respectively). +The method returns the empty string as its result. +.sp +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). +.sp +The method does nothing if no symbol was specified as argument. +.TP +\fIobjectName\fR \fBremove\fR ?\fInt\fR...? +This method removes the named nonterminal symbols \fInt\fR, etc. from +the set of nonterminal symbols known to our grammar. +The method returns the empty string as its result. +.sp +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. +.TP +\fIobjectName\fR \fBexists\fR \fInt\fR +This method tests whether the nonterminal symbol \fInt\fR is known +to our grammar or not. +The result is a boolean value. It will be set to \fBtrue\fR if +\fInt\fR is known, and \fBfalse\fR otherwise. +.sp +The method will fail with an error if \fInt\fR is the empty string, +i.e. an invalid nonterminal symbol. +.TP +\fIobjectName\fR \fBrename\fR \fIntold\fR \fIntnew\fR +This method renames the nonterminal symbol \fIntold\fR to \fIntnew\fR. +The method returns the empty string as its result. +.sp +The method will fail with an error and leave the grammar unchanged if +either \fIntold\fR is not known to the grammar, or \fIntnew\fR is +already known, or any of them is the empty string, i.e. an invalid +nonterminal symbol. +.TP +\fIobjectName\fR \fBmode\fR \fInt\fR +This method returns the current semantic mode for the nonterminal +symbol \fInt\fR. +.sp +The method will fail with an error if \fInt\fR is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol. +.TP +\fIobjectName\fR \fBmode\fR \fInt\fR \fImode\fR +This mode sets the semantic mode for the nonterminal symbol \fInt\fR, +and returns the new mode. +The method will fail with an error if \fInt\fR is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +the chosen \fImode\fR is not one of the legal values. +.sp +The following modes are legal: +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.TP +\fIobjectName\fR \fBrule\fR \fInt\fR +This method returns the current parsing expression (right-hand side) +for the nonterminal symbol \fInt\fR. +.sp +The method will fail with an error if \fInt\fR is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol. +.TP +\fIobjectName\fR \fBrule\fR \fInt\fR \fIpe\fR +This method set the parsing expression (right-hand side) of the +nonterminal \fInt\fR to \fIpe\fR, and returns the new parsing +expression. +.sp +The method will fail with an error if \fInt\fR is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +\fIpe\fR does not contain a valid parsing expression as specified in +the section \fBPE serialization format\fR. +.PP +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_container_peg.n Index: embedded/man/files/modules/pt/pt_peg_container_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_container_peg.n @@ -0,0 +1,285 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_container_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::container::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::container::peg \- PEG Storage. Canned PEG grammar specification +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsnit \fR +.sp +package require \fBpt::peg::container::peg ?1?\fR +.sp +package require \fBpt::peg::container \fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package provides a sub-type of \fBpt::peg::container\fR which +is preloaded with a parsing expression grammar describing a textual +format for parsing expression grammars. +.PP +The sub-type provides the exact same API as +\fBpt::peg::container\fR. Instead of duplicating its contents the +reader is asked to read the referenced document. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_export.n Index: embedded/man/files/modules/pt/pt_peg_export.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_export.n @@ -0,0 +1,741 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_export.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::export" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::export \- PEG Export +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsnit \fR +.sp +package require \fBconfiguration \fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBpluginmgr \fR +.sp +package require \fBpt::peg::export ?1?\fR +.sp +\fB::pt::peg::export\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBconfiguration names\fR +.sp +\fIobjectName\fR \fBconfiguration get\fR +.sp +\fIobjectName\fR \fBconfiguration set\fR \fIname\fR ?\fIvalue\fR? +.sp +\fIobjectName\fR \fBconfiguration unset\fR \fIpattern\fR... +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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 \fInroff\fR, +\fIHTML\fR, etc. +.PP +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. +.PP +IMAGE: arch_core_export +.PP +The other two pillars are, as shown above +.IP [1] +\fIPEG Import\fR, and +.IP [2] +\fIPEG Storage\fR +.PP +.PP +For information about the data structure which is the major input to +the manager objects provided by this package see the section +\fBPEG serialization format\fR. +.PP +The plugin system of this class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBGRAMMAR_PEG_EXPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBGRAMMAR_PEG_PLUGINS\fR, +.IP [3] +the environment variable \fBGRAMMAR_PLUGINS\fR, +.IP [4] +the path "\fI~/.grammar/peg/export/plugin\fR" +.IP [5] +the path "\fI~/.grammar/peg/plugin\fR" +.IP [6] +the path "\fI~/.grammar/plugin\fR" +.IP [7] +the path "\fI~/.grammar/peg/export/plugins\fR" +.IP [8] +the path "\fI~/.grammar/peg/plugins\fR" +.IP [9] +the path "\fI~/.grammar/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PEG\\EXPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PEG\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using the Windows(tm) operating system. +.PP +The whole system is delivered with three predefined export plugins, +namely +.TP +container +See \fIPEG Export Plugin. To CONTAINER format\fR for details. +.TP +json +See \fIPEG Export Plugin. To JSON format\fR for details. +.TP +peg +See \fIPEG Export Plugin. To PEG format\fR for details. +.PP +.PP +For readers wishing to write their own export plugin for some format, +i.e. \fIplugin writer\fRs, reading and understanding the +\fIParser Tools Export API\fR specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::pt::peg::export\fR \fIobjectName\fR +This command creates a new export manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::pt::peg::export\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBexport serial\fR \fIserial\fR ?\fIformat\fR? +This method takes the canonical serialization of a parsing expression +grammar stored in \fIserial\fR and converts it to the specified +\fIformat\fR, 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. +.sp +If no format is specified the method defaults to \fBtext\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBPEG serialization format\fR. +.sp +The plugin has to conform to the interface documented in the +\fIParser Tools Export API\fR specification. +.TP +\fIobjectName\fR \fBexport object\fR \fIobject\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBexport serial\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBserialize\fR method returning the canonical serialization of a +parsing expression grammar. It invokes that method, feeds the result +into \fBexport serial\fR and returns the resulting string as its +own result. +.TP +\fIobjectName\fR \fBconfiguration names\fR +This method returns a list containing the names of all configuration +options currently known to the object. +.TP +\fIobjectName\fR \fBconfiguration get\fR +This method returns a dictionary containing the names and values of +all configuration options currently known to the object. +.TP +\fIobjectName\fR \fBconfiguration set\fR \fIname\fR ?\fIvalue\fR? +This method sets the configuration option \fIname\fR to the +specified \fIvalue\fR and returns the new value of the option. +.sp +If no value is specified it simply returns the current value, without +changing it. +.sp +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. +.TP +\fIobjectName\fR \fBconfiguration unset\fR \fIpattern\fR... +This method unsets all configuration options matching the specified +glob \fIpattern\fRs. If no pattern is specified it will unset all +currently defined configuration options. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_export_container.n Index: embedded/man/files/modules/pt/pt_peg_export_container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_export_container.n @@ -0,0 +1,741 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_export_container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::export::container" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::export::container \- PEG Export Plugin. Write CONTAINER format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::export::container ?1?\fR +.sp +package require \fBpt::peg::to::container \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the parsing expression grammar export plugin +for the generation of CONTAINER markup. +.PP +It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by \fBpt::peg::export\fR, the export +manager, sitting between it and the corresponding core conversion +functionality provided by \fBpt::peg::to::container\fR. +.PP +IMAGE: arch_core_eplugins +.PP +.PP +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: +.IP [1] +In an untrusted environment the proper access is through the package +\fBpt::peg::export\fR and the export manager objects it +provides. +.IP [2] +In a trusted environment however simply use the package +\fBpt::peg::to::container\fR and access the core +conversion functionality directly. +.PP +.SH API +The API provided by this package satisfies the specification of the +Plugin API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates CONTAINER markup encoding the grammar. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The CONTAINER export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +enum \fImode\fR +The value of this configuration variable controls which methods of +\fBpt::peg\fR instances the plugin will use to specify the +grammar. There are two legal values +.RS +.TP +\fBbulk\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmodes\fR, +and \fBrules\fR 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. +.sp +This mode is the default. +.TP +\fBincremental\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmode\fR, +and \fBrule\fR are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands. +.RE +.TP +string \fItemplate\fR +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: +.RS +.TP +\fB@user@\fR +To be replaced with the value of the configuration variable \fBuser\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBCONTAINER\fR. +.TP +\fB@file@\fR +To be replaced with the value of the configuration variable \fBfile\fR. +.TP +\fB@name@\fR +To be replaced with the value of the configuration variable \fBname\fR. +.TP +\fB@mode@\fR +To be replaced with the value of the configuration variable \fBmode\fR. +.TP +\fB@code@\fR +To be replaced with the generated code. +.RE +.sp +If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "\fB@code@\fR". +.PP +\fINote\fR that this plugin may ignore the standard configuration +variables \fBuser\fR, \fBformat\fR, \fBfile\fR, and their values, +depending on the chosen template. +.PP +The content of the standard configuration variable \fBname\fR, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name \fBa_pe_grammar\fR. +.SH "GRAMMAR CONTAINER" +The \fBcontainer\fR 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 \fBpt::peg::interp\fR, a grammar +interpreter. +.PP +The format represents grammars by a \fBsnit::type\fR, i.e. class, +whose instances are API-compatible to the instances of the +\fBpt::peg::container\fR package, and which are preloaded with the +grammar in question. +.PP +It has no direct formal specification beyond what was said above. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +one possible CONTAINER serialization for it is +.PP +.CS + + +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 +} + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +CONTAINER, EBNF, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_export_json.n Index: embedded/man/files/modules/pt/pt_peg_export_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_export_json.n @@ -0,0 +1,800 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_export_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::export::json" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::export::json \- PEG Export Plugin. Write JSON format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::export::json ?1?\fR +.sp +package require \fBpt::peg::to::json \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the parsing expression grammar export plugin +for the generation of JSON markup. +.PP +It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by \fBpt::peg::export\fR, the export +manager, sitting between it and the corresponding core conversion +functionality provided by \fBpt::peg::to::json\fR. +.PP +IMAGE: arch_core_eplugins +.PP +.PP +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: +.IP [1] +In an untrusted environment the proper access is through the package +\fBpt::peg::export\fR and the export manager objects it +provides. +.IP [2] +In a trusted environment however simply use the package +\fBpt::peg::to::json\fR and access the core +conversion functionality directly. +.PP +.SH API +The API provided by this package satisfies the specification of the +Plugin API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates JSON markup encoding the grammar. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +boolean \fIindented\fR +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. +.sp +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. +.TP +boolean \fIaligned\fR +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 \fBindented\fR +is set. +.sp +If this flag is not set (the default), the output is formatted as per +the value of \fBindented\fR, without trying to align the values for +dictionary keys. +.PP +\fINote\fR that this plugin ignores the standard configuration +variables \fBuser\fR, \fBformat\fR, \fBfile\fR, and \fBname\fR, and +their values. +.SH "JSON GRAMMAR EXCHANGE FORMAT" +The \fBjson\fR 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. +.PP +It is formally specified by the rules below: +.IP [1] +The JSON of any PEG is a JSON object. +.IP [2] +This object holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section \fBPE serialization format\fR. +.TP +\fBmode\fR +The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +\fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.PP +.PP +As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +\fBPEG serialization format\fR, 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. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +a JSON serialization for it is +.PP +.CS + + +{ + "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" + } +} + +.CE +.PP +and a Tcl serialization of the same is +.PP +.CS + + +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} +} + +.CE +.PP +The similarity of the latter to the JSON should be quite obvious. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, JSON, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_export_peg.n Index: embedded/man/files/modules/pt/pt_peg_export_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_export_peg.n @@ -0,0 +1,793 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_export_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::export::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::export::peg \- PEG Export Plugin. Write PEG format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::export::peg ?1?\fR +.sp +package require \fBpt::peg::to::peg \fR +.sp +\fBexport\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the parsing expression grammar export plugin +for the generation of PEG markup. +.PP +It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by \fBpt::peg::export\fR, the export +manager, sitting between it and the corresponding core conversion +functionality provided by \fBpt::peg::to::peg\fR. +.PP +IMAGE: arch_core_eplugins +.PP +.PP +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: +.IP [1] +In an untrusted environment the proper access is through the package +\fBpt::peg::export\fR and the export manager objects it +provides. +.IP [2] +In a trusted environment however simply use the package +\fBpt::peg::to::peg\fR and access the core +conversion functionality directly. +.PP +.SH API +The API provided by this package satisfies the specification of the +Plugin API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBexport\fR \fIserial\fR \fIconfiguration\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, the \fIconfiguration\fR, a dictionary, +and generates PEG markup encoding the grammar. +The created string is then returned as the result of the command. +.PP +.SH CONFIGURATION +The PEG export plugin recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +string \fItemplate\fR +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: +.RS +.TP +\fB@user@\fR +To be replaced with the value of the configuration variable \fBuser\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBPEG\fR. +.TP +\fB@file@\fR +To be replaced with the value of the configuration variable \fBfile\fR. +.TP +\fB@name@\fR +To be replaced with the value of the configuration variable \fBname\fR. +.TP +\fB@code@\fR +To be replaced with the generated text. +.RE +.sp +If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "\fB@code@\fR". +.PP +\fINote\fR that this plugin may ignore the standard configuration +variables \fBuser\fR, \fBformat\fR, \fBfile\fR, and their values, +depending on the chosen template. +.PP +The content of the standard configuration variable \fBname\fR, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name \fBa_pe_grammar\fR. +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the \fIPEG Language Tutorial\fR. +.PP +.CS + + +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 SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; +leaf: Ident <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + +leaf: CharSpecial <- "\\\\" [nrt'"\\[\\]\\\\] ; +leaf: CharOctalFull <- "\\\\" [0-2][0-7][0-7] ; +leaf: CharOctalPart <- "\\\\" [0-7][0-7]? ; +leaf: CharUnicode <- "\\\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; +leaf: CharUnescaped <- !"\\\\" . ; + +void: HexDigit <- [0-9a-fA-F] ; + +void: TO <- '-' ; +void: OPENB <- "[" ; +void: CLOSEB <- "]" ; +void: APOSTROPH <- "'" ; +void: DAPOSTROPH <- '"' ; +void: PEG <- "PEG" 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: END <- "END" WHITESPACE ; +void: SEMICOLON <- ";" WHITESPACE ; +void: COLON <- ":" WHITESPACE ; +void: SLASH <- "/" WHITESPACE ; +leaf: AND <- "&" WHITESPACE ; +leaf: NOT <- "!" WHITESPACE ; +leaf: QUESTION <- "?" WHITESPACE ; +leaf: STAR <- "*" WHITESPACE ; +leaf: PLUS <- "+" WHITESPACE ; +void: OPEN <- "(" WHITESPACE ; +void: CLOSE <- ")" WHITESPACE ; +leaf: DOT <- "." WHITESPACE ; + +leaf: ALNUM <- "<alnum>" WHITESPACE ; +leaf: ALPHA <- "<alpha>" WHITESPACE ; +leaf: ASCII <- "<ascii>" WHITESPACE ; +leaf: CONTROL <- "<control>" WHITESPACE ; +leaf: DDIGIT <- "<ddigit>" WHITESPACE ; +leaf: DIGIT <- "<digit>" WHITESPACE ; +leaf: GRAPH <- "<graph>" WHITESPACE ; +leaf: LOWER <- "<lower>" WHITESPACE ; +leaf: PRINTABLE <- "<print>" WHITESPACE ; +leaf: PUNCT <- "<punct>" WHITESPACE ; +leaf: SPACE <- "<space>" WHITESPACE ; +leaf: UPPER <- "<upper>" WHITESPACE ; +leaf: WORDCHAR <- "<wordchar>" WHITESPACE ; +leaf: XDIGIT <- "<xdigit>" WHITESPACE ; + +void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; +void: COMMENT <- '#' (!EOL .)* EOL ; +void: EOL <- "\\n\\r" / "\\n" / "\\r" ; +void: EOF <- !. ; + + # -------------------------------------------------------------------- +END; + +.CE +.SS EXAMPLE +Our example specifies the grammar for a basic 4-operation calculator. +.PP +.CS + + +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; + +.CE +.PP +Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as +.PP +.CS + + +PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? <ddigit>+ ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; +END; + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_from_container.n Index: embedded/man/files/modules/pt/pt_peg_from_container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_from_container.n @@ -0,0 +1,279 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_from_container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::from::container" n 0 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::from::container \- PEG Conversion. From CONTAINER format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_from_json.n Index: embedded/man/files/modules/pt/pt_peg_from_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_from_json.n @@ -0,0 +1,766 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_from_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::from::json" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::from::json \- PEG Conversion. Read JSON format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::from::json ?1?\fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBjson \fR +.sp +\fBpt::peg::from::json\fR \fBconvert\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from JSON markup to +parsing expression grammars. +.PP +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 +\fBpt::peg::import\fR. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +\fBpt::peg::import::json\fR sitting between converter +and import manager. +.PP +IMAGE: arch_core_iplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Import API\fR +specification. +.TP +\fBpt::peg::from::json\fR \fBconvert\fR \fItext\fR +This command takes the JSON markup encoding a parsing +expression grammar and contained in \fItext\fR, and generates the +canonical serialization of said grammar, as specified in section +\fBPEG serialization format\fR. +The created value is then returned as the result of the command. +.PP +.SH "JSON GRAMMAR EXCHANGE FORMAT" +The \fBjson\fR 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. +.PP +It is formally specified by the rules below: +.IP [1] +The JSON of any PEG is a JSON object. +.IP [2] +This object holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section \fBPE serialization format\fR. +.TP +\fBmode\fR +The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +\fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.PP +.PP +As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +\fBPEG serialization format\fR, 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. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +a JSON serialization for it is +.PP +.CS + + +{ + "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" + } +} + +.CE +.PP +and a Tcl serialization of the same is +.PP +.CS + + +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} +} + +.CE +.PP +The similarity of the latter to the JSON should be quite obvious. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, JSON, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_from_peg.n Index: embedded/man/files/modules/pt/pt_peg_from_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_from_peg.n @@ -0,0 +1,743 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_from_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::from::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::from::peg \- PEG Conversion. Read PEG format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::from::peg ?1?\fR +.sp +\fBpt::peg::from::peg\fR \fBconvert\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from PEG markup to +parsing expression grammars. +.PP +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 +\fBpt::peg::import\fR. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +\fBpt::peg::import::peg\fR sitting between converter +and import manager. +.PP +IMAGE: arch_core_iplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Import API\fR +specification. +.TP +\fBpt::peg::from::peg\fR \fBconvert\fR \fItext\fR +This command takes the PEG markup encoding a parsing +expression grammar and contained in \fItext\fR, and generates the +canonical serialization of said grammar, as specified in section +\fBPEG serialization format\fR. +The created value is then returned as the result of the command. +.PP +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the \fIPEG Language Tutorial\fR. +.PP +.CS + + +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 SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; +leaf: Ident <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + +leaf: CharSpecial <- "\\\\" [nrt'"\\[\\]\\\\] ; +leaf: CharOctalFull <- "\\\\" [0-2][0-7][0-7] ; +leaf: CharOctalPart <- "\\\\" [0-7][0-7]? ; +leaf: CharUnicode <- "\\\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; +leaf: CharUnescaped <- !"\\\\" . ; + +void: HexDigit <- [0-9a-fA-F] ; + +void: TO <- '-' ; +void: OPENB <- "[" ; +void: CLOSEB <- "]" ; +void: APOSTROPH <- "'" ; +void: DAPOSTROPH <- '"' ; +void: PEG <- "PEG" 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: END <- "END" WHITESPACE ; +void: SEMICOLON <- ";" WHITESPACE ; +void: COLON <- ":" WHITESPACE ; +void: SLASH <- "/" WHITESPACE ; +leaf: AND <- "&" WHITESPACE ; +leaf: NOT <- "!" WHITESPACE ; +leaf: QUESTION <- "?" WHITESPACE ; +leaf: STAR <- "*" WHITESPACE ; +leaf: PLUS <- "+" WHITESPACE ; +void: OPEN <- "(" WHITESPACE ; +void: CLOSE <- ")" WHITESPACE ; +leaf: DOT <- "." WHITESPACE ; + +leaf: ALNUM <- "<alnum>" WHITESPACE ; +leaf: ALPHA <- "<alpha>" WHITESPACE ; +leaf: ASCII <- "<ascii>" WHITESPACE ; +leaf: CONTROL <- "<control>" WHITESPACE ; +leaf: DDIGIT <- "<ddigit>" WHITESPACE ; +leaf: DIGIT <- "<digit>" WHITESPACE ; +leaf: GRAPH <- "<graph>" WHITESPACE ; +leaf: LOWER <- "<lower>" WHITESPACE ; +leaf: PRINTABLE <- "<print>" WHITESPACE ; +leaf: PUNCT <- "<punct>" WHITESPACE ; +leaf: SPACE <- "<space>" WHITESPACE ; +leaf: UPPER <- "<upper>" WHITESPACE ; +leaf: WORDCHAR <- "<wordchar>" WHITESPACE ; +leaf: XDIGIT <- "<xdigit>" WHITESPACE ; + +void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; +void: COMMENT <- '#' (!EOL .)* EOL ; +void: EOL <- "\\n\\r" / "\\n" / "\\r" ; +void: EOF <- !. ; + + # -------------------------------------------------------------------- +END; + +.CE +.SS EXAMPLE +Our example specifies the grammar for a basic 4-operation calculator. +.PP +.CS + + +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; + +.CE +.PP +Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as +.PP +.CS + + +PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? <ddigit>+ ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; +END; + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_import.n Index: embedded/man/files/modules/pt/pt_peg_import.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_import.n @@ -0,0 +1,761 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_import.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::import" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::import \- PEG Import +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsnit \fR +.sp +package require \fBconfiguration \fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBpluginmgr \fR +.sp +package require \fBpt::peg::import ?1?\fR +.sp +\fB::pt::peg::import\fR \fIobjectName\fR +.sp +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +.sp +\fIobjectName\fR \fBincludes\fR +.sp +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +.sp +\fIobjectName\fR \fBinclude clear\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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 \fIpeg\fR, +\fIcontainer\fR, \fIjson\fR, etc. +.PP +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. +.PP +IMAGE: arch_core_import +.PP +The other two pillars are, as shown above +.IP [1] +\fIPEG Export\fR, and +.IP [2] +\fIPEG Storage\fR +.PP +.PP +For information about the data structure which is the major output of +the manager objects provided by this package see the section +\fBPEG serialization format\fR. +.PP +The plugin system of our class is based on the package +\fBpluginmgr\fR, and configured to look for plugins using +.IP [1] +the environment variable \fBGRAMMAR_PEG_IMPORT_PLUGINS\fR, +.IP [2] +the environment variable \fBGRAMMAR_PEG_PLUGINS\fR, +.IP [3] +the environment variable \fBGRAMMAR_PLUGINS\fR, +.IP [4] +the path "\fI~/.grammar/peg/import/plugin\fR" +.IP [5] +the path "\fI~/.grammar/peg/plugin\fR" +.IP [6] +the path "\fI~/.grammar/plugin\fR" +.IP [7] +the path "\fI~/.grammar/peg/import/plugins\fR" +.IP [8] +the path "\fI~/.grammar/peg/plugins\fR" +.IP [9] +the path "\fI~/.grammar/plugins\fR" +.IP [10] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PEG\\IMPORT\\PLUGINS" +.IP [11] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PEG\\PLUGINS" +.IP [12] +the registry entry "HKEY_CURRENT_USER\\SOFTWARE\\GRAMMAR\\PLUGINS" +.PP +The last three are used only when the package is run on a machine +using the Windows(tm) operating system. +.PP +The whole system is delivered with three predefined import plugins, +namely +.TP +container +See \fIPEG Import Plugin. From CONTAINER format\fR for details. +.TP +json +See \fIPEG Import Plugin. From JSON format\fR for details. +.TP +peg +See \fIPEG Import Plugin. From PEG format\fR for details. +.PP +.PP +For readers wishing to write their own import plugin for some format, +i.e. \fIplugin writer\fRs, reading and understanding the +\fIParser Tools Impport API\fR specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fB::pt::peg::import\fR \fIobjectName\fR +This command creates a new import manager object with an associated +Tcl command whose name is \fIobjectName\fR. This \fIobject\fR command +is explained in full detail in the sections \fBObject command\fR +and \fBObject methods\fR. The object command will be created +under the current namespace if the \fIobjectName\fR is not fully +qualified, and in the specified namespace otherwise. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::pt::peg::import\fR command have +the following general form: +.TP +\fBobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object it is invoked for. +.TP +\fIobjectName\fR \fBimport text\fR \fItext\fR ?\fIformat\fR? +This method takes the \fItext\fR and converts it from the specified +\fIformat\fR 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. +.sp +If no format is specified the method defaults to \fBtext\fR. +.sp +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBPEG serialization format\fR. +.sp +The plugin has to conform to the interface documented in the +\fIParser Tools Import API\fR specification. +.TP +\fIobjectName\fR \fBimport file\fR \fIpath\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into \fBimport text\fR and returns the resulting +serialization as its own result. +.TP +\fIobjectName\fR \fBimport object text\fR \fIobject\fR \fItext\fR ?\fIformat\fR? +This method is a convenient wrapper around the \fBimport text\fR +method described by the previous item. +It expects that \fIobject\fR is an object command supporting a +\fBdeserialize\fR method expecting the canonical serialization of a +parsing expression grammar. +It imports the text using \fBimport text\fR and then feeds the +resulting serialization into the \fIobject\fR via \fBdeserialize\fR. +This method returns the empty string as it result. +.TP +\fIobjectName\fR \fBimport object file\fR \fIobject\fR \fIpath\fR ?\fIformat\fR? +This method behaves like \fBimport object text\fR, except that it +reads the text to convert from the specified file instead of being +given it as argument. +.TP +\fIobjectName\fR \fBincludes\fR +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. +.TP +\fIobjectName\fR \fBinclude add\fR \fIpath\fR +This methods adds the specified \fIpath\fR 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. +.sp +The method does nothing if the path is already known. +.TP +\fIobjectName\fR \fBinclude remove\fR \fIpath\fR +This methods removes the specified \fIpath\fR from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string. +.sp +The method does nothing if the path is not known. +.TP +\fIobjectName\fR \fBinclude clear\fR +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. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_import_container.n Index: embedded/man/files/modules/pt/pt_peg_import_container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_import_container.n @@ -0,0 +1,279 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_import_container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::import::container" n 0 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::import::container \- PEG Import Plugin. From CONTAINER format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_import_json.n Index: embedded/man/files/modules/pt/pt_peg_import_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_import_json.n @@ -0,0 +1,775 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_import_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::import::json" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::import::json \- PEG Import Plugin. Read JSON format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::import::json ?1?\fR +.sp +package require \fBpt::peg::to::json \fR +.sp +\fBimport\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the parsing expression grammar import plugin +processing JSON markup. +.PP +It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by \fBpt::peg::import\fR, the import +manager, sitting between it and the corresponding core conversion +functionality provided by \fBpt::peg::from::json\fR. +.PP +IMAGE: arch_core_iplugins +.PP +.PP +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: +.IP [1] +In an untrusted environment the proper access is through the package +\fBpt::peg::import\fR and the import manager objects it +provides. +.IP [2] +In a trusted environment however simply use the package +\fBpt::peg::from::json\fR and access the core +conversion functionality directly. +.PP +.SH API +The API provided by this package satisfies the specification of the +Plugin API found in the \fIParser Tools Import API\fR +specification. +.TP +\fBimport\fR \fItext\fR +This command takes the JSON markup encoding a parsing +expression grammar and contained in \fItext\fR, and generates the +canonical serialization of said grammar, as specified in section +\fBPEG serialization format\fR. +The created value is then returned as the result of the command. +.PP +.SH "JSON GRAMMAR EXCHANGE FORMAT" +The \fBjson\fR 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. +.PP +It is formally specified by the rules below: +.IP [1] +The JSON of any PEG is a JSON object. +.IP [2] +This object holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section \fBPE serialization format\fR. +.TP +\fBmode\fR +The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +\fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.PP +.PP +As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +\fBPEG serialization format\fR, 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. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +a JSON serialization for it is +.PP +.CS + + +{ + "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" + } +} + +.CE +.PP +and a Tcl serialization of the same is +.PP +.CS + + +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} +} + +.CE +.PP +The similarity of the latter to the JSON should be quite obvious. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, JSON, LL(k), PEG, TDPL, context-free languages, expression, grammar, import, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_import_peg.n Index: embedded/man/files/modules/pt/pt_peg_import_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_import_peg.n @@ -0,0 +1,756 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_import_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::import::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::import::peg \- PEG Import Plugin. Read PEG format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::import::peg ?1?\fR +.sp +package require \fBpt::peg::to::peg \fR +.sp +\fBimport\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the parsing expression grammar import plugin +processing PEG markup. +.PP +It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by \fBpt::peg::import\fR, the import +manager, sitting between it and the corresponding core conversion +functionality provided by \fBpt::peg::from::peg\fR. +.PP +IMAGE: arch_core_iplugins +.PP +.PP +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: +.IP [1] +In an untrusted environment the proper access is through the package +\fBpt::peg::import\fR and the import manager objects it +provides. +.IP [2] +In a trusted environment however simply use the package +\fBpt::peg::from::peg\fR and access the core +conversion functionality directly. +.PP +.SH API +The API provided by this package satisfies the specification of the +Plugin API found in the \fIParser Tools Import API\fR +specification. +.TP +\fBimport\fR \fItext\fR +This command takes the PEG markup encoding a parsing +expression grammar and contained in \fItext\fR, and generates the +canonical serialization of said grammar, as specified in section +\fBPEG serialization format\fR. +The created value is then returned as the result of the command. +.PP +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the \fIPEG Language Tutorial\fR. +.PP +.CS + + +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 SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; +leaf: Ident <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + +leaf: CharSpecial <- "\\\\" [nrt'"\\[\\]\\\\] ; +leaf: CharOctalFull <- "\\\\" [0-2][0-7][0-7] ; +leaf: CharOctalPart <- "\\\\" [0-7][0-7]? ; +leaf: CharUnicode <- "\\\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; +leaf: CharUnescaped <- !"\\\\" . ; + +void: HexDigit <- [0-9a-fA-F] ; + +void: TO <- '-' ; +void: OPENB <- "[" ; +void: CLOSEB <- "]" ; +void: APOSTROPH <- "'" ; +void: DAPOSTROPH <- '"' ; +void: PEG <- "PEG" 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: END <- "END" WHITESPACE ; +void: SEMICOLON <- ";" WHITESPACE ; +void: COLON <- ":" WHITESPACE ; +void: SLASH <- "/" WHITESPACE ; +leaf: AND <- "&" WHITESPACE ; +leaf: NOT <- "!" WHITESPACE ; +leaf: QUESTION <- "?" WHITESPACE ; +leaf: STAR <- "*" WHITESPACE ; +leaf: PLUS <- "+" WHITESPACE ; +void: OPEN <- "(" WHITESPACE ; +void: CLOSE <- ")" WHITESPACE ; +leaf: DOT <- "." WHITESPACE ; + +leaf: ALNUM <- "<alnum>" WHITESPACE ; +leaf: ALPHA <- "<alpha>" WHITESPACE ; +leaf: ASCII <- "<ascii>" WHITESPACE ; +leaf: CONTROL <- "<control>" WHITESPACE ; +leaf: DDIGIT <- "<ddigit>" WHITESPACE ; +leaf: DIGIT <- "<digit>" WHITESPACE ; +leaf: GRAPH <- "<graph>" WHITESPACE ; +leaf: LOWER <- "<lower>" WHITESPACE ; +leaf: PRINTABLE <- "<print>" WHITESPACE ; +leaf: PUNCT <- "<punct>" WHITESPACE ; +leaf: SPACE <- "<space>" WHITESPACE ; +leaf: UPPER <- "<upper>" WHITESPACE ; +leaf: WORDCHAR <- "<wordchar>" WHITESPACE ; +leaf: XDIGIT <- "<xdigit>" WHITESPACE ; + +void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; +void: COMMENT <- '#' (!EOL .)* EOL ; +void: EOL <- "\\n\\r" / "\\n" / "\\r" ; +void: EOF <- !. ; + + # -------------------------------------------------------------------- +END; + +.CE +.SS EXAMPLE +Our example specifies the grammar for a basic 4-operation calculator. +.PP +.CS + + +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; + +.CE +.PP +Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as +.PP +.CS + + +PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? <ddigit>+ ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; +END; + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, import, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_interp.n Index: embedded/man/files/modules/pt/pt_peg_interp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_interp.n @@ -0,0 +1,679 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_interp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::interp" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::interp \- Interpreter for parsing expression grammars +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::interp ?1?\fR +.sp +package require \fBpt::rde ?1?\fR +.sp +package require \fBsnit \fR +.sp +\fB::pt::peg::interpreter\fR \fIobjectName\fR \fIgrammar\fR +.sp +\fIobjectName\fR \fBuse\fR \fIgrammar\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBparse\fR \fIchan\fR +.sp +\fIobjectName\fR \fBparset\fR \fItext\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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 \fBpt::rde\fR, basing everything on the +PARAM. +.PP +Like the supporting runtime this package resides in the Execution +section of the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_transform +.PP +.PP +The interpreted grammar is copied from an instance of \fBpt::peg::container\fR, or anything providing the same API, like the +container classes created by \fBpt::peg::to::container\fR or the +associated export plugin \fBpt::peg::export::container\fR. +.SS "CLASS API" +The package exports the API described here. +.TP +\fB::pt::peg::interpreter\fR \fIobjectName\fR \fIgrammar\fR +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 \fBObject API\fR. It +may be used to invoke various operations on the object. +.sp +This new parser is configured for the execution of an empty PEG. To +configure the object for any other PEG use the method \fBuse\fR of +the \fBObject API\fR. +.PP +.SS "OBJECT API" +All objects created by this package provide the following methods. +.TP +\fIobjectName\fR \fBuse\fR \fIgrammar\fR +This method configures the grammar interpreter / parser for the +execution of the PEG stored in \fIgrammar\fR, an object which is +API-compatible to instances of \fBpt::peg::container\fR. The +parser copies the relevant information of the grammar, and does +\fInot\fR take ownership of the object. +.sp +The information of any previously used grammar is overwritten. +.sp +The result of the method the empty string. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command. +.sp +The result of the command is the empty string. +.TP +\fIobjectName\fR \fBparse\fR \fIchan\fR +This method runs the parser using the contents of \fIchan\fR 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. +.sp +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 \fIreflected channels\fR available. +.sp +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 \fBcoroutine::auto\fR to wrap it +into a coroutine where \fBread\fR is properly changed for +push-operation. +.sp +Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +\fBAST serialization format\fR. +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 \fBpt::ast\fR 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. +.sp +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: +.RS +.IP [1] +The string \fBpt::rde\fR identifying it as parser runtime error. +.IP [2] +The location of the parse error, as character offset from the +beginning of the parsed input. +.IP [3] +The location of parse error, now as a 2-element list containing +line-number and column in the line. +.IP [4] +A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. +For the specification of atomic parsing expressions please see the +section \fBPE serialization format\fR. +.RE +.TP +\fIobjectName\fR \fBparset\fR \fItext\fR +This method runs the parser using the string in \fItext\fR as input. +In all other ways it behaves like the method \fBparse\fR, shown +above. +.PP +.SH "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. +.PP +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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.IP [1] +The serialization of any AST is the serialization of its root node. +.IP [2] +The serialization of any node is a Tcl list containing at least three +elements. +.RS +.IP [1] +The first element is the name of the nonterminal symbol stored in the +node. +.IP [2] +The second and third element are the locations of the first and last +token in the token stream the node represents (covers). +.RS +.IP [1] +Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero). +.IP [2] +The end location has to be equal to or larger than the start location. +.RE +.IP [3] +All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression grammar below +.PP +.CS + + +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; + +.CE +.PP +and the input string +.CS + + 120+5 +.CE +then a parser should deliver the abstract syntax tree below (except for whitespace) +.PP +.CS + + +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} + } + } + } +} + +.CE +.PP +Or, more graphical +.PP +.PS +.nf + +- Digit 0 0 | 1 + | | + +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 + | | | + | +- Digit 2 2 | 0 + | | +Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + + | | + +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 +.fi +.PE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_introduction.n Index: embedded/man/files/modules/pt/pt_peg_introduction.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_introduction.n @@ -0,0 +1,409 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_introduction.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::pegrammar" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::pegrammar \- Introduction to Parsing Expression Grammars +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +Welcome to the introduction to \fIParsing Expression Grammar\fRs +(short: \fIPEG\fR), the formalism used by the Parser Tools. +It is assumed that the reader has a basic knowledge of parsing theory, +i.e. \fIContext-Free Grammars\fR (short: \fICFG\fR), +\fIlanguages\fR, and associated terms like \fILL(k)\fR, +\fILR(k)\fR, \fIterminal\fR and \fInonterminal\fR \fIsymbols\fR, +etc. +We do not intend to recapitulate such basic definitions or terms like +\fIuseful\fR, \fIreachable\fR, (left/right) \fIrecursive\fR, +\fInullable\fR, first/last/follow sets, etc. +Please see the \fBReferences\fR at the end instead if you are in +need of places and books which provide such background information. +.PP +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 \fIchoice\fR +operators. Where CFGs use an \fIunordered choice\fR to represent +alternatives PEGs use \fIprioritized choice\fR. 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. +.PP +On the CFG side this gives rise to LL(k) and LR(k) for making the +choice \fIdeterministic\fR with a bounded \fIlookahead\fR of k +terminal symbols, where LL is in essence \fItopdown\fR aka +\fIrecursive descent\fR parsing, and LR \fIbottomup\fR aka +\fIshift reduce\fR parsing. +.PP +On the PEG side we can parse input with recursive descent and +\fIbacktracking\fR 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. +.PP +This is the basic concept behind \fIpackrat parsers\fR. +.PP +A limitation pure PEGs share with LL(k) CFGs is that +\fIleft-recursive\fR 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 \fIkleene closure\fR and +\fIpositive kleene closure\fR. +This is what the Parser Tools are doing. +.PP +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 \fBstring is\fR. +.PP +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. +.SH "FORMAL DEFINITION" +.PP +For the mathematically inclined, a Parsing Expression Grammar is a +4-tuple (VN,VT,R,eS) where +.IP \(bu +VN is a set of \fInonterminal symbols\fR, +.IP \(bu +VT is a set of \fIterminal symbols\fR, +.IP \(bu +R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and \fIe\fR a \fIparsing expression\fR. +.IP \(bu +eS is a parsing expression, the \fIstart expression\fR. +.PP +.PP +Further constraints are +.IP \(bu +The intersection of VN and VT is empty. +.IP \(bu +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. +.PP +.PP +Parsing expressions are inductively defined via +.IP \(bu +The empty string (epsilon) is a parsing expression. +.IP \(bu +A terminal symbol \fIa\fR is a parsing expression. +.IP \(bu +A nonterminal symbol \fIA\fR is a parsing expression. +.IP \(bu +\fIe1\fR\fIe2\fR is a parsing expression for parsing expressions +\fIe1\fR and \fI2\fR. This is called \fIsequence\fR. +.IP \(bu +\fIe1\fR/\fIe2\fR is a parsing expression for parsing expressions +\fIe1\fR and \fI2\fR. This is called \fIordered choice\fR. +.IP \(bu +\fIe\fR* is a parsing expression for parsing expression +\fIe\fR. This is called \fIzero-or-more repetitions\fR, also known +as \fIkleene closure\fR. +.IP \(bu +\fIe\fR+ is a parsing expression for parsing expression +\fIe\fR. This is called \fIone-or-more repetitions\fR, also known +as \fIpositive kleene closure\fR. +.IP \(bu +!\fIe\fR is a parsing expression for parsing expression +\fIe1\fR. This is called a \fInot lookahead predicate\fR. +.IP \(bu +&\fIe\fR is a parsing expression for parsing expression +\fIe1\fR. This is called an \fIand lookahead predicate\fR. +.PP +.PP +.PP +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). +.PP +They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars. +.SH REFERENCES +.IP [1] +\fIThe Packrat Parsing and Parsing Expression Grammars Page\fR [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. +.IP [2] +\fIhttp://en.wikipedia.org/wiki/Parsing_expression_grammar\fR +Wikipedia's entry about Parsing Expression Grammars. +.IP [3] +\fIParsing Techniques - A Practical Guide \fR [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. +.IP [4] +\fICompilers and Compiler Generators\fR [http://scifac.ru.ac.za/compilers/], an online book using +CoCo/R, a generator for recursive descent parsers. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_language.n Index: embedded/man/files/modules/pt/pt_peg_language.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_language.n @@ -0,0 +1,724 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_language.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg_language" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg_language \- PEG Language Tutorial +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +Welcome to the tutorial / introduction for the +\fBPEG Specification Language\fR. +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. +.SH "WHAT IS IT?" +\fBpeg\fR, 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. +.SH "THE ELEMENTS OF THE LANGUAGE" +.SS "BASIC STRUCTURE" +The general outline of a textual PEG is +.CS + + +PEG <<name>> (<<start-expression>>) + <<rules>> +END; + +.CE +\fINote\fR: We are using text in double angle-brackets as +place-holders for things not yet explained. +.SS NAMES +Names are mostly used to identify the nonterminal symbols of the +grammar, i.e. that which occurs on the left-hand side of a <rule>. +The exception to that is the name given after the keyword \fBPEG\fR +(see previous section), which is the name of the whole grammar itself. +.PP +The structure of a name is simple: +.IP [1] +It begins with a letter, underscore, or colon, followed by +.IP [2] +zero or more letters, digits, underscores, or colons. +.PP +Or, in formal textual notation: +.CS + + + ([_:] / <alpha>) ([_:] / <alnum>)* + +.CE +Examples of names: +.CS + + + Hello + ::world + _:submarine55_ + +.CE +Examples of text which are \fInot\fR names: +.CS + + + 12 + .bogus + 0wrong + @location + +.CE +.SS 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 +.CS + + + <<name>> <- <<expression>> ; + +.CE +The <name> specifies the nonterminal symbol to be defined, the +<expression> after the arrow (<-) then declares its structure. +.PP +Note that each rule ends in a single semicolon, even the last. +I.e. the semicolon is a rule \fIterminator\fR, not a separator. +.PP +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. +.SS EXPRESSIONS +The \fIparsing\fR expressions are the meat of any specification. They +declare the structure of the whole document (<<start-expression>>), +and of all nonterminal symbols. +.PP +All expressions are made up out of \fIatomic expressions\fR and +\fIoperators\fR 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 \fIconcatenation\fR) of parts however. This is specified by +simply placing the parts adjacent to each other. +.PP +Here are the operators, from highest to lowest priority (i.e. strength +of binding): +.CS + + + # Binary operators. + + <<expression-1>> <<expression-2>> # sequence. parse 1, then 2. + <<expression-1>> / <<expression-2>> # alternative. try to parse 1, and parse 2 if 1 failed to parse. + + # Prefix operators. Lookahead constraints. Same priority. + + & <<expression>> # Parse expression, ok on successful parse. + ! <<expression>> # Ditto, except ok on failure to parse. + + # Suffix operators. Repetition. Same priority. + + <<expression>> ? # Parse expression none, or once (repeat 0 or 1). + <<expression>> * # Parse expression zero or more times. + <<expression>> + # Parse expression one or more times. + + # Expression nesting + + ( <<expression>> ) # Put an expression in parens to change its priority. + +.CE +With this we can now deconstruct the formal expression for names given +in section \fBNames\fR: +.CS + + + ([_:] / <alpha>) ([_:] / <alnum>)* + +.CE +It is a sequence of two parts, +.CS + + [_:] / <alpha> +.CE +and +.CS + + ([_:] / <alnum>)* +.CE +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 +.CS + + + [_:] + <alpha> + <alnum> + +.CE +And \fIatomic expressions\fR are our next topic. They +fall into three classes: +.IP [1] +names, i.e. nonterminal symbols, +.IP [2] +string literals, and +.IP [3] +character classes. +.PP +Names we know about already, or see section \fBNames\fR for a +refresher. +.PP +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 +.CS + + + '' + "" + 'hello' + "umbra" + "'" + '"' + +.CE +The last two examples show how to place any of the delimiters into a +string. +.PP +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: +.CS + + + <alnum> # Any unicode alphabet or digit character (string is alnum). + <alpha> # Any unicode alphabet character (string is alpha). + <ascii> # Any unicode character below codepoint 0x80 (string is ascii). + <control> # Any unicode control character (string is control). + <ddigit> # The digit characters [0-9]. + <digit> # Any unicode digit character (string is digit). + <graph> # Any unicode printing character, except space (string is graph). + <lower> # Any unicode lower-case alphabet character (string is lower). + <print> # Any unicode printing character, incl. space (string is print). + <punct> # Any unicode punctuation character (string is punct). + <space> # Any unicode space character (string is space). + <upper> # Any unicode upper-case alphabet character (string is upper). + <wordchar> # Any unicode word character (string is wordchar). + <xdigit> # The hexadecimal digit characters [0-9a-fA-F]. + . # Any character, except end of input. + +.CE +And the syntax of custom-defined character classes is +.CS + + + [ <<range>>* ] + +.CE +where each range is either a single character, or of the form +.CS + + + <<character>> - <character>> + +.CE +Examples for character classes we have seen already in the course of +this introduction are +.CS + + + [_:] + [0-9] + [0-9a-fA-F] + +.CE +We are nearly done with expressions. The only piece left is to tell +how the characters in character classes and string literals are +specified. +.PP +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. +.PP +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: +.CS + + + \\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 + +.CE +.SS "WHITESPACE AND COMMENTS" +One issue not touched upon so far is whitespace and comments. +.PP +Whitespace is any unicode space character, i.e. anything in the +character class <space>, and comments. The latter are sequences of +characters starting with a '#' (hash, unicode codepoint 0x23) and +ending at the next end-of-line. +.PP +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. +.SS "NONTERMINAL ATTRIBUTES" +Lastly, a more advanced topic. In the section \fBRules\fR we gave +the structure of a rule as +.CS + + + <<name>> <- <<expression>> ; + +.CE +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 +.CS + + + <<mode>> : <<name>> <- <<expression>> ; + +.CE +is also allowed. This mode is optional. The known modes and their +meanings are: +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.PP +Of these three modes only \fBleaf\fR and \fBvoid\fR can be +specified directly. \fBvalue\fR is implicitly specified by the +absence of a mode before the nonterminal. +.PP +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. +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the \fIPEG Language Tutorial\fR. +.PP +.CS + + +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 SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; +leaf: Ident <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + +leaf: CharSpecial <- "\\\\" [nrt'"\\[\\]\\\\] ; +leaf: CharOctalFull <- "\\\\" [0-2][0-7][0-7] ; +leaf: CharOctalPart <- "\\\\" [0-7][0-7]? ; +leaf: CharUnicode <- "\\\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; +leaf: CharUnescaped <- !"\\\\" . ; + +void: HexDigit <- [0-9a-fA-F] ; + +void: TO <- '-' ; +void: OPENB <- "[" ; +void: CLOSEB <- "]" ; +void: APOSTROPH <- "'" ; +void: DAPOSTROPH <- '"' ; +void: PEG <- "PEG" 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: END <- "END" WHITESPACE ; +void: SEMICOLON <- ";" WHITESPACE ; +void: COLON <- ":" WHITESPACE ; +void: SLASH <- "/" WHITESPACE ; +leaf: AND <- "&" WHITESPACE ; +leaf: NOT <- "!" WHITESPACE ; +leaf: QUESTION <- "?" WHITESPACE ; +leaf: STAR <- "*" WHITESPACE ; +leaf: PLUS <- "+" WHITESPACE ; +void: OPEN <- "(" WHITESPACE ; +void: CLOSE <- ")" WHITESPACE ; +leaf: DOT <- "." WHITESPACE ; + +leaf: ALNUM <- "<alnum>" WHITESPACE ; +leaf: ALPHA <- "<alpha>" WHITESPACE ; +leaf: ASCII <- "<ascii>" WHITESPACE ; +leaf: CONTROL <- "<control>" WHITESPACE ; +leaf: DDIGIT <- "<ddigit>" WHITESPACE ; +leaf: DIGIT <- "<digit>" WHITESPACE ; +leaf: GRAPH <- "<graph>" WHITESPACE ; +leaf: LOWER <- "<lower>" WHITESPACE ; +leaf: PRINTABLE <- "<print>" WHITESPACE ; +leaf: PUNCT <- "<punct>" WHITESPACE ; +leaf: SPACE <- "<space>" WHITESPACE ; +leaf: UPPER <- "<upper>" WHITESPACE ; +leaf: WORDCHAR <- "<wordchar>" WHITESPACE ; +leaf: XDIGIT <- "<xdigit>" WHITESPACE ; + +void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; +void: COMMENT <- '#' (!EOL .)* EOL ; +void: EOL <- "\\n\\r" / "\\n" / "\\r" ; +void: EOF <- !. ; + + # -------------------------------------------------------------------- +END; + +.CE +.SS EXAMPLE +Our example specifies the grammar for a basic 4-operation calculator. +.PP +.CS + + +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; + +.CE +.PP +Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as +.PP +.CS + + +PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? <ddigit>+ ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; +END; + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_container.n Index: embedded/man/files/modules/pt/pt_peg_to_container.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_container.n @@ -0,0 +1,764 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_container.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::container" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::container \- PEG Conversion. Write CONTAINER format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::container ?1?\fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBtext::write \fR +.sp +package require \fBchar \fR +.sp +\fBpt::peg::to::container\fR \fBreset\fR +.sp +\fBpt::peg::to::container\fR \fBconfigure\fR +.sp +\fBpt::peg::to::container\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::container\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::container\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to CONTAINER markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::container\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::container\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::container\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::container\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::container\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::container\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates CONTAINER markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to the CONTAINER format recognizes the following options +and changes its behaviour as they specify. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-mode\fR \fBbulk\fR|\fBincremental\fR +The value of this option controls which methods of +\fBpt::peg::container\fR 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 \fBbulk\fR. +.RS +.TP +\fBbulk\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmodes\fR, +and \fBrules\fR 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. +.sp +This mode is the default. +.TP +\fBincremental\fR +In this mode the methods \fBstart\fR, \fBadd\fR, \fBmode\fR, +and \fBrule\fR are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands. +.RE +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBCONTAINER\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@mode@\fR +To be replaced with the value of the option \fB-mode\fR. +.TP +\fB@code@\fR +To be replaced with the generated code. +.RE +.PP +.SH "GRAMMAR CONTAINER" +The \fBcontainer\fR 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 \fBpt::peg::interp\fR, a grammar +interpreter. +.PP +The format represents grammars by a \fBsnit::type\fR, i.e. class, +whose instances are API-compatible to the instances of the +\fBpt::peg::container\fR package, and which are preloaded with the +grammar in question. +.PP +It has no direct formal specification beyond what was said above. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +one possible CONTAINER serialization for it is +.PP +.CS + + +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 +} + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +CONTAINER, EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_cparam.n Index: embedded/man/files/modules/pt/pt_peg_to_cparam.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_cparam.n @@ -0,0 +1,784 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_cparam.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::cparam" n 1.0.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::cparam \- PEG Conversion. Write CPARAM format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::cparam ?1.0.1?\fR +.sp +\fBpt::peg::to::cparam\fR \fBreset\fR +.sp +\fBpt::peg::to::cparam\fR \fBconfigure\fR +.sp +\fBpt::peg::to::cparam\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::cparam\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::cparam\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to CPARAM markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::cparam\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::cparam\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::cparam\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::cparam\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::cparam\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::cparam\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates CPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to C code recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBC/PARAM\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated Tcl code. +.RE +.IP +The following options are special, in that they will +occur within the generated code, and are replaced there as well. +.RS +.TP +\fB@statedecl@\fR +To be replaced with the value of the option \fBstate-decl\fR. +.TP +\fB@stateref@\fR +To be replaced with the value of the option \fBstate-ref\fR. +.TP +\fB@strings@\fR +To be replaced with the value of the option \fBstring-varname\fR. +.TP +\fB@self@\fR +To be replaced with the value of the option \fBself-command\fR. +.TP +\fB@def@\fR +To be replaced with the value of the option \fBfun-qualifier\fR. +.TP +\fB@ns@\fR +To be replaced with the value of the option \fBnamespace\fR. +.TP +\fB@main@\fR +To be replaced with the value of the option \fBmain\fR. +.TP +\fB@prelude@\fR +To be replaced with the value of the option \fBprelude\fR. +.RE +.TP +\fB-state-decl\fR 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 \fBRDE_PARAM p\fR. +.TP +\fB-state-ref\fR 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 \fBp\fR. +.TP +\fB-self-command\fR 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. +.TP +\fB-fun-qualifier\fR string +A C string containing the attributes to give to the generated +functions (methods ...), per the chosen framework (template). +The default value is \fBstatic\fR. +.TP +\fB-namespace\fR 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. +.TP +\fB-main\fR string +The name of the main function (method, ...) to be called by the chosen +framework (template) to start parsing input. +The default value is \fB__main\fR. +.TP +\fB-string-varname\fR 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 \fBp_string\fR. +.TP +\fB-prelude\fR string +A snippet of code to be inserted at the head of each generated parsing +function. +The default value is the empty string. +.TP +\fB-indent\fR integer +The number of characters to indent each line of the generated code by. +The default value is \fB0\fR. +.PP +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. +.PP +To help these latter users an adjunct package is provided, containing +a canned configuration which will generate immediately useful full +parsers. It is +.TP +\fBpt::cparam::configuration::critcl\fR +Generated parsers are embedded into a \fBCritcl\fR-based framework. +.PP +.SH "C/PARAM CODE REPRESENTATION OF PARSING EXPRESSION GRAMMARS" +The \fBc\fR 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. +.PP +The \fBcritcl\fR format, for example, is implemented as a canned +configuration of these options on top of the generator for \fBc\fR. +.PP +The bulk of such a framework has to be specified through the option +\fB-template\fR. The additional options +.TP +\fB-fun-qualifier\fR string +.TP +\fB-indent\fR integer +.TP +\fB-main\fR string +.TP +\fB-namespace\fR string +.TP +\fB-prelude\fR string +.TP +\fB-self-command\fR string +.TP +\fB-state-decl\fR string +.TP +\fB-state-ref\fR string +.TP +\fB-string-varname\fR string +.PP +provide code snippets which help to glue framework and generated code +together. Their placeholders are in the \fIgenerated\fR code. +.SS EXAMPLE +We are forgoing an example of this representation, with apologies. +It would be way to large for this document. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +CPARAM, EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_json.n Index: embedded/man/files/modules/pt/pt_peg_to_json.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_json.n @@ -0,0 +1,828 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_json.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::json" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::json \- PEG Conversion. Write JSON format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::json ?1?\fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBjson::write \fR +.sp +\fBpt::peg::to::json\fR \fBreset\fR +.sp +\fBpt::peg::to::json\fR \fBconfigure\fR +.sp +\fBpt::peg::to::json\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::json\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::json\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to JSON markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::json\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::json\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::json\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::json\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::json\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::json\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates JSON markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to the JSON grammar exchange format recognizes the +following configuration variables and changes its behaviour as they +specify. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-indented\fR 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. +.sp +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. +.TP +\fB-aligned\fR 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 \fB-indented\fR is set. +.sp +If the option is not set (the default), the output is formatted as per +the value of \fBindented\fR, without trying to align the values for +dictionary keys. +.PP +.SH "JSON GRAMMAR EXCHANGE FORMAT" +The \fBjson\fR 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. +.PP +It is formally specified by the rules below: +.IP [1] +The JSON of any PEG is a JSON object. +.IP [2] +This object holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section \fBPE serialization format\fR. +.TP +\fBmode\fR +The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +\fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.PP +.PP +As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +\fBPEG serialization format\fR, 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. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +a JSON serialization for it is +.PP +.CS + + +{ + "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" + } +} + +.CE +.PP +and a Tcl serialization of the same is +.PP +.CS + + +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} +} + +.CE +.PP +The similarity of the latter to the JSON should be quite obvious. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, JSON, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_param.n Index: embedded/man/files/modules/pt/pt_peg_to_param.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_param.n @@ -0,0 +1,1462 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_param.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::param" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::param \- PEG Conversion. Write PARAM format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::param ?1?\fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBpt::pe \fR +.sp +\fBpt::peg::to::param\fR \fBreset\fR +.sp +\fBpt::peg::to::param\fR \fBconfigure\fR +.sp +\fBpt::peg::to::param\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::param\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::param\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to PARAM markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::param\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::param\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::param\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::param\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::param\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::param\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates PARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to PARAM markup recognizes the following configuration +variables and changes its behaviour as they specify. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the configuration variable \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBPARAM\fR. +.TP +\fB@file@\fR +To be replaced with the value of the configuration variable \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the configuration variable \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated text. +.RE +.TP +\fB-name\fR string +The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this configuration variable is the name of the user for +which the conversion is run. The default value is \fBunknown\fR. +.TP +\fB-file\fR 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 \fBunknown\fR. +.PP +.SH "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 \fIPackRat Machine Specification\fR, plus a +few more for control flow (jump ok, jump fail, call symbol, return). +.PP +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. +.PP +It has no direct formal specification beyond what was said above. +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +one possible PARAM serialization for it is +.PP +.CS + + +# -*- text -*- +# Parsing Expression Grammar 'TEMPLATE'. +# Generated for unknown, from file 'TEST' + +# +# Grammar Start Expression +# + +<<MAIN>>: + call sym_Expression + halt + +# +# value Symbol 'AddOp' +# + +sym_AddOp: +# / +# '-' +# '+' + + symbol_restore AddOp + found! jump found_7 + loc_push + + call choice_5 + + fail! value_clear + ok! value_leaf AddOp + symbol_save AddOp + error_nonterminal AddOp + loc_pop_discard + +found_7: + ok! ast_value_push + return + +choice_5: +# / +# '-' +# '+' + + error_clear + + loc_push + error_push + + input_next "t -" + ok! test_char "-" + + error_pop_merge + ok! jump oknoast_4 + + loc_pop_rewind + loc_push + error_push + + input_next "t +" + ok! test_char "+" + + error_pop_merge + ok! jump oknoast_4 + + loc_pop_rewind + status_fail + return + +oknoast_4: + loc_pop_discard + return +# +# value Symbol 'Digit' +# + +sym_Digit: +# / +# '0' +# '1' +# '2' +# '3' +# '4' +# '5' +# '6' +# '7' +# '8' +# '9' + + symbol_restore Digit + found! jump found_22 + loc_push + + call choice_20 + + fail! value_clear + ok! value_leaf Digit + symbol_save Digit + error_nonterminal Digit + loc_pop_discard + +found_22: + ok! ast_value_push + return + +choice_20: +# / +# '0' +# '1' +# '2' +# '3' +# '4' +# '5' +# '6' +# '7' +# '8' +# '9' + + error_clear + + loc_push + error_push + + input_next "t 0" + ok! test_char "0" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 1" + ok! test_char "1" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 2" + ok! test_char "2" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 3" + ok! test_char "3" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 4" + ok! test_char "4" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 5" + ok! test_char "5" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 6" + ok! test_char "6" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 7" + ok! test_char "7" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 8" + ok! test_char "8" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + loc_push + error_push + + input_next "t 9" + ok! test_char "9" + + error_pop_merge + ok! jump oknoast_19 + + loc_pop_rewind + status_fail + return + +oknoast_19: + loc_pop_discard + return +# +# value Symbol 'Expression' +# + +sym_Expression: +# / +# x +# '\\(' +# (Expression) +# '\\)' +# x +# (Factor) +# * +# x +# (MulOp) +# (Factor) + + symbol_restore Expression + found! jump found_46 + loc_push + ast_push + + call choice_44 + + fail! value_clear + ok! value_reduce Expression + symbol_save Expression + error_nonterminal Expression + ast_pop_rewind + loc_pop_discard + +found_46: + ok! ast_value_push + return + +choice_44: +# / +# x +# '\\(' +# (Expression) +# '\\)' +# x +# (Factor) +# * +# x +# (MulOp) +# (Factor) + + error_clear + + ast_push + loc_push + error_push + + call sequence_27 + + error_pop_merge + ok! jump ok_43 + + ast_pop_rewind + loc_pop_rewind + ast_push + loc_push + error_push + + call sequence_40 + + error_pop_merge + ok! jump ok_43 + + ast_pop_rewind + loc_pop_rewind + status_fail + return + +ok_43: + ast_pop_discard + loc_pop_discard + return + +sequence_27: +# x +# '\\(' +# (Expression) +# '\\)' + + loc_push + error_clear + + error_push + + input_next "t (" + ok! test_char "(" + + error_pop_merge + fail! jump failednoast_29 + ast_push + error_push + + call sym_Expression + + error_pop_merge + fail! jump failed_28 + error_push + + input_next "t )" + ok! test_char ")" + + error_pop_merge + fail! jump failed_28 + + ast_pop_discard + loc_pop_discard + return + +failed_28: + ast_pop_rewind + +failednoast_29: + loc_pop_rewind + return + +sequence_40: +# x +# (Factor) +# * +# x +# (MulOp) +# (Factor) + + ast_push + loc_push + error_clear + + error_push + + call sym_Factor + + error_pop_merge + fail! jump failed_41 + error_push + + call kleene_37 + + error_pop_merge + fail! jump failed_41 + + ast_pop_discard + loc_pop_discard + return + +failed_41: + ast_pop_rewind + loc_pop_rewind + return + +kleene_37: +# * +# x +# (MulOp) +# (Factor) + + loc_push + error_push + + call sequence_34 + + error_pop_merge + fail! jump failed_38 + loc_pop_discard + jump kleene_37 + +failed_38: + loc_pop_rewind + status_ok + return + +sequence_34: +# x +# (MulOp) +# (Factor) + + ast_push + loc_push + error_clear + + error_push + + call sym_MulOp + + error_pop_merge + fail! jump failed_35 + error_push + + call sym_Factor + + error_pop_merge + fail! jump failed_35 + + ast_pop_discard + loc_pop_discard + return + +failed_35: + ast_pop_rewind + loc_pop_rewind + return +# +# value Symbol 'Factor' +# + +sym_Factor: +# x +# (Term) +# * +# x +# (AddOp) +# (Term) + + symbol_restore Factor + found! jump found_60 + loc_push + ast_push + + call sequence_57 + + fail! value_clear + ok! value_reduce Factor + symbol_save Factor + error_nonterminal Factor + ast_pop_rewind + loc_pop_discard + +found_60: + ok! ast_value_push + return + +sequence_57: +# x +# (Term) +# * +# x +# (AddOp) +# (Term) + + ast_push + loc_push + error_clear + + error_push + + call sym_Term + + error_pop_merge + fail! jump failed_58 + error_push + + call kleene_54 + + error_pop_merge + fail! jump failed_58 + + ast_pop_discard + loc_pop_discard + return + +failed_58: + ast_pop_rewind + loc_pop_rewind + return + +kleene_54: +# * +# x +# (AddOp) +# (Term) + + loc_push + error_push + + call sequence_51 + + error_pop_merge + fail! jump failed_55 + loc_pop_discard + jump kleene_54 + +failed_55: + loc_pop_rewind + status_ok + return + +sequence_51: +# x +# (AddOp) +# (Term) + + ast_push + loc_push + error_clear + + error_push + + call sym_AddOp + + error_pop_merge + fail! jump failed_52 + error_push + + call sym_Term + + error_pop_merge + fail! jump failed_52 + + ast_pop_discard + loc_pop_discard + return + +failed_52: + ast_pop_rewind + loc_pop_rewind + return +# +# value Symbol 'MulOp' +# + +sym_MulOp: +# / +# '*' +# '/' + + symbol_restore MulOp + found! jump found_67 + loc_push + + call choice_65 + + fail! value_clear + ok! value_leaf MulOp + symbol_save MulOp + error_nonterminal MulOp + loc_pop_discard + +found_67: + ok! ast_value_push + return + +choice_65: +# / +# '*' +# '/' + + error_clear + + loc_push + error_push + + input_next "t *" + ok! test_char "*" + + error_pop_merge + ok! jump oknoast_64 + + loc_pop_rewind + loc_push + error_push + + input_next "t /" + ok! test_char "/" + + error_pop_merge + ok! jump oknoast_64 + + loc_pop_rewind + status_fail + return + +oknoast_64: + loc_pop_discard + return +# +# value Symbol 'Number' +# + +sym_Number: +# x +# ? +# (Sign) +# + +# (Digit) + + symbol_restore Number + found! jump found_80 + loc_push + ast_push + + call sequence_77 + + fail! value_clear + ok! value_reduce Number + symbol_save Number + error_nonterminal Number + ast_pop_rewind + loc_pop_discard + +found_80: + ok! ast_value_push + return + +sequence_77: +# x +# ? +# (Sign) +# + +# (Digit) + + ast_push + loc_push + error_clear + + error_push + + call optional_70 + + error_pop_merge + fail! jump failed_78 + error_push + + call poskleene_73 + + error_pop_merge + fail! jump failed_78 + + ast_pop_discard + loc_pop_discard + return + +failed_78: + ast_pop_rewind + loc_pop_rewind + return + +optional_70: +# ? +# (Sign) + + loc_push + error_push + + call sym_Sign + + error_pop_merge + fail! loc_pop_rewind + ok! loc_pop_discard + status_ok + return + +poskleene_73: +# + +# (Digit) + + loc_push + + call sym_Digit + + fail! jump failed_74 + +loop_75: + loc_pop_discard + loc_push + error_push + + call sym_Digit + + error_pop_merge + ok! jump loop_75 + status_ok + +failed_74: + loc_pop_rewind + return +# +# value Symbol 'Sign' +# + +sym_Sign: +# / +# '-' +# '+' + + symbol_restore Sign + found! jump found_86 + loc_push + + call choice_5 + + fail! value_clear + ok! value_leaf Sign + symbol_save Sign + error_nonterminal Sign + loc_pop_discard + +found_86: + ok! ast_value_push + return +# +# value Symbol 'Term' +# + +sym_Term: +# (Number) + + symbol_restore Term + found! jump found_89 + loc_push + ast_push + + call sym_Number + + fail! value_clear + ok! value_reduce Term + symbol_save Term + error_nonterminal Term + ast_pop_rewind + loc_pop_discard + +found_89: + ok! ast_value_push + return + +# +# + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PARAM, PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_peg.n Index: embedded/man/files/modules/pt/pt_peg_to_peg.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_peg.n @@ -0,0 +1,815 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_peg.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::peg \- PEG Conversion. Write PEG format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::peg ?1?\fR +.sp +package require \fBpt::peg \fR +.sp +package require \fBpt::pe \fR +.sp +package require \fBtext::write \fR +.sp +\fBpt::peg::to::peg\fR \fBreset\fR +.sp +\fBpt::peg::to::peg\fR \fBconfigure\fR +.sp +\fBpt::peg::to::peg\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::peg\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::peg\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to PEG markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::peg\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::peg\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::peg\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::peg\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::peg\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::peg\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates PEG markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to the PEG language recognizes the following options and +changes its behaviour as they specify. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the option \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBPEG\fR. +.TP +\fB@file@\fR +To be replaced with the value of the option \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the option \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated text. +.RE +.PP +.SH "PEG SPECIFICATION LANGUAGE" +\fBpeg\fR, 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. +.PP +It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the \fIPEG Language Tutorial\fR. +.PP +.CS + + +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 SEMICOLON WHITESPACE ; + + # -------------------------------------------------------------------- + # Lexing constructs + + Identifier <- Ident WHITESPACE ; +leaf: Ident <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ; + Char <- CharSpecial / CharOctalFull / CharOctalPart + / CharUnicode / CharUnescaped + ; + +leaf: CharSpecial <- "\\\\" [nrt'"\\[\\]\\\\] ; +leaf: CharOctalFull <- "\\\\" [0-2][0-7][0-7] ; +leaf: CharOctalPart <- "\\\\" [0-7][0-7]? ; +leaf: CharUnicode <- "\\\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; +leaf: CharUnescaped <- !"\\\\" . ; + +void: HexDigit <- [0-9a-fA-F] ; + +void: TO <- '-' ; +void: OPENB <- "[" ; +void: CLOSEB <- "]" ; +void: APOSTROPH <- "'" ; +void: DAPOSTROPH <- '"' ; +void: PEG <- "PEG" 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: END <- "END" WHITESPACE ; +void: SEMICOLON <- ";" WHITESPACE ; +void: COLON <- ":" WHITESPACE ; +void: SLASH <- "/" WHITESPACE ; +leaf: AND <- "&" WHITESPACE ; +leaf: NOT <- "!" WHITESPACE ; +leaf: QUESTION <- "?" WHITESPACE ; +leaf: STAR <- "*" WHITESPACE ; +leaf: PLUS <- "+" WHITESPACE ; +void: OPEN <- "(" WHITESPACE ; +void: CLOSE <- ")" WHITESPACE ; +leaf: DOT <- "." WHITESPACE ; + +leaf: ALNUM <- "<alnum>" WHITESPACE ; +leaf: ALPHA <- "<alpha>" WHITESPACE ; +leaf: ASCII <- "<ascii>" WHITESPACE ; +leaf: CONTROL <- "<control>" WHITESPACE ; +leaf: DDIGIT <- "<ddigit>" WHITESPACE ; +leaf: DIGIT <- "<digit>" WHITESPACE ; +leaf: GRAPH <- "<graph>" WHITESPACE ; +leaf: LOWER <- "<lower>" WHITESPACE ; +leaf: PRINTABLE <- "<print>" WHITESPACE ; +leaf: PUNCT <- "<punct>" WHITESPACE ; +leaf: SPACE <- "<space>" WHITESPACE ; +leaf: UPPER <- "<upper>" WHITESPACE ; +leaf: WORDCHAR <- "<wordchar>" WHITESPACE ; +leaf: XDIGIT <- "<xdigit>" WHITESPACE ; + +void: WHITESPACE <- (" " / "\\t" / EOL / COMMENT)* ; +void: COMMENT <- '#' (!EOL .)* EOL ; +void: EOL <- "\\n\\r" / "\\n" / "\\r" ; +void: EOF <- !. ; + + # -------------------------------------------------------------------- +END; + +.CE +.SS EXAMPLE +Our example specifies the grammar for a basic 4-operation calculator. +.PP +.CS + + +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; + +.CE +.PP +Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as +.PP +.CS + + +PEG calculator (Expression) + Sign <- [-+] ; + Number <- Sign? <ddigit>+ ; + Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; + MulOp <- [*/] ; + Factor <- Term (AddOp Term)* ; + AddOp <- [-+] ; + Term <- Number ; +END; + +.CE +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_peg_to_tclparam.n Index: embedded/man/files/modules/pt/pt_peg_to_tclparam.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_peg_to_tclparam.n @@ -0,0 +1,768 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_peg_to_tclparam.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg::to::tclparam" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg::to::tclparam \- PEG Conversion. Write TCLPARAM format +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg::to::tclparam ?1?\fR +.sp +\fBpt::peg::to::tclparam\fR \fBreset\fR +.sp +\fBpt::peg::to::tclparam\fR \fBconfigure\fR +.sp +\fBpt::peg::to::tclparam\fR \fBconfigure\fR \fIoption\fR +.sp +\fBpt::peg::to::tclparam\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBpt::peg::to::tclparam\fR \fBconvert\fR \fIserial\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package implements the converter from parsing expression grammars +to TCLPARAM markup. +.PP +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 +\fBpt::peg::export\fR. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +\fBpt::peg::export::tclparam\fR sitting between converter +and export manager. +.PP +IMAGE: arch_core_eplugins +.PP +.SH API +The API provided by this package satisfies the specification of the +Converter API found in the \fIParser Tools Export API\fR +specification. +.TP +\fBpt::peg::to::tclparam\fR \fBreset\fR +This command resets the configuration of the package to its default +settings. +.TP +\fBpt::peg::to::tclparam\fR \fBconfigure\fR +This command returns a dictionary containing the current configuration +of the package. +.TP +\fBpt::peg::to::tclparam\fR \fBconfigure\fR \fIoption\fR +This command returns the current value of the specified configuration +\fIoption\fR of the package. For the set of legal options, please read +the section \fBOptions\fR. +.TP +\fBpt::peg::to::tclparam\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command sets the given configuration \fIoption\fRs of the +package, to the specified \fIvalue\fRs. For the set of legal options, +please read the section \fBOptions\fR. +.TP +\fBpt::peg::to::tclparam\fR \fBconvert\fR \fIserial\fR +This command takes the canonical serialization of a parsing expression +grammar, as specified in section \fBPEG serialization format\fR, +and contained in \fIserial\fR, and generates TCLPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command. +.PP +.SH OPTIONS +The converter to Tcl/PARAM markup recognizes the following +configuration variables and changes its behaviour as they specify. +.TP +\fB-template\fR 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 "\fB@code@\fR". +.RS +.TP +\fB@user@\fR +To be replaced with the value of the configuration variable \fB-user\fR. +.TP +\fB@format@\fR +To be replaced with the the constant \fBTcl/PARAM\fR. +.TP +\fB@file@\fR +To be replaced with the value of the configuration variable \fB-file\fR. +.TP +\fB@name@\fR +To be replaced with the value of the configuration variable \fB-name\fR. +.TP +\fB@code@\fR +To be replaced with the generated Tcl code. +.RE +.IP +The following configuration variables are special, in that they will +occur within the generated code, and are replaced there as well. +.RS +.TP +\fB@runtime@\fR +To be replaced with the value of the configuration variable \fBruntime-command\fR. +.TP +\fB@self@\fR +To be replaced with the value of the configuration variable \fBself-command\fR. +.TP +\fB@def@\fR +To be replaced with the value of the configuration variable \fBproc-command\fR. +.TP +\fB@ns@\fR +To be replaced with the value of the configuration variable \fBnamespace\fR. +.TP +\fB@main@\fR +To be replaced with the value of the configuration variable \fBmain\fR. +.TP +\fB@prelude@\fR +To be replaced with the value of the configuration variable \fBprelude\fR. +.RE +.TP +\fB-name\fR string +The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this configuration variable is the name of the user for +which the conversion is run. The default value is \fBunknown\fR. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-runtime-command\fR 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. +.TP +\fB-self-command\fR 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. +.TP +\fB-proc-command\fR string +The name of the Tcl command used to define procedures (methods ...), +per the chosen framework (template). +The default value is \fBproc\fR. +.TP +\fB-namespace\fR 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 \fB::\fR. +.TP +\fB-main\fR string +The name of the main procedure (method, ...) to be called by the +chosen framework (template) to start parsing input. +The default value is \fB__main\fR. +.TP +\fB-prelude\fR string +A snippet of code to be insert at the head of each generated parsing +command. +The default value is the empty string. +.TP +\fB-indent\fR integer +The number of characters to indent each line of the generated code by. +The default value is \fB0\fR. +.PP +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. +.PP +To help these latter users two adjunct packages are provided, each +containing a canned configuration which will generate immediately +useful full parsers. These are +.TP +\fBpt::tclparam::configuration::snit\fR +Generated parsers are classes based on the \fBsnit\fR package, +i.e. snit::type's. +.TP +\fBpt::tclparam::configuration::tcloo\fR +Generated parsers are classes based on the \fBOO\fR package. +.PP +.SH "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 +\fIPackRat Machine Specification\fR, using its instructions +and a few more to handle control flow. +.PP +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 +\fB-template\fR. The additional options +.TP +\fB-indent\fR integer +.TP +\fB-main\fR string +.TP +\fB-namespace\fR string +.TP +\fB-prelude\fR string +.TP +\fB-proc-command\fR string +.TP +\fB-runtime-command\fR string +.TP +\fB-self-command\fR string +.PP +provide code snippets which help to glue framework and generated code +together. Their placeholders are in the \fIgenerated\fR code. +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TCLPARAM, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_pegrammar.n Index: embedded/man/files/modules/pt/pt_pegrammar.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_pegrammar.n @@ -0,0 +1,678 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_pegrammar.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::peg" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::peg \- Parsing Expression Grammar Serialization +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::peg ?1?\fR +.sp +package require \fBpt::pe \fR +.sp +\fB::pt::peg\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +.sp +\fB::pt::peg\fR \fBverify-as-canonical\fR \fIserial\fR +.sp +\fB::pt::peg\fR \fBcanonicalize\fR \fIserial\fR +.sp +\fB::pt::peg\fR \fBprint\fR \fIserial\fR +.sp +\fB::pt::peg\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +.sp +\fB::pt::peg\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package provides commands to work with the serializations of +parsing expression grammars as managed by the Parser Tools, and +specified in section \fBPEG serialization format\fR. +.PP +This is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::peg\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +This command verifies that the content of \fIserial\fR 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. +.sp +If the argument \fIcanonvar\fR 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 \fIserial\fR is a valid regular +serialization. Its value will be a boolean, with \fBTrue\fR +indicating that the serialization is not only valid, but also +\fIcanonical\fR. \fBFalse\fR will be written for a valid, but +non-canonical serialization. +.sp +For the specification of serializations see the section +\fBPE serialization format\fR. +.TP +\fB::pt::peg\fR \fBverify-as-canonical\fR \fIserial\fR +This command verifies that the content of \fIserial\fR is a valid +\fIcanonical\fR serialization of a PEG and will throw an error if +that is not the case. The result of the command is the empty string. +.sp +For the specification of canonical serializations see the section +\fBPEG serialization format\fR. +.TP +\fB::pt::peg\fR \fBcanonicalize\fR \fIserial\fR +This command assumes that the content of \fIserial\fR is a valid +\fIregular\fR serialization of a PEG and will throw an error if that +is not the case. +.sp +It will then convert the input into the \fIcanonical\fR serialization +of the contained PEG and return it as its result. If the input is +already canonical it will be returned unchanged. +.sp +For the specification of regular and canonical serializations see the +section \fBPEG serialization format\fR. +.TP +\fB::pt::peg\fR \fBprint\fR \fIserial\fR +This command assumes that the argument \fIserial\fR contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form. +.sp +The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities. +.sp +For the specification of serializations see the section +\fBPEG serialization format\fR. +.TP +\fB::pt::peg\fR \fBmerge\fR \fIseriala\fR \fIserialb\fR +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. +.sp +A merge errors occurs if for any nonterminal symbol S occuring in both +input grammars the two input grammars specify different semantic +modes. +.sp +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. +.sp +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 \fIseriala\fR +coming first, except if both expressions are identical. In that case +the first expression is taken. +.sp +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. +.sp +The start expression of the unified grammar is the choice between the +start expressions of the input grammars, with the start expression of +\fIseriala\fR coming first, except if both expressions are identical. +In that case the first expression is taken +.TP +\fB::pt::peg\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +This command tests the two grammars \fIseriala\fR and \fIserialb\fR +for structural equality. The result of the command is a boolean +value. It will be set to \fBtrue\fR if the expressions are +identical, and \fBfalse\fR otherwise. +.sp +String equality is usable only if we can assume that the two grammars +are pure Tcl lists and dictionaries. +.PP +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_pexpr_op.n Index: embedded/man/files/modules/pt/pt_pexpr_op.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_pexpr_op.n @@ -0,0 +1,509 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_pexpr_op.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::pe::op" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::pe::op \- Parsing Expression Utilities +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::pe::op ?1?\fR +.sp +package require \fBpt::pe ?1?\fR +.sp +package require \fBstruct::set \fR +.sp +\fB::pt::pe::op\fR \fBdrop\fR \fIdropset\fR \fIpe\fR +.sp +\fB::pt::pe::op\fR \fBrename\fR \fInt\fR \fIntnew\fR \fIpe\fR +.sp +\fB::pt::pe::op\fR \fBcalled\fR \fIpe\fR +.sp +\fB::pt::pe::op\fR \fBflatten\fR \fIpe\fR +.sp +\fB::pt::pe::op\fR \fBfusechars\fR \fIpe\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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 +\fBPE serialization format\fR. +.PP +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. +.SH API +.TP +\fB::pt::pe::op\fR \fBdrop\fR \fIdropset\fR \fIpe\fR +This command removes all occurences of any of the nonterminals symbols +in the set \fIdropset\fR from the parsing expression \fIpe\fR, and +simplifies it. This may result in the expression becoming "epsilon", +i.e. matching nothing. +.TP +\fB::pt::pe::op\fR \fBrename\fR \fInt\fR \fIntnew\fR \fIpe\fR +This command renames all occurences of the nonterminal \fInt\fR in the +parsing expression \fIpe\fR into \fIntnew\fR. +.TP +\fB::pt::pe::op\fR \fBcalled\fR \fIpe\fR +This command extracts the set of all nonterminal symbols used, +i.e. 'called', in the parsing expression \fIpe\fR. +.TP +\fB::pt::pe::op\fR \fBflatten\fR \fIpe\fR +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. +.sp +The resulting parsing expression is returned as the result of the +command. +.TP +\fB::pt::pe::op\fR \fBfusechars\fR \fIpe\fR +This command transforms the parsing expression by fusing adjacent +terminals in sequences and adjacent terminals and ranges in choices, +it (re)constructs highlevel \fIstrings\fR and +\fIcharacter classes\fR. +.sp +The resulting pseudo-parsing expression is returned as the result of +the command and may contain the pseudo-operators \fBstr\fR for +character sequences, aka strings, and \fBcl\fR for character +choices, aka character classes. +.sp +The result is called a \fIpseudo-parsing expression\fR because it +is not a true parsing expression anymore, and will fail a check with +\fB::pt::peg verify\fR if the new pseudo-operators +are present in the result, but is otherwise of sound structure for a +parsing expression. +Notably, the commands \fB::pt::peg bottomup\fR and +\fB::pt::peg topdown\fR will process them without +trouble. +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_pexpression.n Index: embedded/man/files/modules/pt/pt_pexpression.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_pexpression.n @@ -0,0 +1,704 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_pexpression.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::pe" n 1 tcllib "Parser Tools" +.BS +.SH NAME +pt::pe \- Parsing Expression Serialization +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::pe ?1?\fR +.sp +package require \fBchar \fR +.sp +\fB::pt::pe\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +.sp +\fB::pt::pe\fR \fBverify-as-canonical\fR \fIserial\fR +.sp +\fB::pt::pe\fR \fBcanonicalize\fR \fIserial\fR +.sp +\fB::pt::pe\fR \fBprint\fR \fIserial\fR +.sp +\fB::pt::pe\fR \fBbottomup\fR \fIcmdprefix\fR \fIpe\fR +.sp +\fBcmdprefix\fR \fIpe\fR \fIop\fR \fIarguments\fR +.sp +\fB::pt::pe\fR \fBtopdown\fR \fIcmdprefix\fR \fIpe\fR +.sp +\fB::pt::pe\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +.sp +\fB::pt::pe\fR \fBepsilon\fR +.sp +\fB::pt::pe\fR \fBdot\fR +.sp +\fB::pt::pe\fR \fBalnum\fR +.sp +\fB::pt::pe\fR \fBalpha\fR +.sp +\fB::pt::pe\fR \fBascii\fR +.sp +\fB::pt::pe\fR \fBcontrol\fR +.sp +\fB::pt::pe\fR \fBdigit\fR +.sp +\fB::pt::pe\fR \fBgraph\fR +.sp +\fB::pt::pe\fR \fBlower\fR +.sp +\fB::pt::pe\fR \fBprint\fR +.sp +\fB::pt::pe\fR \fBpunct\fR +.sp +\fB::pt::pe\fR \fBspace\fR +.sp +\fB::pt::pe\fR \fBupper\fR +.sp +\fB::pt::pe\fR \fBwordchar\fR +.sp +\fB::pt::pe\fR \fBxdigit\fR +.sp +\fB::pt::pe\fR \fBddigit\fR +.sp +\fB::pt::pe\fR \fBterminal\fR \fIt\fR +.sp +\fB::pt::pe\fR \fBrange\fR \fIta\fR \fItb\fR +.sp +\fB::pt::pe\fR \fBnonterminal\fR \fInt\fR +.sp +\fB::pt::pe\fR \fBchoice\fR \fIpe\fR... +.sp +\fB::pt::pe\fR \fBsequence\fR \fIpe\fR... +.sp +\fB::pt::pe\fR \fBrepeat0\fR \fIpe\fR +.sp +\fB::pt::pe\fR \fBrepeat1\fR \fIpe\fR +.sp +\fB::pt::pe\fR \fBoptional\fR \fIpe\fR +.sp +\fB::pt::pe\fR \fBahead\fR \fIpe\fR +.sp +\fB::pt::pe\fR \fBnotahead\fR \fIpe\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package provides commands to work with the serializations of +parsing expressions as managed by the Parser Tools, and specified in +section \fBPE serialization format\fR. +.PP +This is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::pe\fR \fBverify\fR \fIserial\fR ?\fIcanonvar\fR? +This command verifies that the content of \fIserial\fR 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. +.sp +If the argument \fIcanonvar\fR 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 \fIserial\fR is a valid regular +serialization. Its value will be a boolean, with \fBTrue\fR +indicating that the serialization is not only valid, but also +\fIcanonical\fR. \fBFalse\fR will be written for a valid, but +non-canonical serialization. +.sp +For the specification of serializations see the section +\fBPE serialization format\fR. +.TP +\fB::pt::pe\fR \fBverify-as-canonical\fR \fIserial\fR +This command verifies that the content of \fIserial\fR is a valid +\fIcanonical\fR 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. +.sp +For the specification of canonical serializations see the section +\fBPE serialization format\fR. +.TP +\fB::pt::pe\fR \fBcanonicalize\fR \fIserial\fR +This command assumes that the content of \fIserial\fR is a valid +\fIregular\fR serialization of a parsing expression and will throw an +error if that is not the case. +.sp +It will then convert the input into the \fIcanonical\fR serialization +of this parsing expression and return it as its result. If the input +is already canonical it will be returned unchanged. +.sp +For the specification of regular and canonical serializations see the +section \fBPE serialization format\fR. +.TP +\fB::pt::pe\fR \fBprint\fR \fIserial\fR +This command assumes that the argument \fIserial\fR contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form. +.sp +The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities. +.sp +For the specification of serializations see the section +\fBPE serialization format\fR. +.TP +\fB::pt::pe\fR \fBbottomup\fR \fIcmdprefix\fR \fIpe\fR +This command walks the parsing expression \fIpe\fR from the bottom up +to the root, invoking the command prefix \fIcmdprefix\fR for each +partial expression. This implies that the children of a parsing +expression PE are handled before PE. +.sp +The command prefix has the signature +.RS +.TP +\fBcmdprefix\fR \fIpe\fR \fIop\fR \fIarguments\fR +I.e. it is invoked with the parsing expression \fIpe\fR the walk is +currently at, the \fIop\fR'erator in the \fIpe\fR, and the operator's +\fIarguments\fR. +.sp +The result returned by the command prefix replaces \fIpe\fR in the +parsing expression it was a child of, allowing transformations of the +expression tree. +.sp +This also means that for all inner parsing expressions the contents of +\fIarguments\fR are the results of the command prefix invoked for the +children of this inner parsing expression. +.RE +.TP +\fB::pt::pe\fR \fBtopdown\fR \fIcmdprefix\fR \fIpe\fR +This command walks the parsing expression \fIpe\fR from the root down +to the leaves, invoking the command prefix \fIcmdprefix\fR for each +partial expression. This implies that the children of a parsing +expression PE are handled after PE. +.sp +The command prefix has the same signature as for \fBbottomup\fR, +see above. +.sp +The result returned by the command prefix is \fIignored\fR. +.TP +\fB::pt::pe\fR \fBequal\fR \fIseriala\fR \fIserialb\fR +This command tests the two parsing expressions \fIseriala\fR and +\fIserialb\fR for structural equality. The result of the command is a +boolean value. It will be set to \fBtrue\fR if the expressions are +identical, and \fBfalse\fR otherwise. +.sp +String equality is usable only if we can assume that the two parsing +expressions are pure Tcl lists. +.TP +\fB::pt::pe\fR \fBepsilon\fR +This command constructs the atomic parsing expression for epsilon. +.TP +\fB::pt::pe\fR \fBdot\fR +This command constructs the atomic parsing expression for dot. +.TP +\fB::pt::pe\fR \fBalnum\fR +This command constructs the atomic parsing expression for alnum. +.TP +\fB::pt::pe\fR \fBalpha\fR +This command constructs the atomic parsing expression for alpha. +.TP +\fB::pt::pe\fR \fBascii\fR +This command constructs the atomic parsing expression for ascii. +.TP +\fB::pt::pe\fR \fBcontrol\fR +This command constructs the atomic parsing expression for control. +.TP +\fB::pt::pe\fR \fBdigit\fR +This command constructs the atomic parsing expression for digit. +.TP +\fB::pt::pe\fR \fBgraph\fR +This command constructs the atomic parsing expression for graph. +.TP +\fB::pt::pe\fR \fBlower\fR +This command constructs the atomic parsing expression for lower. +.TP +\fB::pt::pe\fR \fBprint\fR +This command constructs the atomic parsing expression for print. +.TP +\fB::pt::pe\fR \fBpunct\fR +This command constructs the atomic parsing expression for punct. +.TP +\fB::pt::pe\fR \fBspace\fR +This command constructs the atomic parsing expression for space. +.TP +\fB::pt::pe\fR \fBupper\fR +This command constructs the atomic parsing expression for upper. +.TP +\fB::pt::pe\fR \fBwordchar\fR +This command constructs the atomic parsing expression for wordchar. +.TP +\fB::pt::pe\fR \fBxdigit\fR +This command constructs the atomic parsing expression for xdigit. +.TP +\fB::pt::pe\fR \fBddigit\fR +This command constructs the atomic parsing expression for ddigit. +.TP +\fB::pt::pe\fR \fBterminal\fR \fIt\fR +This command constructs the atomic parsing expression for the terminal +symbol \fIt\fR. +.TP +\fB::pt::pe\fR \fBrange\fR \fIta\fR \fItb\fR +This command constructs the atomic parsing expression for the range of +terminal symbols \fIta\fR ... \fItb\fR. +.TP +\fB::pt::pe\fR \fBnonterminal\fR \fInt\fR +This command constructs the atomic parsing expression for the +nonterminal symbol \fInt\fR. +.TP +\fB::pt::pe\fR \fBchoice\fR \fIpe\fR... +This command constructs the parsing expression representing the +ordered or prioritized choice between the argument parsing +expressions. The first argument has the highest priority. +.TP +\fB::pt::pe\fR \fBsequence\fR \fIpe\fR... +This command constructs the parsing expression representing the +sequence of the argument parsing expression. The first argument is the +first element of the sequence. +.TP +\fB::pt::pe\fR \fBrepeat0\fR \fIpe\fR +This command constructs the parsing expression representing the zero +or more repetition of the argument parsing expression \fIpe\fR, also +known as the kleene closure. +.TP +\fB::pt::pe\fR \fBrepeat1\fR \fIpe\fR +This command constructs the parsing expression representing the one or +more repetition of the argument parsing expression \fIpe\fR, also +known as the positive kleene closure. +.TP +\fB::pt::pe\fR \fBoptional\fR \fIpe\fR +This command constructs the parsing expression representing the +optionality of the argument parsing expression \fIpe\fR. +.TP +\fB::pt::pe\fR \fBahead\fR \fIpe\fR +This command constructs the parsing expression representing the +positive lookahead of the argument parsing expression \fIpe\fR. +.TP +\fB::pt::pe\fR \fBnotahead\fR \fIpe\fR +This command constructs the parsing expression representing the +negative lookahead of the argument parsing expression \fIpe\fR. +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_pgen.n Index: embedded/man/files/modules/pt/pt_pgen.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_pgen.n @@ -0,0 +1,470 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_pgen.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::pgen" n 1.0.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::pgen \- Parser Generator +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::pgen ?1.0.1?\fR +.sp +\fB::pt::pgen\fR \fIinputformat\fR \fItext\fR \fIresultformat\fR ?\fIoptions...\fR? +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package provides a command implementing a +\fIparser generator\fR +taking parsing expression grammars as input. +.PP +It is the implementation of method \fBgenerate\fR of \fBpt\fR, the +\fIParser Tools Application\fR. +.PP +As such the intended audience of this document are people wishing to +modify and/or extend this part of \fBpt\fR's functionality. Users of +\fBpt\fR on the other hand are hereby refered to the applications' +manpage, i.e. \fIParser Tools Application\fR. +.PP +It resides in the User Package Layer of Parser Tools. +.PP +IMAGE: arch_user_pkg +.PP +.SH API +.TP +\fB::pt::pgen\fR \fIinputformat\fR \fItext\fR \fIresultformat\fR ?\fIoptions...\fR? +This command takes the parsing expression grammar in \fItext\fR (in +the format specified by \fIinputformat\fR), and returns the same +grammar in the format \fIresultformat\fR as the result of the command. +.sp +The two known input formats are \fBpeg\fR and \fBjson\fR. +Introductions to them, including their formal specifications, can be +found in the \fIPEG Language Tutorial\fR and +\fIThe JSON Grammar Exchange Format\fR. The packages used to +parse these formats are +.RS +.TP +\fBpeg\fR +\fBpt::peg::from::peg\fR +.TP +\fBjson\fR +\fBpt::peg::from::json\fR +.RE +.sp +On the output side the known formats, and the packages used to +generate them are +.RS +.TP +\fBc\fR +\fBpt::peg::to::cparam\fR +.TP +\fBcontainer\fR +\fBpt::peg::to::container\fR +.TP +\fBcritcl\fR +\fBpt::peg::to::cparam\fR + +\fBpt::cparam::configuration::critcl\fR +.TP +\fBjson\fR +\fBpt::peg::to::json\fR +.TP +\fBoo\fR +\fBpt::peg::to::tclparam\fR + +\fBpt::tclparam::configuration::tcloo\fR +.TP +\fBpeg\fR +\fBpt::peg::to::peg\fR +.TP +\fBsnit\fR +\fBpt::peg::to::tclparam\fR + +\fBpt::tclparam::configuration::snit\fR +.RE +.IP +The options supported by each of these formats are documented +with their respective packages. +.PP +.SH 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: +.PP +IMAGE: flow +.PP +Our grammar, assumed to the stored in the file "\fIcalculator.peg\fR" +is +.CS + + +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; + +.CE +From this we create a snit-based parser +using the script "\fIgen\fR" +.CS + + +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 + +.CE +calling it like +.CS + + tclsh8.5 gen calculator +.CE +which leaves us with the parser package and class written to the file +"\fIcalculator.tcl\fR". +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 +.CS + + + 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 ... + +.CE +where the abstract syntax tree stored in the variable will look like +.PP +.CS + + +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} + } + } + } +} + +.CE +.PP +assuming that the input file and channel contained the text +.CS + + 120+5 +.CE +A more graphical representation of the tree would be +.PP +.PS +.nf + +- Digit 0 0 | 1 + | | + +- Term 0 2 --- Number 0 2 -+- Digit 1 1 | 2 + | | | + | +- Digit 2 2 | 0 + | | +Expression 0 4 --- Factor 0 4 -+----------------------------- AddOp 3 3 | + + | | + +- Term 4 4 --- Number 4 4 --- Digit 4 4 | 5 +.fi +.PE +.PP +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 \fBpt::ast\fR should be of help +here, providing commands to walk such ASTs structures in various ways. +.PP +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 \fIno\fR callbacks during the +parsing process, i.e. no \fIparsing actions\fR, as most other +parsers will have. +.PP +Going back to the last snippet of code, the execution of the parser +for some input, note how the parser instance follows the specified +\fIParser API\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_rdengine.n Index: embedded/man/files/modules/pt/pt_rdengine.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_rdengine.n @@ -0,0 +1,1269 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_rdengine.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::rde" n 1.0.2 tcllib "Parser Tools" +.BS +.SH NAME +pt::rde \- Parsing Runtime Support, PARAM based +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::rde ?1.0.2?\fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::stack 1.4\fR +.sp +package require \fBpt::ast 1.1\fR +.sp +\fB::pt::rde\fR \fIobjectName\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBreset\fR \fIchan\fR +.sp +\fIobjectName\fR \fBcomplete\fR +.sp +\fIobjectName\fR \fBchan\fR +.sp +\fIobjectName\fR \fBline\fR +.sp +\fIobjectName\fR \fBcolumn\fR +.sp +\fIobjectName\fR \fBcurrent\fR +.sp +\fIobjectName\fR \fBlocation\fR +.sp +\fIobjectName\fR \fBlocations\fR +.sp +\fIobjectName\fR \fBok\fR +.sp +\fIobjectName\fR \fBvalue\fR +.sp +\fIobjectName\fR \fBerror\fR +.sp +\fIobjectName\fR \fBerrors\fR +.sp +\fIobjectName\fR \fBtokens\fR ?\fIfrom\fR ?\fIto\fR?? +.sp +\fIobjectName\fR \fBsymbols\fR +.sp +\fIobjectName\fR \fBknown\fR +.sp +\fIobjectName\fR \fBreducible\fR +.sp +\fIobjectName\fR \fBasts\fR +.sp +\fIobjectName\fR \fBast\fR +.sp +\fIobjectName\fR \fBposition\fR \fIloc\fR +.sp +\fIobjectName\fR \fBi_input_next\fR \fImsg\fR +.sp +\fIobjectName\fR \fBi_test_alnum\fR +.sp +\fIobjectName\fR \fBi_test_alpha\fR +.sp +\fIobjectName\fR \fBi_test_ascii\fR +.sp +\fIobjectName\fR \fBi_test_char\fR \fIchar\fR +.sp +\fIobjectName\fR \fBi_test_ddigit\fR +.sp +\fIobjectName\fR \fBi_test_digit\fR +.sp +\fIobjectName\fR \fBi_test_graph\fR +.sp +\fIobjectName\fR \fBi_test_lower\fR +.sp +\fIobjectName\fR \fBi_test_print\fR +.sp +\fIobjectName\fR \fBi_test_punct\fR +.sp +\fIobjectName\fR \fBi_test_range\fR \fIchars\fR \fIchare\fR +.sp +\fIobjectName\fR \fBi_test_space\fR +.sp +\fIobjectName\fR \fBi_test_upper\fR +.sp +\fIobjectName\fR \fBi_test_wordchar\fR +.sp +\fIobjectName\fR \fBi_test_xdigit\fR +.sp +\fIobjectName\fR \fBi_error_clear\fR +.sp +\fIobjectName\fR \fBi_error_push\fR +.sp +\fIobjectName\fR \fBi_error_pop_merge\fR +.sp +\fIobjectName\fR \fBi_error_nonterminal\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBi_status_ok\fR +.sp +\fIobjectName\fR \fBi_status_fail\fR +.sp +\fIobjectName\fR \fBi_status_negate\fR +.sp +\fIobjectName\fR \fBi_loc_push\fR +.sp +\fIobjectName\fR \fBi_loc_pop_discard\fR +.sp +\fIobjectName\fR \fBi_loc_pop_rewind\fR +.sp +\fIobjectName\fR \fBi:ok_loc_pop_rewind\fR +.sp +\fIobjectName\fR \fBi_loc_pop_rewind/discard\fR +.sp +\fIobjectName\fR \fBi_symbol_restore\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBi_symbol_save\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBi_value_clear\fR +.sp +\fIobjectName\fR \fBi_value_clear/leaf\fR +.sp +\fIobjectName\fR \fBi_value_clear/reduce\fR +.sp +\fIobjectName\fR \fBi:ok_ast_value_push\fR +.sp +\fIobjectName\fR \fBi_ast_push\fR +.sp +\fIobjectName\fR \fBi_ast_pop_rewind\fR +.sp +\fIobjectName\fR \fBi:fail_ast_pop_rewind\fR +.sp +\fIobjectName\fR \fBi_ast_pop_rewind/discard\fR +.sp +\fIobjectName\fR \fBi_ast_pop_discard\fR +.sp +\fIobjectName\fR \fBi_ast_pop_discard/rewind\fR +.sp +\fIobjectName\fR \fBi:ok_continue\fR +.sp +\fIobjectName\fR \fBi:fail_continue\fR +.sp +\fIobjectName\fR \fBi:fail_return\fR +.sp +\fIobjectName\fR \fBi:ok_return\fR +.sp +\fIobjectName\fR \fBsi:void_state_push\fR +.sp +\fIobjectName\fR \fBsi:void2_state_push\fR +.sp +\fIobjectName\fR \fBsi:value_state_push\fR +.sp +\fIobjectName\fR \fBsi:void_state_merge\fR +.sp +\fIobjectName\fR \fBsi:void_state_merge_ok\fR +.sp +\fIobjectName\fR \fBsi:value_state_merge\fR +.sp +\fIobjectName\fR \fBsi:value_notahead_start\fR +.sp +\fIobjectName\fR \fBsi:void_notahead_exit\fR +.sp +\fIobjectName\fR \fBsi:value_notahead_exit\fR +.sp +\fIobjectName\fR \fBsi:kleene_abort\fR +.sp +\fIobjectName\fR \fBsi:kleene_close\fR +.sp +\fIobjectName\fR \fBsi:voidvoid_branch\fR +.sp +\fIobjectName\fR \fBsi:voidvalue_branch\fR +.sp +\fIobjectName\fR \fBsi:valuevoid_branch\fR +.sp +\fIobjectName\fR \fBsi:valuevalue_branch\fR +.sp +\fIobjectName\fR \fBsi:voidvoid_part\fR +.sp +\fIobjectName\fR \fBsi:voidvalue_part\fR +.sp +\fIobjectName\fR \fBsi:valuevalue_part\fR +.sp +\fIobjectName\fR \fBsi:value_symbol_start\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:value_void_symbol_start\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:void_symbol_start\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:void_void_symbol_start\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:reduce_symbol_end\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:void_leaf_symbol_end\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:value_leaf_symbol_end\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:value_clear_symbol_end\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:void_clear_symbol_end\fR \fIsymbol\fR +.sp +\fIobjectName\fR \fBsi:next_char\fR \fItok\fR +.sp +\fIobjectName\fR \fBsi:next_range\fR \fItoks\fR \fItoke\fR +.sp +\fIobjectName\fR \fBsi:next_alnum\fR +.sp +\fIobjectName\fR \fBsi:next_alpha\fR +.sp +\fIobjectName\fR \fBsi:next_ascii\fR +.sp +\fIobjectName\fR \fBsi:next_ddigit\fR +.sp +\fIobjectName\fR \fBsi:next_digit\fR +.sp +\fIobjectName\fR \fBsi:next_graph\fR +.sp +\fIobjectName\fR \fBsi:next_lower\fR +.sp +\fIobjectName\fR \fBsi:next_print\fR +.sp +\fIobjectName\fR \fBsi:next_punct\fR +.sp +\fIobjectName\fR \fBsi:next_space\fR +.sp +\fIobjectName\fR \fBsi:next_upper\fR +.sp +\fIobjectName\fR \fBsi:next_wordchar\fR +.sp +\fIobjectName\fR \fBsi:next_xdigit\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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 \fIPackRat Machine Specification\fR, as such that +document is \fIrequired\fR 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. +.PP +The package resides in the Execution section of the Core Layer of +Parser Tools. +.PP +IMAGE: arch_core_transform +.PP +.PP +Note: This package not only has the standard Tcl implementation, but +also an accelerator, i.e. a C implementation, based on Critcl. +.PP +.SS "CLASS API" +The package exports the API described here. +.TP +\fB::pt::rde\fR \fIobjectName\fR +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 \fBObject API\fR. It may be used to +invoke various operations on the object. +.PP +.SS "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. +.PP +First some general methods and the state accessors. +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object, releasing all claimed memory, and +deleting the associated object command. +.TP +\fIobjectName\fR \fBreset\fR \fIchan\fR +This method resets the state of the runtme to its defaults, preparing +it for the parsing of the character in the channel \fIchan\fR, which +becomes IN. +.sp +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 \fIreflected channels\fR available. +.sp +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 \fBcoroutine::auto\fR to wrap it +into a coroutine where \fBread\fR is properly changed for +push-operation. +.TP +\fIobjectName\fR \fBcomplete\fR +This method completes parsing, either returning the AST made from the +elements of ARS, or throwing an error containing the current ER. +.TP +\fIobjectName\fR \fBchan\fR +This method returns the handle of the channel which is IN. +.TP +\fIobjectName\fR \fBline\fR +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. +.TP +\fIobjectName\fR \fBcolumn\fR +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. +.TP +\fIobjectName\fR \fBcurrent\fR +This method returns CC. +.TP +\fIobjectName\fR \fBlocation\fR +This method returns CL. +.TP +\fIobjectName\fR \fBlocations\fR +This method returns the LS. The topmost entry of the stack will be the +first element of the returned list. +.TP +\fIobjectName\fR \fBok\fR +This method returns ST. +.TP +\fIobjectName\fR \fBvalue\fR +This method returns SV. +.TP +\fIobjectName\fR \fBerror\fR +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). +.TP +\fIobjectName\fR \fBerrors\fR +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 \fBerror\fR. +.TP +\fIobjectName\fR \fBtokens\fR ?\fIfrom\fR ?\fIto\fR?? +This method returns the part of TC for the range of locations of IN +starting at \fIfrom\fR and ending at \fIto\fR. If \fIto\fR is not +specified it is taken as identical to \fIfrom\fR. If neither argument +is specified the whole of TC is returned. +.sp +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. +.TP +\fIobjectName\fR \fBsymbols\fR +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 \fBerror\fR. +.TP +\fIobjectName\fR \fBknown\fR +This method returns a list containing the keys of SC. They are +encoded in the same manner as is done by method \fBsymbols\fR. +.TP +\fIobjectName\fR \fBreducible\fR +This method returns ARS. The topmost entry of the stack will be the +first element of the returned list +.TP +\fIobjectName\fR \fBasts\fR +This method returns AS. The topmost entry of the stack will be the +first element of the returned list +.TP +\fIobjectName\fR \fBast\fR +This is a convenience method returning the topmost element of ARS. +.TP +\fIobjectName\fR \fBposition\fR \fIloc\fR +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. +.PP +The following methods implement all PARAM instructions. They all have +the prefix "i_". +.PP +The control flow is mainly provided by Tcl's builtin commands, like +\fBif\fR, \fBwhile\fR, 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. +.PP +The instructions are listed in the same order they occur in the +\fIPackRat Machine Specification\fR, with the guard variants +listed after their regular implementation, if any, or in their place. +.TP +\fIobjectName\fR \fBi_input_next\fR \fImsg\fR +This method implements the PARAM instruction \fBinput_next\fR. +.TP +\fIobjectName\fR \fBi_test_alnum\fR +This method implements the PARAM instruction \fBtest_alnum\fR. +.TP +\fIobjectName\fR \fBi_test_alpha\fR +This method implements the PARAM instruction \fBtest_alpha\fR. +.TP +\fIobjectName\fR \fBi_test_ascii\fR +This method implements the PARAM instruction \fBtest_ascii\fR. +.TP +\fIobjectName\fR \fBi_test_char\fR \fIchar\fR +This method implements the PARAM instruction \fBtest_char\fR. +.TP +\fIobjectName\fR \fBi_test_ddigit\fR +This method implements the PARAM instruction \fBtest_ddigit\fR. +.TP +\fIobjectName\fR \fBi_test_digit\fR +This method implements the PARAM instruction \fBtest_digit\fR. +.TP +\fIobjectName\fR \fBi_test_graph\fR +This method implements the PARAM instruction \fBtest_graph\fR. +.TP +\fIobjectName\fR \fBi_test_lower\fR +This method implements the PARAM instruction \fBtest_lower\fR. +.TP +\fIobjectName\fR \fBi_test_print\fR +This method implements the PARAM instruction \fBtest_print\fR. +.TP +\fIobjectName\fR \fBi_test_punct\fR +This method implements the PARAM instruction \fBtest_punct\fR. +.TP +\fIobjectName\fR \fBi_test_range\fR \fIchars\fR \fIchare\fR +This method implements the PARAM instruction \fBtest_range\fR. +.TP +\fIobjectName\fR \fBi_test_space\fR +This method implements the PARAM instruction \fBtest_space\fR. +.TP +\fIobjectName\fR \fBi_test_upper\fR +This method implements the PARAM instruction \fBtest_upper\fR. +.TP +\fIobjectName\fR \fBi_test_wordchar\fR +This method implements the PARAM instruction \fBtest_wordchar\fR. +.TP +\fIobjectName\fR \fBi_test_xdigit\fR +This method implements the PARAM instruction \fBtest_xdigit\fR. +.TP +\fIobjectName\fR \fBi_error_clear\fR +This method implements the PARAM instruction \fBerror_clear\fR. +.TP +\fIobjectName\fR \fBi_error_push\fR +This method implements the PARAM instruction \fBerror_push\fR. +.TP +\fIobjectName\fR \fBi_error_pop_merge\fR +This method implements the PARAM instruction \fBerror_pop_merge\fR. +.TP +\fIobjectName\fR \fBi_error_nonterminal\fR \fIsymbol\fR +This method implements the PARAM instruction \fBerror_nonterminal\fR. +.TP +\fIobjectName\fR \fBi_status_ok\fR +This method implements the PARAM instruction \fBstatus_ok\fR. +.TP +\fIobjectName\fR \fBi_status_fail\fR +This method implements the PARAM instruction \fBstatus_fail\fR. +.TP +\fIobjectName\fR \fBi_status_negate\fR +This method implements the PARAM instruction \fBstatus_negate\fR. +.TP +\fIobjectName\fR \fBi_loc_push\fR +This method implements the PARAM instruction \fBloc_push\fR. +.TP +\fIobjectName\fR \fBi_loc_pop_discard\fR +This method implements the PARAM instruction \fBloc_pop_discard\fR. +.TP +\fIobjectName\fR \fBi_loc_pop_rewind\fR +This method implements the PARAM instruction \fBloc_pop_rewind\fR. +.TP +\fIobjectName\fR \fBi:ok_loc_pop_rewind\fR +This guarded method, a variant of \fBi_loc_pop_rewind\fR, executes only +for "ST == ok". +.TP +\fIobjectName\fR \fBi_loc_pop_rewind/discard\fR +This method is a convenient combination of control flow and the two +PARAM instructions \fBloc_pop_rewind\fR and \fBloc_pop_discard\fR. The former +is executed for "ST == fail", the latter for "ST == ok". +.TP +\fIobjectName\fR \fBi_symbol_restore\fR \fIsymbol\fR +This method implements the PARAM instruction \fBsymbol_restore\fR. +.sp +The boolean result of the check is returned as the result of +the method and can be used with standard Tcl control flow commands. +.TP +\fIobjectName\fR \fBi_symbol_save\fR \fIsymbol\fR +This method implements the PARAM instruction \fBsymbol_save\fR. +.TP +\fIobjectName\fR \fBi_value_clear\fR +This method implements the PARAM instruction \fBvalue_clear\fR. +.TP +\fIobjectName\fR \fBi_value_clear/leaf\fR +This method is a convenient combination of control flow and the two +PARAM instructions \fBvalue_clear\fR and \fBvalue_leaf\fR. The former +is executed for "ST == fail", the latter for "ST == ok". +.TP +\fIobjectName\fR \fBi_value_clear/reduce\fR +This method is a convenient combination of control flow and the two +PARAM instructions \fBvalue_clear\fR and \fBvalue_reduce\fR. The former +is executed for "ST == fail", the latter for "ST == ok". +.TP +\fIobjectName\fR \fBi:ok_ast_value_push\fR +This method implements a guarded variant of the the PARAM instruction +\fBast_value_push\fR, which executes only for "ST == ok". +.TP +\fIobjectName\fR \fBi_ast_push\fR +This method implements the PARAM instruction \fBast_push\fR. +.TP +\fIobjectName\fR \fBi_ast_pop_rewind\fR +This method implements the PARAM instruction \fBast_pop_rewind\fR. +.TP +\fIobjectName\fR \fBi:fail_ast_pop_rewind\fR +This guarded method, a variant of \fBi_ast_pop_rewind\fR, executes only +for "ST == fail". +.TP +\fIobjectName\fR \fBi_ast_pop_rewind/discard\fR +This method is a convenient combination of control flow and the two +PARAM instructions \fBast_pop_rewind\fR and \fBast_pop_discard\fR. The former +is executed for "ST == fail", the latter for "ST == ok". +.TP +\fIobjectName\fR \fBi_ast_pop_discard\fR +This method implements the PARAM instruction \fBast_pop_discard\fR. +.TP +\fIobjectName\fR \fBi_ast_pop_discard/rewind\fR +This method is a convenient combination of control flow and the two +PARAM instructions \fBast_pop_discard\fR and \fBast_pop_rewind\fR. The former +is executed for "ST == fail", the latter for "ST == ok". +.TP +\fIobjectName\fR \fBi:ok_continue\fR +This guarded method executes only for "ST == ok". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure. +.TP +\fIobjectName\fR \fBi:fail_continue\fR +This guarded method executes only for "ST == fail". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure. +.TP +\fIobjectName\fR \fBi:fail_return\fR +This guarded method executes only for "ST == fail". Then it aborts the +calling Tcl procedure. +.TP +\fIobjectName\fR \fBi:ok_return\fR +This guarded method executes only for "ST == ok". Then it aborts the +calling Tcl procedure. +.PP +.PP +The next set of methods are \fIsuper instructions\fR, 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. +.PP +In this we can see the reasoning behind their use well: +.IP [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. +.IP [2] +Using less instructions additionally reduces the overhead associated +with calls into the runtime, i.e. the cost of method dispatch and of +setting up the variable context. +.IP [3] +Another effect of the super instructions is that their internals can +be optimized as well, especially regarding control flow, and stack +use, as the runtime internals are accessible to all instructions +folded into the sequence. +.PP +.PP +.TP +\fIobjectName\fR \fBsi:void_state_push\fR +This method combines +.CS + + +i_loc_push +i_error_clear +i_error_push + +.CE +.IP +Parsers use it at the beginning of \fIvoid\fR sequences and choices +with a \fIvoid\fR initial branch. +.TP +\fIobjectName\fR \fBsi:void2_state_push\fR +This method combines +.CS + + +i_loc_push +i_error_clear +i_error_push + +.CE +.IP +Parsers use it at the beginning of optional and repeated expressions. +.TP +\fIobjectName\fR \fBsi:value_state_push\fR +This method combines +.CS + + +i_ast_push +i_loc_push +i_error_clear +i_error_push + +.CE +.IP +Parsers use it at the beginning of sequences generating an AST and +choices with an initial branch generating an AST. +.TP +\fIobjectName\fR \fBsi:void_state_merge\fR +This method combines +.CS + + +i_error_pop_merge +i_loc_pop_rewind/discard + +.CE +.IP +Parsers use it at the end of void sequences and choices whose last +branch is void. +.TP +\fIobjectName\fR \fBsi:void_state_merge_ok\fR +This method combines +.CS + + +i_error_pop_merge +i_loc_pop_rewind/discard +i_status_ok + +.CE +.IP +Parsers use it at the end of optional expressions +.TP +\fIobjectName\fR \fBsi:value_state_merge\fR +This method combines +.CS + + +i_error_pop_merge +i_ast_pop_rewind/discard +i_loc_pop_rewind/discard + +.CE +.IP +Parsers use it at the end of sequences generating ASTs and choices +whose last branch generates an AST +.TP +\fIobjectName\fR \fBsi:value_notahead_start\fR +This method combines +.CS + + +i_loc_push +i_ast_push + +.CE +.IP +Parsers use it at the beginning of negative lookahead predicates which +generate ASTs. +.TP +\fIobjectName\fR \fBsi:void_notahead_exit\fR +This method combines +.CS + + +i_loc_pop_rewind +i_status_negate + +.CE +.IP +Parsers use it at the end of void negative lookahead predicates. +.TP +\fIobjectName\fR \fBsi:value_notahead_exit\fR +This method combines +.CS + + +i_ast_pop_discard/rewind +i_loc_pop_rewind +i_status_negate + +.CE +.IP +Parsers use it at the end of negative lookahead predicates which +generate ASTs. +.TP +\fIobjectName\fR \fBsi:kleene_abort\fR +This method combines +.CS + + +i_loc_pop_rewind/discard +i:fail_return + +.CE +.IP +Parsers use it to stop a positive repetition when its first, required, expression fails. +.TP +\fIobjectName\fR \fBsi:kleene_close\fR +This method combines +.CS + + +i_error_pop_merge +i_loc_pop_rewind/discard +i:fail_status_ok +i:fail_return + +.CE +.IP +Parsers use it at the end of repetitions. +.TP +\fIobjectName\fR \fBsi:voidvoid_branch\fR +This method combines +.CS + + +i_error_pop_merge +i:ok_loc_pop_discard +i:ok_return +i_loc_rewind +i_error_push + +.CE +.IP +Parsers use it when transiting between branches of a choice when both are void. +.TP +\fIobjectName\fR \fBsi:voidvalue_branch\fR +This method combines +.CS + + +i_error_pop_merge +i:ok_loc_pop_discard +i:ok_return +i_ast_push +i_loc_rewind +i_error_push + +.CE +.IP +Parsers use it when transiting between branches of a choice when the +failing branch is void, and the next to test generates an AST. +.TP +\fIobjectName\fR \fBsi:valuevoid_branch\fR +This method combines +.CS + + +i_error_pop_merge +i_ast_pop_rewind/discard +i:ok_loc_pop_discard +i:ok_return +i_loc_rewind +i_error_push + +.CE +.IP +Parsers use it when transiting between branches of a choice when the +failing branch generates an AST, and the next to test is void. +.TP +\fIobjectName\fR \fBsi:valuevalue_branch\fR +This method combines +.CS + + +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 + +.CE +.IP +Parsers use it when transiting between branches of a choice when both +generate ASTs. +.TP +\fIobjectName\fR \fBsi:voidvoid_part\fR +This method combines +.CS + + +i_error_pop_merge +i:fail_loc_pop_rewind +i:fail_return +i_error_push + +.CE +.IP +Parsers use it when transiting between parts of a sequence and both +are void. +.TP +\fIobjectName\fR \fBsi:voidvalue_part\fR +This method combines +.CS + + +i_error_pop_merge +i:fail_loc_pop_rewind +i:fail_return +i_ast_push +i_error_push + +.CE +.IP +Parsers use it when transiting between parts of a sequence and the +sucessfully matched part is void, and after it an AST is generated. +.TP +\fIobjectName\fR \fBsi:valuevalue_part\fR +This method combines +.CS + + +i_error_pop_merge +i:fail_ast_pop_rewind +i:fail_loc_pop_rewind +i:fail_return +i_error_push + +.CE +.IP +Parsers use it when transiting between parts of a sequence and both +parts generate ASTs. +.TP +\fIobjectName\fR \fBsi:value_symbol_start\fR \fIsymbol\fR +This method combines +.CS + + +if/found? i_symbol_restore $symbol +i:found:ok_ast_value_push +i:found_return +i_loc_push +i_ast_push + +.CE +.IP +Parsers use it at the beginning of a nonterminal symbol generating an +AST, whose right-hand side may have generated an AST as well. +.TP +\fIobjectName\fR \fBsi:value_void_symbol_start\fR \fIsymbol\fR +This method combines +.CS + + +if/found? i_symbol_restore $symbol +i:found:ok_ast_value_push +i:found_return +i_loc_push +i_ast_push + +.CE +.IP +Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side may generate an AST. +.TP +\fIobjectName\fR \fBsi:void_symbol_start\fR \fIsymbol\fR +This method combines +.CS + + +if/found? i_symbol_restore $symbol +i:found_return +i_loc_push +i_ast_push + +.CE +.IP +Parsers use it at the beginning of a nonterminal symbol generating an +AST whose right-hand side is void. +.TP +\fIobjectName\fR \fBsi:void_void_symbol_start\fR \fIsymbol\fR +This method combines +.CS + + +if/found? i_symbol_restore $symbol +i:found_return +i_loc_push + +.CE +.IP +Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side is void as well. +.TP +\fIobjectName\fR \fBsi:reduce_symbol_end\fR \fIsymbol\fR +This method combines +.CS + + +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 + +.CE +.IP +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. +.TP +\fIobjectName\fR \fBsi:void_leaf_symbol_end\fR \fIsymbol\fR +This method combines +.CS + + +i_value_clear/leaf $symbol +i_symbol_save $symbol +i_error_nonterminal $symbol +i_loc_pop_discard +i:ok_ast_value_push + +.CE +.IP +Parsers use it at the end of a non-terminal symbol generating an AST +whose right-hand side is void. +.TP +\fIobjectName\fR \fBsi:value_leaf_symbol_end\fR \fIsymbol\fR +This method combines +.CS + + +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 + +.CE +.IP +Parsers use it at the end of a non-terminal symbol generating an AST +discarding the AST generated by the right-hand side. +.TP +\fIobjectName\fR \fBsi:value_clear_symbol_end\fR \fIsymbol\fR +This method combines +.CS + + +i_value_clear +i_symbol_save $symbol +i_error_nonterminal $symbol +i_loc_pop_discard +i_ast_pop_rewind + +.CE +.IP +Parsers use it at the end of a void non-terminal symbol, discarding +the AST generated by the right-hand side. +.TP +\fIobjectName\fR \fBsi:void_clear_symbol_end\fR \fIsymbol\fR +This method combines +.CS + + +i_value_clear +i_symbol_save $symbol +i_error_nonterminal $symbol +i_loc_pop_discard + +.CE +.IP +Parsers use it at the end of a void non-terminal symbol with a void +right-hand side. +.TP +\fIobjectName\fR \fBsi:next_char\fR \fItok\fR +.TP +\fIobjectName\fR \fBsi:next_range\fR \fItoks\fR \fItoke\fR +.TP +\fIobjectName\fR \fBsi:next_alnum\fR +.TP +\fIobjectName\fR \fBsi:next_alpha\fR +.TP +\fIobjectName\fR \fBsi:next_ascii\fR +.TP +\fIobjectName\fR \fBsi:next_ddigit\fR +.TP +\fIobjectName\fR \fBsi:next_digit\fR +.TP +\fIobjectName\fR \fBsi:next_graph\fR +.TP +\fIobjectName\fR \fBsi:next_lower\fR +.TP +\fIobjectName\fR \fBsi:next_print\fR +.TP +\fIobjectName\fR \fBsi:next_punct\fR +.TP +\fIobjectName\fR \fBsi:next_space\fR +.TP +\fIobjectName\fR \fBsi:next_upper\fR +.TP +\fIobjectName\fR \fBsi:next_wordchar\fR +.TP +\fIobjectName\fR \fBsi:next_xdigit\fR +These methods all combine +.CS + + +i_input_next $msg +i:fail_return + +.CE +.IP +with the appropriate \fBi_test_xxx\fR instruction. Parsers use them for +handling atomic expressions. +.PP +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_tclparam_config_snit.n Index: embedded/man/files/modules/pt/pt_tclparam_config_snit.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_tclparam_config_snit.n @@ -0,0 +1,302 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_tclparam_config_snit.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::tclparam::configuration::snit" n 1.0.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::tclparam::configuration::snit \- Tcl/PARAM, Canned configuration, Snit +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::tclparam::configuration::snit ?1.0.1?\fR +.sp +\fB::pt::tclparam::configuration::snit\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package is an adjunct to \fBpt::peg::to::tclparam\fR, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package \fBpt::peg::to::tclparam\fR to generate +\fBsnit\fR-based parser packages. +.PP +It is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::tclparam::configuration::snit\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +The command applies the configuration provided by this package to the +\fIcmdprefix\fR, causing the creation of \fBsnit\fR-based parsers +whose class is \fIname\fR. +.sp +The use of a command prefix as API allows application of the +configuration to not only \fBpt::peg::to::tclparam\fR +(\fBpt::peg::to::tclparam configure\fR), but also export manager +instances and PEG containers (\fB$export configuration set\fR and +\fB[$container exporter] configuration set\fR respectively). +.sp +Or anything other command prefix accepting two arguments, option and +value. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n Index: embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n @@ -0,0 +1,302 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_tclparam_config_tcloo.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt::tclparam::configuration::tcloo" n 1.0.1 tcllib "Parser Tools" +.BS +.SH NAME +pt::tclparam::configuration::tcloo \- Tcl/PARAM, Canned configuration, Tcloo +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBpt::tclparam::configuration::tcloo ?1.0.1?\fR +.sp +\fB::pt::tclparam::configuration::tcloo\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +This package is an adjunct to \fBpt::peg::to::tclparam\fR, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package \fBpt::peg::to::tclparam\fR to generate +\fBOO\fR-based parser packages. +.PP +It is a supporting package in the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_support +.PP +.SH API +.TP +\fB::pt::tclparam::configuration::tcloo\fR \fBdef\fR \fIname\fR \fIcmdprefix\fR +The command applies the configuration provided by this package to the +\fIcmdprefix\fR, causing the creation of \fBOO\fR-based parsers +whose class is \fIname\fR. +.sp +The use of a command prefix as API allows application of the +configuration to not only \fBpt::peg::to::tclparam\fR +(\fBpt::peg::to::tclparam configure\fR), but also export manager +instances and PEG containers (\fB$export configuration set\fR and +\fB[$container exporter] configuration set\fR respectively). +.sp +Or anything other command prefix accepting two arguments, option and +value. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/pt/pt_to_api.n Index: embedded/man/files/modules/pt/pt_to_api.n ================================================================== --- /dev/null +++ embedded/man/files/modules/pt/pt_to_api.n @@ -0,0 +1,755 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/pt/pt_to_api.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "pt_export_api" i 1 tcllib "Parser Tools" +.BS +.SH NAME +pt_export_api \- Parser Tools Export API +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +\fBCONVERTER\fR \fBreset\fR +.sp +\fBCONVERTER\fR \fBconfigure\fR +.sp +\fBCONVERTER\fR \fBconfigure\fR \fIoption\fR +.sp +\fBCONVERTER\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fBCONVERTER\fR \fBconvert\fR \fIserial\fR +.sp +\fB::export\fR \fIserial\fR \fIconfiguration\fR +.sp +.BE +.SH DESCRIPTION +.PP +Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +\fIIntroduction to Parser Tools\fR. This document is the +entrypoint to the whole system the current package is a part of. +.PP +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. +.PP +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. +.PP +It resides in the Export section of the Core Layer of Parser Tools. +.PP +IMAGE: arch_core_export +.PP +.SH "CONVERTER API" +Any (grammar) export converter has to follow the rules set out below: +.IP [1] +A converter is a package. Its name is arbitrary, however it is +recommended to put it under the \fB::pt::peg::to\fR +namespace. +.IP [2] +The package provides either a single Tcl command following the +API outlined below, or a class command whose instances follow +the same API. The commands which follow the API are called +\fIconverter commands\fR. +.IP [3] +A converter command has to provide the following three methods +with the given signatures and semantics. Converter commands +are allowed to provide more methods of their own, but not +less, and they may not provide different semantics for the +standardized methods. +.RS +.TP +\fBCONVERTER\fR \fBreset\fR +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. +.TP +\fBCONVERTER\fR \fBconfigure\fR +This method, in this form, has to return a dictionary containing the +current configuration of the converter. +.TP +\fBCONVERTER\fR \fBconfigure\fR \fIoption\fR +This method, in this form, has to return the current value of the +specified configuration \fIoption\fR of the converter. +.sp +Please read the section \fBOptions\fR 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. +.TP +\fBCONVERTER\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +This command, in this form, sets the specified \fIoption\fRs of the +converter to the given \fIvalue\fRs. +.sp +Please read the section \fBOptions\fR 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. +.TP +\fBCONVERTER\fR \fBconvert\fR \fIserial\fR +This method has to accept the canonical serialization of a parsing +expression grammar, as specified in section +\fBPEG serialization format\fR, and contained in \fIserial\fR. +The result of the method has to be the result of converting the input +grammar into whatever the converter is for, per its configuration. +.RE +.PP +.SH "PLUGIN API" +Any (grammar) export plugin has to follow the rules set out below: +.IP [1] +A plugin is a package. +.IP [2] +The name of a plugin package has the form +pt::peg::export::\fBFOO\fR, +where \fBFOO\fR is the name of the format the plugin will +generate output for. +.IP [3] +The plugin can expect that the package +\fBpt::peg::export::plugin\fR is present, as +indicator that it was invoked from a genuine plugin manager. +.sp +It is recommended that a plugin does check for the presence of +this package. +.IP [4] +A plugin has to provide a single command, in the global +namespace, with the signature shown below. Plugins are allowed +to provide more command of their own, but not less, and they +may not provide different semantics for the standardized +command. +.RS +.TP +\fB::export\fR \fIserial\fR \fIconfiguration\fR +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. +.RS +.TP +string \fIserial\fR +This argument will contain the \fIcanonical\fR serialization of the +parsing expression grammar for which to generate the output. +The specification of what a \fIcanonical\fR serialization is can be +found in the section \fBPEG serialization format\fR. +.TP +dictionary \fIconfiguration\fR +This argument will contain the configuration to configure the +converter with before invoking it, as a dictionary mapping from +options to values. +.sp +Please read the section \fBOptions\fR 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. +.RE +.RE +.IP [5] +A single usage cycle of a plugin consists of an invokation of +the command \fBexport\fR. This call has to leave the plugin in +a state where another usage cycle can be run without problems. +.PP +.SH OPTIONS +Each export converter and plugin for an export converter has to accept +the options below in their \fBconfigure\fR 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. +.TP +\fB-file\fR 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 \fBunknown\fR. +.TP +\fB-name\fR string +The value of this option is the name of the grammar we are processing. +The default value is \fBa_pe_grammar\fR. +.TP +\fB-user\fR string +The value of this option is the name of the user for which the command +is run. The default value is \fBunknown\fR. +.PP +.SH USAGE +To use a converter do +.CS + + + # 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 ... + +.CE +To use a plugin \fBFOO\fR do +.CS + + + # 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 ... + +.CE +.SH "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. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be \fIcanonical\fR. +.TP +regular serialization +.RS +.IP [1] +The serialization of any PEG is a nested Tcl dictionary. +.IP [2] +This dictionary holds a single key, \fBpt::grammar::peg\fR, and its +value. This value holds the contents of the grammar. +.IP [3] +The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are +.RS +.TP +\fBrules\fR +The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar. +.RS +.IP [1] +Each nonterminal symbol may occur only once. +.IP [2] +The empty string is not a legal nonterminal symbol. +.IP [3] +The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are +.RS +.TP +\fBis\fR +The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +\fBPE serialization format\fR. +.TP +\fBmode\fR +The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol. +.RS +.TP +\fBvalue\fR +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. +.TP +\fBleaf\fR +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. +.TP +\fBvoid\fR +The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well). +.RE +.RE +.RE +.TP +\fBstart\fR +The value is the serialization of the start parsing expression of the +grammar, as specified in the section \fBPE serialization format\fR. +.RE +.IP [4] +The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules. +.RE +.TP +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. +.RS +.IP [1] +The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +\fBlsort -increasing -dict\fR. +.IP [2] +The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace. +.RE +.PP +.SS EXAMPLE +Assuming the following PEG for simple mathematical expressions +.PP +.CS + + +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; + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + +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} +} + +.CE +.PP +.SH "PE SERIALIZATION FORMAT" +Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc. +.PP +We distinguish between \fIregular\fR and \fIcanonical\fR +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be \fIcanonical\fR. +.TP +Regular serialization +.RS +.TP +\fBAtomic Parsing Expressions\fR +.RS +.IP [1] +The string \fBepsilon\fR is an atomic parsing expression. It matches +the empty string. +.IP [2] +The string \fBdot\fR is an atomic parsing expression. It matches +any character. +.IP [3] +The string \fBalnum\fR 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 \fBstring is\fR. +.IP [4] +The string \fBalpha\fR is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [5] +The string \fBascii\fR 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 \fBstring is\fR. +.IP [6] +The string \fBcontrol\fR is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [7] +The string \fBdigit\fR 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 \fBstring is\fR. +.IP [8] +The string \fBgraph\fR 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 \fBstring is\fR. +.IP [9] +The string \fBlower\fR 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 \fBstring is\fR. +.IP [10] +The string \fBprint\fR 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 \fBstring is\fR. +.IP [11] +The string \fBpunct\fR is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [12] +The string \fBspace\fR is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command \fBstring is\fR. +.IP [13] +The string \fBupper\fR 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 \fBstring is\fR. +.IP [14] +The string \fBwordchar\fR 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 \fBstring is\fR. +.IP [15] +The string \fBxdigit\fR is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command \fBstring is\fR. +.IP [16] +The string \fBddigit\fR is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command \fBregexp\fR. +.IP [17] +The expression +[list t \fBx\fR] +is an atomic parsing expression. It matches the terminal string \fBx\fR. +.IP [18] +The expression +[list n \fBA\fR] +is an atomic parsing expression. It matches the nonterminal \fBA\fR. +.RE +.TP +\fBCombined Parsing Expressions\fR +.RS +.IP [1] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list / \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIordered choice\fR, aka \fIprioritized choice\fR. +.IP [2] +For parsing expressions \fBe1\fR, \fBe2\fR, ... the result of +[list x \fBe1\fR \fBe2\fR ... ] +is a parsing expression as well. +This is the \fIsequence\fR. +.IP [3] +For a parsing expression \fBe\fR the result of +[list * \fBe\fR] +is a parsing expression as well. +This is the \fIkleene closure\fR, describing zero or more +repetitions. +.IP [4] +For a parsing expression \fBe\fR the result of +[list + \fBe\fR] +is a parsing expression as well. +This is the \fIpositive kleene closure\fR, describing one or more +repetitions. +.IP [5] +For a parsing expression \fBe\fR the result of +[list & \fBe\fR] +is a parsing expression as well. +This is the \fIand lookahead predicate\fR. +.IP [6] +For a parsing expression \fBe\fR the result of +[list ! \fBe\fR] +is a parsing expression as well. +This is the \fInot lookahead predicate\fR. +.IP [7] +For a parsing expression \fBe\fR the result of +[list ? \fBe\fR] +is a parsing expression as well. +This is the \fIoptional input\fR. +.RE +.RE +.TP +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. +.RS +.IP [1] +The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace. +.IP [2] +Terminals are \fInot\fR encoded as ranges (where start and end of the +range are identical). +.RE +.PP +.PP +.SS EXAMPLE +Assuming the parsing expression shown on the right-hand side of the +rule +.PP +.CS + + + Expression <- Term (AddOp Term)* + +.CE +.PP +then its canonical serialization (except for whitespace) is +.PP +.CS + + + {x {n Term} {* {x {n AddOp} {n Term}}}} + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIpt\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer +.SH CATEGORY +Parsing and Grammars +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/rc4/rc4.n Index: embedded/man/files/modules/rc4/rc4.n ================================================================== --- /dev/null +++ embedded/man/files/modules/rc4/rc4.n @@ -0,0 +1,354 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/rc4/rc4.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "rc4" n 1.1.0 tcllib "RC4 Stream Cipher" +.BS +.SH NAME +rc4 \- Implementation of the RC4 stream cipher +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBrc4 ?1.1.0?\fR +.sp +\fB::rc4::rc4\fR ?\fI-hex\fR? \fI-key keyvalue\fR ?\fI-command lst\fR? ?\fI-out channel\fR? [ \fI-in channel\fR | \fI-infile filename\fR | \fIstring\fR ] +.sp +\fB::rc4::RC4Init\fR \fIkeydata\fR +.sp +\fB::rc4::RC4\fR \fIKey\fR \fIdata\fR +.sp +\fB::rc4::RC4Final\fR \fIKey\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::rc4::rc4\fR ?\fI-hex\fR? \fI-key keyvalue\fR ?\fI-command lst\fR? ?\fI-out channel\fR? [ \fI-in channel\fR | \fI-infile filename\fR | \fIstring\fR ] +Perform the RC4 algorithm on either the data provided by the argument +or on the data read from the \fI-in\fR channel. If an \fI-out\fR +channel is given then the result will be written to this channel. +Giving the \fI-hex\fR option will return a hexadecimal encoded +version of the result if not using an \fI-out\fR channel. +.sp +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 +\fI-infile\fR argument is given then the file is opened, the data read +and processed and the file is closed. If the \fI-in\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. If the \fI-out\fR argument is given then the +processing result is written to this channel. +.sp +If \fI-command\fR 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 +.sp +Only one of \fI-infile\fR, \fI-in\fR or \fIstring\fR should be given. +.PP +.SH "PROGRAMMING INTERFACE" +.TP +\fB::rc4::RC4Init\fR \fIkeydata\fR +Initialize a new RC4 key. The \fIkeydata\fR is any amount of binary +data and is used to initialize the cipher internal state. +.TP +\fB::rc4::RC4\fR \fIKey\fR \fIdata\fR +Encrypt or decrypt the input data using the key obtained by calling +\fBRC4Init\fR. +.TP +\fB::rc4::RC4Final\fR \fIKey\fR +This should be called to clean up resources associated with +\fIKey\fR. Once this function has been called the key is destroyed. +.PP +.SH EXAMPLES +.CS + + +% set keydata [binary format H* 0123456789abcdef] +% rc4::rc4 -hex -key $keydata HelloWorld +3cf1ae8b7f1c670b612f +% rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f] +HelloWorld + +.CE +.CS + + + set Key [rc4::RC4Init "key data"] + append ciphertext [rc4::RC4 $Key $plaintext] + append ciphertext [rc4::RC4 $Key $additional_plaintext] + rc4::RC4Final $Key + +.CE +.CS + + + proc ::Finish {myState data} { + DoStuffWith $myState $data + } + rc4::rc4 -in $socket -command [list ::Finish $ApplicationState] + +.CE +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIrc4\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +aes(n), blowfish(n), des(n) +.SH KEYWORDS +arcfour, data integrity, encryption, rc4, security, stream cipher +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/rcs/rcs.n Index: embedded/man/files/modules/rcs/rcs.n ================================================================== --- /dev/null +++ embedded/man/files/modules/rcs/rcs.n @@ -0,0 +1,520 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/rcs/rcs.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005, Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2005, Colin McCormack <coldstore@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "rcs" n 2.0.2 tcllib "RCS low level utilities" +.BS +.SH NAME +rcs \- RCS low level utilities +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBrcs ?0.1?\fR +.sp +\fB::rcs::text2dict\fR \fItext\fR +.sp +\fB::rcs::dict2text\fR \fIdict\fR +.sp +\fB::rcs::file2dict\fR \fIfilename\fR +.sp +\fB::rcs::dict2file\fR \fIfilename\fR \fIdict\fR +.sp +\fB::rcs::decodeRcsPatch\fR \fItext\fR +.sp +\fB::rcs::encodeRcsPatch\fR \fIpcmds\fR +.sp +\fB::rcs::applyRcsPatch\fR \fItext\fR \fIpcmds\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fIRevision Control System\fR, short \fIRCS\fR, 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 \fICVS\fR, etc. +.PP +This package \fIdoes not\fR implement RCS. +.PP +It only provides a number of low level commands which should be useful +in the implementation of any revision management system, namely: +.IP [1] +The conversion of texts into and out of a data structures which allow +the easy modification of such text by \fIpatches\fR, i.e. sequences +of instructions for the transformation of one text into an other. +.IP [2] +And the conversion of one particular format for patches, the so-called +\fIRCS patches\fR, into and out of data structures which allow +their easy application to texts. +.PP +.SH COMMANDS +.TP +\fB::rcs::text2dict\fR \fItext\fR +Converts the argument \fItext\fR 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 \fBTEXT DICT DATA STRUCTURE\fR. This command returns the +\fIcanonical\fR representation of the input. +.TP +\fB::rcs::dict2text\fR \fIdict\fR +This command provides the complementary operation to +\fB::rcs::text2dict\fR. It converts a dictionary in the form described +in section \fBTEXT DICT DATA STRUCTURE\fR back into a text and +returns that text as its result. The command does accept non-canonical +representations of the text as its input. +.TP +\fB::rcs::file2dict\fR \fIfilename\fR +This command is identical to \fB::rcs::text2dict\fR, except that it +reads the text to convert from the file with path \fIfilename\fR. The +file has to exist and must be readable as well. +.TP +\fB::rcs::dict2file\fR \fIfilename\fR \fIdict\fR +This command is identical to \fB::rcs::2dict2text\fR, except that it +stores the resulting text in the file with path \fIfilename\fR. The +file is created if it did not exist, and must be writable. The result +of the command is the empty string. +.TP +\fB::rcs::decodeRcsPatch\fR \fItext\fR +Converts the \fItext\fR argument into a patch command list (PCL) as +specified in the section \fBRCS PATCH COMMAND LIST\fR and +returns this list as its result. +It is assumed that the input text is in \fIdiff -n format\fR, also +known as \fIRCS patch\fR format, as specified in the section +\fBRCS PATCH FORMAT\fR. +Please note that the command ignores no-ops in the input, in other +words the resulting PCL contains only instructions doing something. +.TP +\fB::rcs::encodeRcsPatch\fR \fIpcmds\fR +This command provides the complementary operation to +\fB::rcs::decodeRcsPatch\fR. It convert a patch comand list (PCL) list +as specified in the section \fBRCS PATCH COMMAND LIST\fR back +into a text in \fBRCS PATCH FORMAT\fR and returns that text as its result. +.sp +Note that this command and \fB::rcs::decodeRcsPatch\fR 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. +.TP +\fB::rcs::applyRcsPatch\fR \fItext\fR \fIpcmds\fR +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. +.sp +To handle actual text use the commands \fB::rcs::text2dict\fR (or +equivalent) and \fB::rcs::decodeRcsPatch\fR to transform the inputs +into data structures acceptable to this command. Analogously use the +command \fB::rcs::dict2text\fR (or equivalent) to transform the +result of this command into actuall text as required. +.PP +.SH "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. +.PP +The text +.PP +.CS + +Hello World, +how are you ? +Fine, and you ? +.CE +.PP +for example can be represented by +.PP +.CS + +{{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}} +.CE +.PP +or +.PP +.CS + +{{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}} +.CE +.PP +or +.PP +.CS + +{{-1 {Hello World, +how are you ?}} {4 {Fine, and you ?}}} +.CE +.PP +The first dictionary is the \fIcanonical\fR representation of the +text, with line numbers starting at \fB1\fR, increasing in steps of +\fB1\fR and without gaps, and each value representing exactly one +physical line. +.PP +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. +.PP +The result of applying a patch to a text dictionary will in general +cause the dictionary to become non-canonical. +.SH "RCS PATCH FORMAT" +A \fIpatch\fR 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. +.PP +The text format for patches understood by this package is a very +simple one, known under the names \fIRCS patch\fR or +\fIdiff -n format\fR. +.PP +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. +.PP +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 \fIRCS patch\fR is always a command line. +.PP +The commands are: +.TP +"" +The empty line is a command which does nothing. +.TP +"a\fBstart\fR \fBn\fR" +A line starting with the character \fBa\fR is a command for the +addition of text to the output. It is followed by \fBn\fR lines of +text data. When applying the patch the data is added just between the +lines \fBstart\fR and \fBstart\fR+1. The same effect is had by +appending the data to the existing text on line \fBstart\fR. A +non-existing line \fBstart\fR is created. +.TP +"d\fBstart\fR \fBn\fR" +A line starting with the character \fBd\fR is a command for the +deletion of text from the output. When applied it deletes \fBn\fR +lines of text, and the first line deleted is at index \fBstart\fR. +.PP +Note that the line indices \fBstart\fR always refer to the text which +is transformed as it is in its original state, without taking the +precending changes into account. +.PP +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. +.PP +This is the format of results returned by the command +\fB::rcs::decodeRcsPatch\fR and accepted by the commands +\fB::rcs::encodeRcsPatch\fR and \fB::rcs::appplyRcsPatch\fR +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. +.PP +And example of a RCS patch is +.PP +.CS + +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! +.CE +.SH "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. +.PP +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. +.TP +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. +.TP +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. +.PP +.PP +This is the format returned by the patch decoder command and accepted +as input by the patch encoder and applicator commands. +.PP +An example for a patch command is shown below, it represents the +example RCS patch found in section \fBRCS PATCH FORMAT\fR. +.PP +.CS + +{{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!}}} +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIrcs\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +struct, textutil +.SH KEYWORDS +CVS, RCS, RCS patch, SCCS, diff -n format, patching, text conversion, text differences +.SH CATEGORY +Text processing +.SH COPYRIGHT +.nf +Copyright (c) 2005, Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2005, Colin McCormack <coldstore@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/report/report.n Index: embedded/man/files/modules/report/report.n ================================================================== --- /dev/null +++ embedded/man/files/modules/report/report.n @@ -0,0 +1,668 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/report/report.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "report" n 0.3.1 tcllib "Matrix reports" +.BS +.SH NAME +report \- Create and manipulate report objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBreport ?0.3.1?\fR +.sp +\fB::report::report\fR \fIreportName\fR \fIcolumns\fR ?\fBstyle\fR \fIstyle arg...\fR? +.sp +\fBreportName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fB::report::defstyle\fR \fIstyleName arguments script\fR +.sp +\fB::report::rmstyle\fR \fIstyleName\fR +.sp +\fB::report::stylearguments\fR \fIstyleName\fR +.sp +\fB::report::stylebody\fR \fIstyleName\fR +.sp +\fB::report::styles\fR +.sp +\fIreportName\fR \fBdestroy\fR +.sp +\fIreportName\fR \fItemplatecode\fR \fBdisable\fR|\fBenable\fR +.sp +\fIreportName\fR \fItemplatecode\fR \fBenabled\fR +.sp +\fIreportName\fR \fItemplatecode\fR \fBget\fR +.sp +\fIreportName\fR \fItemplatecode\fR \fBset\fR \fItemplatedata\fR +.sp +\fIreportName\fR \fBtcaption\fR ?\fIsize\fR? +.sp +\fIreportName\fR \fBbcaption\fR \fIsize\fR +.sp +\fIreportName\fR \fBsize\fR \fIcolumn\fR ?\fInumber\fR|\fBdyn\fR? +.sp +\fIreportName\fR \fBsizes\fR ?\fIsize-list\fR? +.sp +\fIreportName\fR \fBpad\fR \fIcolumn\fR ?\fBleft\fR|\fBright\fR|\fBboth\fR ?\fIpadstring\fR?? +.sp +\fIreportName\fR \fBjustify\fR \fIcolumn\fR ?\fBleft\fR|\fBright\fR|\fBcenter\fR? +.sp +\fIreportName\fR \fBprintmatrix\fR \fImatrix\fR +.sp +\fIreportName\fR \fBprintmatrix2channel\fR \fImatrix chan\fR +.sp +\fIreportName\fR \fBcolumns\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBREGIONS\fR and ten classes of +\fIlines\fR (various separator- and data-lines). See the following +section for more detailed explanations. +.TP +\fB::report::report\fR \fIreportName\fR \fIcolumns\fR ?\fBstyle\fR \fIstyle arg...\fR? +Creates a new report object for a report having \fIcolumns\fR columns +with an associated global Tcl command whose name is +\fIreportName\fR. This command may be used to invoke various +configuration operations on the report. It has the following general +form: +.RS +.TP +\fBreportName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. See section \fBREPORT METHODS\fR for more +explanations. If no \fBstyle\fR is specified the report will use +the builtin style \fBplain\fR as its default configuration. +.RE +.TP +\fB::report::defstyle\fR \fIstyleName arguments script\fR +Defines the new style \fIstyleName\fR. See section \fBSTYLES\fR +for more information. +.TP +\fB::report::rmstyle\fR \fIstyleName\fR +Deletes the style \fIstyleName\fR. 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. +.TP +\fB::report::stylearguments\fR \fIstyleName\fR +This introspection command returns the list of arguments associated +with the style \fIstyleName\fR. +.TP +\fB::report::stylebody\fR \fIstyleName\fR +This introspection command returns the script associated with the +style \fIstyleName\fR. +.TP +\fB::report::styles\fR +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 +\fBplain\fR, followed by the first style defined by the user, and +so on. +.PP +.SH REGIONS +.PP +The three regions are the \fItop caption\fR, +\fIdata area\fR and \fIbottom caption\fR. 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. +.SH LINES +.PP +\fBTEMPLATES\fR 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. +.PP +Note that the data-lines in a report and the rows in the matrix the +report was generated from are \fInot\fR in a 1:1 relationship if +any row in the matrix has a height greater than one. +.PP +The different kinds of lines and the codes used by the report methods +to address them are: +.TP +\fBtop\fR +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. +.TP +\fBtopdatasep\fR +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. +.TP +\fBtopcapsep\fR +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. +.TP +\fBdatasep\fR +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. +.TP +\fBbotcapsep\fR +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. +.TP +\fBbotdatasep\fR +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. +.TP +\fBbottom\fR +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. +.TP +\fBtopdata\fR +This line defines the format of data lines in the top caption region +of the report. +.TP +\fBdata\fR +This line defines the format of data lines in the data region of the +report. +.TP +\fBbotdata\fR +This line defines the format of data lines in the bottom caption +region of the report. +.PP +.SH TEMPLATES +.PP +Each template is a list of strings used to format the line it is +associated with. For a report containing \fBn\fR columns a template +for a data line has to contain "\fBn\fR+1" items and a template for a +separator line "2*\fBn\fR+1" items. +.PP +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. +.PP +\fINote\fR 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 \fBk\fR +("1",...,"\fBn\fR-2") separates the information in the columns +"\fBk\fR-1" and "\fBk\fR". +.PP +The items in a separator template having an even-numbered index +("0","2",...) specify the column separators. The item at index +"2*\fBk\fR" ("0","2",...,"2*\fBn\fR") corresponds to the items at +index "\fBk\fR" in the data templates. +.PP +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*\fBk\fR+1" +("1","3",...,"2*\fBn\fR+1") corresponds to column "\fBk\fR". 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. +.SH STYLES +.PP +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. +.PP +The command to define styles is \fB::report::defstyle\fR. Its last +argument is the tcl \fBscript\fR performing the actual +reconfiguration of the report object to obtain the requested style. +.PP +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 +\fBarguments\fR declared here are available in the \fBscript\fR as +variables. When calling the command of a previously declared style all +the arguments expected by it have to be defined in the call. +.SH "REPORT METHODS" +.PP +The following commands are possible for report objects: +.TP +\fIreportName\fR \fBdestroy\fR +Destroys the report, including its storage space and associated +command. +.TP +\fIreportName\fR \fItemplatecode\fR \fBdisable\fR|\fBenable\fR +Enables or disables the usage of the template addressed by the +\fItemplatecode\fR. Only the codes for separator lines are allowed +here. It is not possible to enable or disable data lines. +.sp +Enabling a template causes the report to check all used templates for +inconsistencies in the definition of the vertical lines (See section +\fBTEMPLATES\fR). +.TP +\fIreportName\fR \fItemplatecode\fR \fBenabled\fR +Returns the whether the template addressed by the \fItemplatecode\fR +is currently enabled or not. +.TP +\fIreportName\fR \fItemplatecode\fR \fBget\fR +Returns the template currently associated with the kind of line +addressed by the \fItemplatecode\fR. All known templatecodes are +allowed here. +.TP +\fIreportName\fR \fItemplatecode\fR \fBset\fR \fItemplatedata\fR +Sets the template associated with the kind of line addressed by the +\fItemplatecode\fR to the new value in \fItemplatedata\fR. See section +\fBTEMPLATES\fR for constraints on the length of templates. +.TP +\fIreportName\fR \fBtcaption\fR ?\fIsize\fR? +Specifies the \fIsize\fR 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 \fIsize\fR is specified the +command will return the current size instead. +.sp +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 \fBTEMPLATES\fR). +.TP +\fIreportName\fR \fBbcaption\fR \fIsize\fR +Specifies the \fIsize\fR 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 \fIsize\fR is specified the +command will return the current size instead. +.sp +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 \fBTEMPLATES\fR). +.TP +\fIreportName\fR \fBsize\fR \fIcolumn\fR ?\fInumber\fR|\fBdyn\fR? +Specifies the size of the \fIcolumn\fR in the output. The value +\fBdyn\fR 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 \fInumber\fR is used instead of +\fBdyn\fR it means that the column has a width of that many +characters (padding excluded). Only numbers greater than zero are +allowed here. +.sp +If no size specification is given the command will return the current +size of the \fIcolumn\fR instead. +.TP +\fIreportName\fR \fBsizes\fR ?\fIsize-list\fR? +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. +.sp +If no \fIsize-list\fR is specified the command will return a list +containing the currently set sizes instead. +.TP +\fIreportName\fR \fBpad\fR \fIcolumn\fR ?\fBleft\fR|\fBright\fR|\fBboth\fR ?\fIpadstring\fR?? +This method allows the user to specify padding on the left, right or +both sides of a \fIcolumn\fR. If the \fIpadstring\fR is not specified +it defaults to a single space character. \fINote\fR: An alternative +way of specifying the padding is to use vertical separator strings +longer than one character in the templates (See section +\fBTEMPLATES\fR). +.sp +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. +.TP +\fIreportName\fR \fBjustify\fR \fIcolumn\fR ?\fBleft\fR|\fBright\fR|\fBcenter\fR? +Declares how the cell values for a \fIcolumn\fR are filled into the +report given the specified size of a column in the report. +.sp +For \fBleft\fR and \fBright\fR 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 \fBcenter\fR 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. +.sp +For a value longer than the width of the column the value is cut at +the named edge. This means for \fBleft\fR justification that the +\fItail\fR (i.e. the \fBright\fR part) of the value is made +visible in the output. For \fBcenter\fR 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. +.sp +If no justification was specified the command will return the current +justification for the column instead. +.TP +\fIreportName\fR \fBprintmatrix\fR \fImatrix\fR +Formats the \fImatrix\fR 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. +.TP +\fIreportName\fR \fBprintmatrix2channel\fR \fImatrix chan\fR +Formats the \fImatrix\fR according to the configuration of the report +and writes the result into the channel \fIchan\fR. 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. +.TP +\fIreportName\fR \fBcolumns\fR +Returns the number of columns in the report. +.PP +.PP +The methods \fBsize\fR, \fBpad\fR and \fBjustify\fR 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 \fBlindex\fR command. The +allowed range for indices is +"0,...,[\fBreportName\fR columns]-1". +.SH EXAMPLES +.PP +Our examples define some generally useful report styles. +.PP +A simple table with lines surrounding all information and vertical +separators, but without internal horizontal separators. +.PP +.CS + + + ::report::defstyle simpletable {} { + data set [split "[string repeat "| " [columns]]|"] + top set [split "[string repeat "+ - " [columns]]+"] + bottom set [top get] + top enable + bottom enable + } + +.CE +.PP +An extension of a \fBsimpletable\fR, see above, with a title area. +.PP +.CS + + + ::report::defstyle captionedtable {{n 1}} { + simpletable + topdata set [data get] + topcapsep set [top get] + topcapsep enable + tcaption $n + } + +.CE +.PP +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. +.PP +.CS + + + % ::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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIreport\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +matrix, report, table +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/rest/rest.n Index: embedded/man/files/modules/rest/rest.n ================================================================== --- /dev/null +++ embedded/man/files/modules/rest/rest.n @@ -0,0 +1,496 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/rest/rest.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "rest" n 1.0 tcllib "A framework for RESTful web services" +.BS +.SH NAME +rest \- define REST web APIs and call them inline or asychronously +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBrest ?1.0?\fR +.sp +\fB::rest::simple\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::get\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::post\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::head\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::put\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::delete\fR \fIurl\fR \fIquery\fR ?config? ?body? +.sp +\fB::rest::save\fR \fIname\fR \fIfile\fR +.sp +\fB::rest::describe\fR \fIname\fR +.sp +\fB::rest::parameters\fR \fIurl\fR ?args? +.sp +\fB::rest::parse_opts\fR \fIstatic\fR \fIrequired\fR \fIoptional\fR \fIstring\fR +.sp +\fB::rest::substitute\fR \fIstring\fR ?var? +.sp +\fB::rest::create_interface\fR \fIname\fR +.sp +describe +.sp +uplevel token token +.sp +upvar body body +.sp +uplevel token token +.sp +uplevel token token +.sp +.BE +.SH DESCRIPTION +.PP +There are 2 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 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, a simple call is easier and quicker to implement but less featureful. It takes the url and a few options on 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 http method procedures and then check or process the returned data yourself +.TP +\fB::rest::simple\fR \fIurl\fR \fIquery\fR ?config? ?body? +.TP +\fB::rest::get\fR \fIurl\fR \fIquery\fR ?config? ?body? +.TP +\fB::rest::post\fR \fIurl\fR \fIquery\fR ?config? ?body? +.TP +\fB::rest::head\fR \fIurl\fR \fIquery\fR ?config? ?body? +.TP +\fB::rest::put\fR \fIurl\fR \fIquery\fR ?config? ?body? +.TP +\fB::rest::delete\fR \fIurl\fR \fIquery\fR ?config? ?body? +.PP +The above commands are all equivalent except for the http method used. If you use \fBsimple\fR then the method should be specified as an option in the ?config? dict, otherwise it defaults to \fBget\fR. If a body is needed then the config dict must be present, however it may be empty. +.CS + + + 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] + +.CE +.CS + + + set res [rest::simple http://twitter.com/statuses/update.json [list status $text] { + method post + auth {basic user password} + format json + } + ] + +.CE +the options supported in the config dict are as follows +headers +cookie +auth +format +method +content-type +Interface usage +An interface to a REST API consists of a series of definitions of REST calls contained in an array. The array name becomes a namespace containing the defined commands. Each array element defines the name of the call and takes the form of a dict, aka key/value pairs. These keys are the defined configuration options below. +After creating the definitions simply call rest::create_interface on the array to create the commands. +.CS + + +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] + +.CE +::${name}::basic_auth \fIu\fR \fIp\fR +::${name}::set_static_args ?args?] +.TP +\fB::rest::save\fR \fIname\fR \fIfile\fR +saves a copy of the dynamically created procs to a file for later loading +.TP +\fB::rest::describe\fR \fIname\fR +print a description of defined api calls +.TP +\fB::rest::parameters\fR \fIurl\fR ?args? +parse a url query string into a dict +.TP +\fB::rest::parse_opts\fR \fIstatic\fR \fIrequired\fR \fIoptional\fR \fIstring\fR +.TP +\fB::rest::substitute\fR \fIstring\fR ?var? +take a string and substitute real values for any option identifiers +.TP +\fB::rest::create_interface\fR \fIname\fR +TOKENS +the value is substituted into the url at call time. tokens in the form of %name:default_value% will be an optional argument with a default value. +url +the target of the http request +description +a string which describes the call. used only for +.TP +describe +body +indicates if arguments are required for the request body or not. should +be one of none, optional, required, argument or mime_multipart. default is optional. +if \fBargument\fR is used then the option is parsed as a list where the second value is the name +of a option. the body will then be used as the value for that option. +if the value is \fBmime_multipart\fR then the body is required and interpreted as each argument +representing one part of a mime multipart document. each argument should be a 2 item list with the first being +a list of header keys and values, and the second being the mime part body. +.CS + + +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 + +.CE +.CS + + +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] + +.CE +.IP +method +The HTTP method to call on the url. The default is GET. +copy +this copies the definition of a previously defined call. after copying you can override selected options by defining them again. +unset +removes the named option. useful when using copy of another definition. +headers +the value must be another dict containing header fields and their values. The default is to not add any additional headers. +content-type +Specifies the content type for the request data. +req_args +a list of the required arguments. names ending in a colon will require a value. +opt_args +arguments that may be present but are not required. +static_args +arguments that are always the same. no sense in troubling the user with these. A leading - is allowed but not required to maintain consistancy with the command line. +auth +should be one of basic or sign. if basic is used you can configure basic auth with the proc auth_basic which takes 2 arguments, the username and password. +if sign is specified then the value must be a list with the second element being the name of a proc which will be called to perform the request signing. +.CS + + +set delicious(updated) { + url https://api.del.icio.us/v1/posts/update + auth basic +} + +rest::create_interface flickr + +flickr::basic_auth username password + +.CE +.CS + + +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 +} + +.CE +.IP +callback +If this option is present then the method will be created as an async call. An async call will return immediately with the value of the http token. The event loop must be active to use this option. The value of this option is the name of a proc which is invoked when the HTTP call is complete. The proc receives three arguments, the name of the calling procedure, the status of the result (one of OK or ERROR), and the data associated with the result. +the http request header is available via +.TP +uplevel token token +cookie +a list of cookies to be passed in the http header. this is just a shortcut to the headers option +input_transform +commands which take the variable $query and transform it in some manner before returning a new value. return value must be a dict which will be passed to http::formatQuery +the request body is accessible via +.TP +upvar body body +format or result +defines the format of the returned data. should be one of discard, raw, json, xml, or tdom. the default is auto which should auto detect between xml and json. rss is formated as +a special case of xml. +pre_transform +this value takes the form of a proc which should perform some action on $result and return a value. it is run on the result before the output (xml/json/etc) transformation is done. +the http request header is available via +.TP +uplevel token token +result +may have the value xml, json, tdom, raw, or auto. the default is auto and should auto detect json or xml results and transform them into a tcl list. this is here if you want to specify it explicitly. +post_transform +this value takes the form of a proc which should perform some action on $result and return a value. it is run on the result after the output transformation but before returning the value to the calling procedure. +the http request header is available via +.TP +uplevel token token +check_result +this value should be a list of 2 expressions either of which may be empty. the first expression is checks the OK condition, it must return true when the result is satisfactory. the second expression is the error condition, it must return false unless there is an error. +.PP +.SH INCLUDED +functional but incomplete implementations are included for the following services: +flickr +twitter +yahoo boss +yahoo weather +google calendar +facebook +del.icio.us +read the file or source it and use \fBdescribe\fR for more information. also see the +developers documentation on the respective sites. ADDED embedded/man/files/modules/ripemd/ripemd128.n Index: embedded/man/files/modules/ripemd/ripemd128.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ripemd/ripemd128.n @@ -0,0 +1,415 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ripemd/ripemd128.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ripemd128" n 1.0.3 tcllib "RIPEMD Message-Digest Algorithm" +.BS +.SH NAME +ripemd128 \- RIPEMD-128 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBripemd128 ?1.0.3?\fR +.sp +\fB::ripemd::ripemd128\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::ripemd::hmac128\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::ripemd::RIPEMD128Init\fR +.sp +\fB::ripemd::RIPEMD128Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::ripemd::RIPEMD128Final\fR \fItoken\fR +.sp +\fB::ripemd::RIPEHMAC128Init\fR \fIkey\fR +.sp +\fB::ripemd::RIPEHMAC128Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::ripemd::RIPEHMAC128Final\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +This package will use \fBTrf\fR to +accelerate the digest computation if available. In +the absence of an accelerator package the pure-Tcl implementation will +be used. +.SH COMMANDS +.TP +\fB::ripemd::ripemd128\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate the RIPEMD-128 digest of the data given in string. This is +returned as a binary string by default. Giving the \fI-hex\fR option +will return a hexadecimal encoded version of the digest. +.sp +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 +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::ripemd::hmac128\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 \fI-key\fR are as for the \fB::ripemd::ripemd128\fR command. +.PP +.SH "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 \fBRIPEMD128Init\fR to obtain a token and then call +\fBRIPEMD128Update\fR as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +\fBRIPEMD128Final\fR. An equivalent set of functions gives you a keyed +digest (HMAC). +.PP +If you have \fBcritcl\fR and have built the \fBtcllibc\fR +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. +.TP +\fB::ripemd::RIPEMD128Init\fR +Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the +remaining functions. +.TP +\fB::ripemd::RIPEMD128Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fIRIPEMD128Update $token "abcd"\fR is equivalent to calling +\fIRIPEMD128Update $token "ab"\fR followed by +\fIRIPEMD128Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::ripemd::RIPEMD128Final\fR \fItoken\fR +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. +.TP +\fB::ripemd::RIPEHMAC128Init\fR \fIkey\fR +This is equivalent to the \fB::ripemd::RIPEMD128Init\fR command +except that it requires the key that will be included in the HMAC. +.TP +\fB::ripemd::RIPEHMAC128Update\fR \fItoken\fR \fIdata\fR +.TP +\fB::ripemd::RIPEHMAC128Final\fR \fItoken\fR +These commands are identical to the RIPEMD128 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% ripemd::ripemd128 -hex "Tcl does RIPEMD-128" +3cab177bae65205d81e7978f63556c63 + +.CE +.CS + + +% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128" +b359dc5971a05beea0be7b106b30e389 + +.CE +.CS + + +% 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 + +.CE +.SH REFERENCES +.IP [1] +H. Dobbertin, A. Bosselaers, B. Preneel, +"RIPEMD-160, a strengthened version of RIPEMD" +\fIhttp://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf\fR +.IP [2] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [3] +Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes +and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 +Proceedings, pages 303-311, Springer-Verlag, 1991. +.IP [4] +Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology +vol 11 (4), pp. 253-271 (1998) +.IP [5] +Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and +RSA Data Security, Inc, April 1992. +(\fIhttp://www.rfc-editor.org/rfc/rfc1321.txt\fR) +.IP [6] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIripemd\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md4, md5, ripemd160, sha1 +.SH KEYWORDS +RIPEMD, hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/ripemd/ripemd160.n Index: embedded/man/files/modules/ripemd/ripemd160.n ================================================================== --- /dev/null +++ embedded/man/files/modules/ripemd/ripemd160.n @@ -0,0 +1,402 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/ripemd/ripemd160.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "ripemd160" n 1.0.3 tcllib "RIPEMD Message-Digest Algorithm" +.BS +.SH NAME +ripemd160 \- RIPEMD-160 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBripemd160 ?1.0.3?\fR +.sp +\fB::ripemd::ripemd160\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::ripemd::hmac160\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::ripemd::RIPEMD160Init\fR +.sp +\fB::ripemd::RIPEMD160Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::ripemd::RIPEMD160Final\fR \fItoken\fR +.sp +\fB::ripemd::RIPEHMAC160Init\fR \fIkey\fR +.sp +\fB::ripemd::RIPEHMAC160Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::ripemd::RIPEHMAC160Final\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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). +.PP +This package will use \fBcryptkit\fR or \fBTrf\fR to +accelerate the digest computation if either package is available. In +the absence of an accelerator package the pure-Tcl implementation will +be used. +.SH COMMANDS +.TP +\fB::ripemd::ripemd160\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Calculate the RIPEMD-160 digest of the data given in string. This is +returned as a binary string by default. Giving the \fI-hex\fR option +will return a hexadecimal encoded version of the digest. +.sp +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 +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::ripemd::hmac160\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 \fI-key\fR are as for the \fB::ripemd::ripemd160\fR command. +.PP +.SH "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 \fBRIPEMD160Init\fR to obtain a token and then call +\fBRIPEMD160Update\fR as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +\fBRIPEMD160Final\fR. An equivalent set of functions gives you a keyed +digest (HMAC). +.TP +\fB::ripemd::RIPEMD160Init\fR +Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the +remaining functions. +.TP +\fB::ripemd::RIPEMD160Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fIRIPEMD160Update $token "abcd"\fR is equivalent to calling +\fIRIPEMD160Update $token "ab"\fR followed by +\fIRIPEMD160Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::ripemd::RIPEMD160Final\fR \fItoken\fR +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. +.TP +\fB::ripemd::RIPEHMAC160Init\fR \fIkey\fR +This is equivalent to the \fB::ripemd::RIPEMD160Init\fR command +except that it requires the key that will be included in the HMAC. +.TP +\fB::ripemd::RIPEHMAC160Update\fR \fItoken\fR \fIdata\fR +.TP +\fB::ripemd::RIPEHMAC160Final\fR \fItoken\fR +These commands are identical to the RIPEMD160 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% ripemd::ripemd160 -hex "Tcl does RIPEMD-160" +0829dea75a1a7074c702896723fe37763481a0a7 + +.CE +.CS + + +% ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160" +bf0c927231733686731dddb470b64a9c23f7f53b + +.CE +.CS + + +% 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 + +.CE +.SH REFERENCES +.IP [1] +H. Dobbertin, A. Bosselaers, B. Preneel, +"RIPEMD-160, a strengthened version of RIPEMD" +\fIhttp://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf\fR +.IP [2] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [3] +Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes +and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 +Proceedings, pages 303-311, Springer-Verlag, 1991. +.IP [4] +Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology +vol 11 (4), pp. 253-271 (1998) +.IP [5] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIripemd\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md4, md5, ripemd128, sha1 +.SH KEYWORDS +RIPEMD, hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/sasl/sasl.n Index: embedded/man/files/modules/sasl/sasl.n ================================================================== --- /dev/null +++ embedded/man/files/modules/sasl/sasl.n @@ -0,0 +1,539 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/sasl/sasl.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "SASL" n 1.3.0 tcllib "Simple Authentication and Security Layer (SASL)" +.BS +.SH NAME +SASL \- Implementation of SASL mechanisms for Tcl +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBSASL ?1.3?\fR +.sp +\fB::SASL::new\fR \fIoption value ?...?\fR +.sp +\fB::SASL::configure\fR \fIoption value\fR ?\fI...\fR? +.sp +\fB::SASL::step\fR \fIcontext\fR \fIchallenge\fR ?\fI...\fR? +.sp +\fB::SASL::response\fR \fIcontext\fR +.sp +\fB::SASL::reset\fR \fIcontext\fR +.sp +\fB::SASL::cleanup\fR \fIcontext\fR +.sp +\fB::SASL::mechanisms\fR ?\fItype\fR? ?\fIminimum\fR? +.sp +\fB::SASL::register\fR \fImechanism\fR \fIpreference\fR \fIclientproc\fR ?\fIserverproc\fR? +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBMECHANISMS\fR for the set of available SASL +mechanisms provided with tcllib. +.PP +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 \fBCALLBACK PROCEDURE\fR for details of this +procedure. +.SH COMMANDS +.TP +\fB::SASL::new\fR \fIoption value ?...?\fR +Contruct a new SASL context. See \fBOPTIONS\fR for details of the +possible options to this command. A context token is required for most +of the SASL procedures. +.TP +\fB::SASL::configure\fR \fIoption value\fR ?\fI...\fR? +Modify and inspect the SASL context option. See \fBOPTIONS\fR for +further details. +.TP +\fB::SASL::step\fR \fIcontext\fR \fIchallenge\fR ?\fI...\fR? +This is the core procedure for using the SASL framework. The +\fBstep\fR 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. +.TP +\fB::SASL::response\fR \fIcontext\fR +Returns the next response string that should be sent to the server. +.TP +\fB::SASL::reset\fR \fIcontext\fR +Re-initialize the SASL context. Discards any internal state and +permits the token to be reused. +.TP +\fB::SASL::cleanup\fR \fIcontext\fR +Release all resources associated with the SASL context. The context +token may not be used again after this procedure has been called. +.TP +\fB::SASL::mechanisms\fR ?\fItype\fR? ?\fIminimum\fR? +Returns a list of all the available SASL mechanisms. The list is +sorted by the mechanism preference value (see \fBregister\fR) with the +preferred mechanisms and the head of the list. Any mechanism with a +preference value less than the\fIminimum\fR (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). +.sp +The \fItype\fR parameter +may be one of \fIclient\fR or \fIserver\fR and defaults to \fIclient\fR. +Only mechanisms that have an implementation matching the \fItype\fR are +returned (this permits servers to correctly declare support only for +mechanisms that actually provide a server implementation). +.TP +\fB::SASL::register\fR \fImechanism\fR \fIpreference\fR \fIclientproc\fR ?\fIserverproc\fR? +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 \fBmechanisms\fR command. Higher values +indicate a preferred mechanism. If the mechanism is already registered +then the recorded values are updated. +.PP +.SH OPTIONS +.TP +\fB-callback\fR +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 +\fBEXAMPLES\fR. +.TP +\fB-mechanism\fR +Set the SASL mechanism to be used. See \fBmechanisms\fR for a list of +supported authentication mechanisms. +.TP +\fB-service\fR +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 \fB-type\fR 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. +.TP +\fB-server\fR +This option is used to set the server name used in SASL challenges +when operating as a SASL server. +.TP +\fB-type\fR +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 \fBstep\fR to issue the next +challenge. A new context must be created for each incoming client +connection when in server mode. +.PP +.SH "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. +.PP +In all cases a single response string should be returned. +.TP +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. +.TP +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. +.TP +password +The callback procedure should return the password that matches the +authentication identity as used within the current realm. +.sp +For server mechanisms the password callback should always be called with +the authentication identity and the realm as the first two parameters. +.TP +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. +.TP +hostname +Returns the client host name - typically [info host]. +.PP +.SH MECHANISMS +.TP +ANONYMOUS +As used in FTP this mechanism only passes an email address for +authentication. The ANONYMOUS mechanism is specified in [2]. +.TP +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. +.TP +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. +.TP +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]. +.TP +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]. +.TP +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 +\fBotp\fR package from tcllib and one or more of the cryptographic +digest packages (md5 or sha-1 are the most commonly used). +.TP +NTLM +This is a proprietary protocol developed by Microsoft [5] and is +in common use for authenticating users in a Windows network +environment. NTLM uses DES encryption and MD4 digests of the users +password to authenticate a connection. Certain weaknesses have been +found in NTLM and thus there are a number of versions of the protocol. +As this mechanism has additional dependencies it is made available as +a separate sub-package. To enable this mechanism your application must +load the SASL::NTLM package. +.TP +X-GOOGLE-TOKEN +This is a proprietary protocol developed by Google and used for +authenticating users for the Google Talk service. This mechanism makes +a pair of HTTP requests over an SSL channel and so this mechanism +depends upon the availability of the tls and http packages. To enable +this mechanism your application must load the SASL::XGoogleToken package. +In addition you are recommended to make use of the autoproxy package to +handle HTTP proxies reasonably transparently. +.PP +.SH 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 \fBstep\fR command is called, the last server +response should be provided as the command argument so that the SASL +mechanism can take appropriate action. +.CS + + +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 +} + +.CE +.SH REFERENCES +.IP [1] +Myers, J. "Simple Authentication and Security Layer (SASL)", +RFC 2222, October 1997. +(\fIhttp://www.ietf.org/rfc/rfc2222.txt\fR) +.IP [2] +Newman, C. "Anonymous SASL Mechanism", +RFC 2245, November 1997. +(\fIhttp://www.ietf.org/rfc/rfc2245.txt\fR) +.IP [3] +Leach, P., Newman, C. "Using Digest Authentication as a SASL +Mechanism", RFC 2831, May 2000, +(\fIhttp://www.ietf.org/rfc/rfc2831.txt\fR) +.IP [4] +Klensin, J., Catoe, R. and Krumviede, P., +"IMAP/POP AUTHorize Extension for Simple Challenge/Response" +RFC 2195, September 1997. +(\fIhttp://www.ietf.org/rfc/rfc2195.txt\fR) +.IP [5] +No official specification is available. However, +\fIhttp://davenport.sourceforge.net/ntlm.html\fR provides a good +description. +.IP [6] +Haller, N. et al., "A One-Time Password System", +RFC 2289, February 1998, +(\fIhttp://www.ieft.org/rfc/rfc2289.txt\fR) +.PP +.SH AUTHORS +Pat Thoyts +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsasl\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +SASL, authentication +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/sha1/sha1.n Index: embedded/man/files/modules/sha1/sha1.n ================================================================== --- /dev/null +++ embedded/man/files/modules/sha1/sha1.n @@ -0,0 +1,407 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/sha1/sha1.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "sha1" n 2.0.3 tcllib "SHA-x Message-Digest Algorithm" +.BS +.SH NAME +sha1 \- SHA1 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBsha1 ?2.0.3?\fR +.sp +\fB::sha1::sha1\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::sha1::hmac\fR \fIkey\fR \fIstring\fR +.sp +\fB::sha1::hmac\fR ?\fI-hex|-bin\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::sha1::SHA1Init\fR +.sp +\fB::sha1::SHA1Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::sha1::SHA1Final\fR \fItoken\fR +.sp +\fB::sha1::HMACInit\fR \fIkey\fR +.sp +\fB::sha1::HMACUpdate\fR \fItoken\fR \fIdata\fR +.sp +\fB::sha1::HMACFinal\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA1 as the +message-digest. +.SH COMMANDS +.TP +\fB::sha1::sha1\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 \fI-bin\fR. +.sp +The data to be hashed can be specified either as a string argument to +the \fBsha1\fR command, or as a filename or a pre-opened channel. If the +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. \fINOTE\fR use of the channel or filename +options results in the internal use of \fBvwait\fR. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below). +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::sha1::hmac\fR \fIkey\fR \fIstring\fR +.TP +\fB::sha1::hmac\fR ?\fI-hex|-bin\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 \fI-key\fR are as +for the \fB::sha1::sha1\fR command. +.PP +.SH "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 \fBSHA1Init\fR to obtain a token and then call +\fBSHA1Update\fR as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +\fBSHA1Final\fR. An equivalent set of functions gives you a keyed digest +(HMAC). +.PP +If you have \fBcritcl\fR and have built the \fBtcllibc\fR package +then the implementation of the hashing function will be performed by compiled +code. Failing that if you have the \fBTrf\fR package then this can +be used otherwise there is a pure-tcl equivalent. The programming +interface remains the same in all cases. +.TP +\fB::sha1::SHA1Init\fR +Begins a new SHA1 hash. Returns a token ID that must be used for the +remaining functions. +.TP +\fB::sha1::SHA1Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fISHA1Update $token "abcd"\fR is equivalent to calling +\fISHA1Update $token "ab"\fR followed by +\fISHA1Update $token "cb"\fR. See \fBEXAMPLES\fR. +.TP +\fB::sha1::SHA1Final\fR \fItoken\fR +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. +.TP +\fB::sha1::HMACInit\fR \fIkey\fR +This is equivalent to the \fB::sha1::SHA1Init\fR command except that +it requires the key that will be included in the HMAC. +.TP +\fB::sha1::HMACUpdate\fR \fItoken\fR \fIdata\fR +.TP +\fB::sha1::HMACFinal\fR \fItoken\fR +These commands are identical to the SHA1 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% sha1::sha1 "Tcl does SHA1" +285a6a91c45a9066bf39fcf24425796ef0b2a8bf + +.CE +.CS + + +% sha1::hmac Sekret "Tcl does SHA1" +ae6251fa51b95b18cba2be95eb031d07475ff03c + +.CE +.CS + + +% set tok [sha1::SHA1Init] +::sha1::1 +% sha1::SHA1Update $tok "Tcl " +% sha1::SHA1Update $tok "does " +% sha1::SHA1Update $tok "SHA1" +% sha1::Hex [sha1::SHA1Final $tok] +285a6a91c45a9066bf39fcf24425796ef0b2a8bf + +.CE +.SH REFERENCES +.IP [1] +"Secure Hash Standard", National Institute of Standards +and Technology, U.S. Department Of Commerce, April 1995. +(\fIhttp://www.itl.nist.gov/fipspubs/fip180-1.htm\fR) +.IP [2] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [3] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsha1\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md4, md5, ripemd128, ripemd160 +.SH KEYWORDS +FIPS 180-1, hashing, message-digest, rfc 2104, security, sha1 +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/sha1/sha256.n Index: embedded/man/files/modules/sha1/sha256.n ================================================================== --- /dev/null +++ embedded/man/files/modules/sha1/sha256.n @@ -0,0 +1,420 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/sha1/sha256.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008, Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "sha256" n 1.0.3 tcllib "SHA-x Message-Digest Algorithm" +.BS +.SH NAME +sha256 \- SHA256 Message-Digest Algorithm +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBsha256 ?1.0.3?\fR +.sp +\fB::sha2::sha256\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::sha2::sha224\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::sha2::hmac\fR \fIkey\fR \fIstring\fR +.sp +\fB::sha2::hmac\fR ?\fI-hex|-bin\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +.sp +\fB::sha2::SHA256Init\fR +.sp +\fB::sha2::SHA224Init\fR +.sp +\fB::sha2::SHA256Update\fR \fItoken\fR \fIdata\fR +.sp +\fB::sha2::SHA256Final\fR \fItoken\fR +.sp +\fB::sha2::SHA224Final\fR \fItoken\fR +.sp +\fB::sha2::HMACInit\fR \fIkey\fR +.sp +\fB::sha2::HMACUpdate\fR \fItoken\fR \fIdata\fR +.sp +\fB::sha2::HMACFinal\fR \fItoken\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA256 as the +message-digest. +.SH COMMANDS +.TP +\fB::sha2::sha256\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 \fI-bin\fR. +.sp +The data to be hashed can be specified either as a string argument to +the \fBsha256\fR command, or as a filename or a pre-opened channel. If the +\fI-filename\fR argument is given then the file is opened, the data read +and hashed and the file is closed. If the \fI-channel\fR argument is +given then data is read from the channel until the end of file. The +channel is not closed. \fINOTE\fR use of the channel or filename +options results in the internal use of \fBvwait\fR. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below). +.sp +Only one of \fI-file\fR, \fI-channel\fR or \fIstring\fR should be given. +.TP +\fB::sha2::sha224\fR ?\fI-hex|-bin\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +Like \fB::sha2::sha256\fR, except that the SHA224 digest is returned. +.TP +\fB::sha2::hmac\fR \fIkey\fR \fIstring\fR +.TP +\fB::sha2::hmac\fR ?\fI-hex|-bin\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] +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 +\fI-key\fR are as for the \fB::sha2::sha256\fR command. +.PP +.SH "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 \fBSHA256Init\fR to obtain a +token and then call \fBSHA256Update\fR as many times as required to +add data to the hash. To release any resources and obtain the hash +value, you then call \fBSHA256Final\fR. An equivalent set of +functions gives you a keyed digest (HMAC). +.PP +If you have \fBcritcl\fR and have built the \fBtcllibc\fR +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. +.TP +\fB::sha2::SHA256Init\fR +.TP +\fB::sha2::SHA224Init\fR +Begins a new SHA256/SHA224 hash. Returns a token ID that must be used +for the remaining functions. +.TP +\fB::sha2::SHA256Update\fR \fItoken\fR \fIdata\fR +Add data to the hash identified by token. Calling +\fISHA256Update $token "abcd"\fR is equivalent to calling +\fISHA256Update $token "ab"\fR followed by +\fISHA256Update $token "cb"\fR. See \fBEXAMPLES\fR. +Note that this command is used for both SHA256 and SHA224. Only the +initialization and finalization commands of both hashes differ. +.TP +\fB::sha2::SHA256Final\fR \fItoken\fR +.TP +\fB::sha2::SHA224Final\fR \fItoken\fR +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. +.TP +\fB::sha2::HMACInit\fR \fIkey\fR +This is equivalent to the \fB::sha2::SHA256Init\fR command except +that it requires the key that will be included in the HMAC. +.TP +\fB::sha2::HMACUpdate\fR \fItoken\fR \fIdata\fR +.TP +\fB::sha2::HMACFinal\fR \fItoken\fR +These commands are identical to the SHA256 equivalent commands. +.PP +.SH EXAMPLES +.CS + + +% sha2::sha256 "Tcl does SHA256" +0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 + +.CE +.CS + + +% sha2::hmac Sekret "Tcl does SHA256" +4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 + +.CE +.CS + + +% set tok [sha2::SHA256Init] +::sha2::1 +% sha2::SHA256Update $tok "Tcl " +% sha2::SHA256Update $tok "does " +% sha2::SHA256Update $tok "SHA256" +% sha2::Hex [sha2::SHA256Final $tok] +0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 + +.CE +.SH REFERENCES +.IP [1] +"Secure Hash Standard", National Institute of Standards +and Technology, U.S. Department Of Commerce, April 1995. +(\fIhttp://www.itl.nist.gov/fipspubs/fip180-1.htm\fR) +.IP [2] +Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, +April 1992. (\fIhttp://www.rfc-editor.org/rfc/rfc1320.txt\fR) +.IP [3] +Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for +Message Authentication", RFC 2104, February 1997. +(\fIhttp://www.rfc-editor.org/rfc/rfc2104.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsha1\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +md4, md5, ripemd128, ripemd160, sha1 +.SH KEYWORDS +FIPS 180-1, hashing, message-digest, rfc 2104, security, sha256 +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2008, Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/simulation/annealing.n Index: embedded/man/files/modules/simulation/annealing.n ================================================================== --- /dev/null +++ embedded/man/files/modules/simulation/annealing.n @@ -0,0 +1,480 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/simulation/annealing.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "simulation::annealing" n 0.2 tcllib "Tcl Simulation Tools" +.BS +.SH NAME +simulation::annealing \- Simulated annealing +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBsimulation::annealing 0.2\fR +.sp +\fB::simulation::annealing::getOption\fR \fIkeyword\fR +.sp +\fB::simulation::annealing::hasOption\fR \fIkeyword\fR +.sp +\fB::simulation::annealing::setOption\fR \fIkeyword\fR \fIvalue\fR +.sp +\fB::simulation::annealing::findMinimum\fR \fIargs\fR +.sp +\fB::simulation::annealing::findCombinatorialMinimum\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +The technique of \fIsimulated annealing\fR provides methods to +estimate the global optimum of a function. It is described in some +detail on the Wiki \fIhttp://wiki.tcl.tk/...\fR. The idea is simple: +.IP \(bu +randomly select points within a given search space +.IP \(bu +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. +.IP \(bu +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. +.PP +The method resembles the cooling of material, hence the name. +.PP +The package \fIsimulation::annealing\fR offers the command \fIfindMinimum\fR: +.CS + + + 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)}] + +.CE +prints the estimated minimum value of the function f(x,y) = +\fIx**2+y**2+sin(10*x)+4*cos(20*y)\fR and the values of x and y where +the minimum was attained: +.CS + + +result -4.9112922923 x -0.181647676593 y 0.155743646974 + +.CE +.SH PROCEDURES +The package defines the following auxiliary procedures: +.TP +\fB::simulation::annealing::getOption\fR \fIkeyword\fR +Get the value of an option given as part of the \fIfindMinimum\fR +command. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.RE +.sp +.TP +\fB::simulation::annealing::hasOption\fR \fIkeyword\fR +Returns 1 if the option is available, 0 if not. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.RE +.sp +.TP +\fB::simulation::annealing::setOption\fR \fIkeyword\fR \fIvalue\fR +Set the value of the given option. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.TP +string \fIvalue\fR +(New) value for the option +.RE +.PP +The main procedures are \fIfindMinimum\fR and \fIfindCombinatorialMinimum\fR: +.TP +\fB::simulation::annealing::findMinimum\fR \fIargs\fR +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. +.RS +.TP +int \fIn\fR +List of keyword-value pairs, all of which are available +during the execution via the \fIgetOption\fR command. +.RE +.TP +\fB::simulation::annealing::findCombinatorialMinimum\fR \fIargs\fR +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. +.RS +.TP +int \fIn\fR +List of keyword-value pairs, all of which are available +during the execution via the \fIgetOption\fR command. +.RE +.PP +The \fIfindMinimum\fR command predefines the following options: +.IP \(bu +\fI-parameters list\fR: triples defining parameters and ranges +.IP \(bu +\fI-function expr\fR: expression defining the function +.IP \(bu +\fI-code body\fR: body of code to define the function (takes +precedence over \fI-function\fR). The code should set the variable +"result" +.IP \(bu +\fI-init code\fR: code to be run at start up +\fI-final code\fR: code to be run at the end +\fI-trials n\fR: number of trials before reducing the temperature +\fI-reduce factor\fR: reduce the temperature by this factor (between 0 and 1) +\fI-initial-temp t\fR: initial temperature +\fI-scale s\fR: scale of the function (order of magnitude of the values) +\fI-estimate-scale y/n\fR: estimate the scale (only if \fI-scale\fR +is not present) +\fI-verbose y/n\fR: print detailed information on progress to the +report file (1) or not (0) +\fI-reportfile file\fR: opened file to print to (defaults to stdout) +.PP +Any other options can be used via the getOption procedure +in the body. +The \fIfindCombinatorialMinimum\fR command predefines the following +options: +.IP \(bu +\fI-number-params n\fR: number of binary parameters (the solution +space consists of lists of 1s and 0s). This is a required option. +.IP \(bu +\fI-initial-values\fR: list of 1s and 0s constituting the start of +the search. +.PP +The other predefined options are identical to those of \fIfindMinimum\fR. +.SH TIPS +The procedure \fIfindMinimum\fR 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. +.PP +It is possible to optimise over a non-rectangular region, but some care +must be taken: +.IP \(bu +If the point is outside the region of interest, you can specify a very +high value. +.IP \(bu +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. +.PP +Here is an example of finding an optimum inside a circle: +.CS + + + 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 + } + }] + +.CE +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. +.PP +You can use the \fI-final\fR option to use a deterministic optimization +method, once you are sure you are near the required optimum. +.PP +The \fIfindCombinatorialMinimum\fR 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: +.IP \(bu +We have a function that attains an absolute minimum if the first ten +numbers are 1 and the rest is 0: +.CS + + +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 +} + +.CE +.IP \(bu +We want to find the solution that gives this minimum for various lengths +of the solution vector \fIparams\fR: +.CS + + +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]}] +} + +.CE +.IP \(bu +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. +.PP +.SH KEYWORDS +math, optimization, simulated annealing +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/simulation/montecarlo.n Index: embedded/man/files/modules/simulation/montecarlo.n ================================================================== --- /dev/null +++ embedded/man/files/modules/simulation/montecarlo.n @@ -0,0 +1,462 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/simulation/montecarlo.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "simulation::montecarlo" n 0.1 tcllib "Tcl Simulation Tools" +.BS +.SH NAME +simulation::montecarlo \- Monte Carlo simulations +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBsimulation::montecarlo 0.1\fR +.sp +package require \fBsimulation::random \fR +.sp +package require \fBmath::statistics \fR +.sp +\fB::simulation::montecarlo::getOption\fR \fIkeyword\fR +.sp +\fB::simulation::montecarlo::hasOption\fR \fIkeyword\fR +.sp +\fB::simulation::montecarlo::setOption\fR \fIkeyword\fR \fIvalue\fR +.sp +\fB::simulation::montecarlo::setTrialResult\fR \fIvalues\fR +.sp +\fB::simulation::montecarlo::setExpResult\fR \fIvalues\fR +.sp +\fB::simulation::montecarlo::getTrialResults\fR +.sp +\fB::simulation::montecarlo::getExpResult\fR +.sp +\fB::simulation::montecarlo::transposeData\fR \fIvalues\fR +.sp +\fB::simulation::montecarlo::integral2D\fR \fI...\fR +.sp +\fB::simulation::montecarlo::singleExperiment\fR \fIargs\fR +.sp +.BE +.SH DESCRIPTION +.PP +The technique of \fIMonte Carlo simulations\fR is basically simple: +.IP \(bu +generate random values for one or more parameters. +.IP \(bu +evaluate the model of some system you are interested in and record the +interesting results for each realisation of these parameters. +.IP \(bu +after a suitable number of such trials, deduce an overall characteristic +of the model. +.PP +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. +.PP +The package \fIsimulation::montecarlo\fR offers a basic framework for +such a modelling technique: +.CS + + +# +# 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} + +.CE +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. +.SH PROCEDURES +The package defines the following auxiliary procedures: +.TP +\fB::simulation::montecarlo::getOption\fR \fIkeyword\fR +Get the value of an option given as part of the \fIsingeExperiment\fR command. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.RE +.sp +.TP +\fB::simulation::montecarlo::hasOption\fR \fIkeyword\fR +Returns 1 if the option is available, 0 if not. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.RE +.sp +.TP +\fB::simulation::montecarlo::setOption\fR \fIkeyword\fR \fIvalue\fR +Set the value of the given option. +.RS +.TP +string \fIkeyword\fR +Given keyword (without leading minus) +.TP +string \fIvalue\fR +(New) value for the option +.RE +.sp +.TP +\fB::simulation::montecarlo::setTrialResult\fR \fIvalues\fR +Store the results of the trial for later analysis +.RS +.TP +list \fIvalues\fR +List of values to be stored +.RE +.sp +.TP +\fB::simulation::montecarlo::setExpResult\fR \fIvalues\fR +Set the results of the entire experiment (typically used in the final +phase). +.RS +.TP +list \fIvalues\fR +List of values to be stored +.RE +.sp +.TP +\fB::simulation::montecarlo::getTrialResults\fR +Get the results of all individual trials for analysis (typically used in +the final phase or after completion of the command). +.sp +.TP +\fB::simulation::montecarlo::getExpResult\fR +Get the results of the entire experiment (typically used in the final +phase or even after completion of the \fIsingleExperiment\fR command). +.sp +.TP +\fB::simulation::montecarlo::transposeData\fR \fIvalues\fR +Interchange columns and rows of a list of lists and return the result. +.RS +.TP +list \fIvalues\fR +List of lists of values +.RE +.PP +There are two main procedures: \fIintegral2D\fR and \fIsingleExperiment\fR. +.TP +\fB::simulation::montecarlo::integral2D\fR \fI...\fR +Integrate a function over a two-dimensional region using a Monte Carlo +approach. +.sp +Arguments PM +.sp +.TP +\fB::simulation::montecarlo::singleExperiment\fR \fIargs\fR +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. +.RS +.TP +int \fIn\fR +List of keyword-value pairs, all of which are available +during the execution via the \fIgetOption\fR command. +.RE +.PP +The \fIsingleExperiment\fR command predefines the following +options: +.IP \(bu +\fI-init code\fR: code to be run at start up +.IP \(bu +\fI-loop body\fR: body of code that defines the computation to +be run time and again. The code should use \fIsetTrialResult\fR +to store the results of each trial (typically a list of numbers, +but the interpretation is up to the implementation). Note: Required keyword. +.IP \(bu +\fI-final code\fR: code to be run at the end +.IP \(bu +\fI-trials n\fR: number of trials in the experiment (required) +.IP \(bu +\fI-reportfile file\fR: opened file to send the output to (default: stdout) +.IP \(bu +\fI-verbose\fR: write the intermediate results (1) or not (0) (default: 0) +.IP \(bu +\fI-analysis proc\fR: 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. +.IP \(bu +\fI-columns list\fR: list of column names, useful for verbose output +and the analysis +.PP +Any other options can be used via the getOption procedure +in the body. +.SH TIPS +The procedure \fIsingleExperiment\fR works by constructing a +temporary procedure that does the actual work. It loops for the given +number of trials. +.PP +As it constructs a temporary procedure, local variables defined at the +start continue to exist in the loop. +.SH KEYWORDS +math, montecarlo simulation, stochastic modelling +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/simulation/simulation_random.n Index: embedded/man/files/modules/simulation/simulation_random.n ================================================================== --- /dev/null +++ embedded/man/files/modules/simulation/simulation_random.n @@ -0,0 +1,484 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/simulation/simulation_random.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "simulation::random" n 0.1 tcllib "Tcl Simulation Tools" +.BS +.SH NAME +simulation::random \- Pseudo-random number generators +.SH SYNOPSIS +package require \fBTcl ?8.4?\fR +.sp +package require \fBsimulation::random 0.1\fR +.sp +\fB::simulation::random::prng_Bernoulli\fR \fIp\fR +.sp +\fB::simulation::random::prng_Discrete\fR \fIn\fR +.sp +\fB::simulation::random::prng_Poisson\fR \fIlambda\fR +.sp +\fB::simulation::random::prng_Uniform\fR \fImin\fR \fImax\fR +.sp +\fB::simulation::random::prng_Exponential\fR \fImin\fR \fImean\fR +.sp +\fB::simulation::random::prng_Normal\fR \fImean\fR \fIstdev\fR +.sp +\fB::simulation::random::prng_Pareto\fR \fImin\fR \fIsteep\fR +.sp +\fB::simulation::random::prng_Gumbel\fR \fImin\fR \fIf\fR +.sp +\fB::simulation::random::prng_chiSquared\fR \fIdf\fR +.sp +\fB::simulation::random::prng_Disk\fR \fIrad\fR +.sp +\fB::simulation::random::prng_Sphere\fR \fIrad\fR +.sp +\fB::simulation::random::prng_Ball\fR \fIrad\fR +.sp +\fB::simulation::random::prng_Rectangle\fR \fIlength\fR \fIwidth\fR +.sp +\fB::simulation::random::prng_Block\fR \fIlength\fR \fIwidth\fR \fIdepth\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package consists of commands to generate pseudo-random number +generators. These new commands deliver +.IP \(bu +numbers that are distributed normally, uniformly, according to a +Pareto or Gumbel distribution and so on +.IP \(bu +coordinates of points uniformly spread inside a sphere or a rectangle +.PP +For example: +.CS + + + set p [::simulation::random::prng_Normal -1.0 10.0] + +.CE +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. +.SH PROCEDURES +The package defines the following public procedures for \fIdiscrete\fR +distributions: +.TP +\fB::simulation::random::prng_Bernoulli\fR \fIp\fR +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 +.RS +.TP +float \fIp\fR +Chance the outcome is 1 +.RE +.sp +.TP +\fB::simulation::random::prng_Discrete\fR \fIn\fR +Create a command (PRNG) that generates numbers 0 to n-1 with equal +probability. +.RS +.TP +int \fIn\fR +Number of different values (ranging from 0 to n-1) +.RE +.sp +.TP +\fB::simulation::random::prng_Poisson\fR \fIlambda\fR +Create a command (PRNG) that generates numbers according to the Poisson +distribution. +.RS +.TP +float \fIlambda\fR +Mean number per time interval +.RE +.PP +The package defines the following public procedures for \fIcontinuous\fR distributions: +.TP +\fB::simulation::random::prng_Uniform\fR \fImin\fR \fImax\fR +Create a command (PRNG) that generates uniformly distributed numbers +between "min" and "max". +.RS +.TP +float \fImin\fR +Minimum number that will be generated +.TP +float \fImax\fR +Maximum number that will be generated +.RE +.sp +.TP +\fB::simulation::random::prng_Exponential\fR \fImin\fR \fImean\fR +Create a command (PRNG) that generates exponentially distributed numbers +with a given minimum value and a given mean value. +.RS +.TP +float \fImin\fR +Minimum number that will be generated +.TP +float \fImean\fR +Mean value for the numbers +.RE +.sp +.TP +\fB::simulation::random::prng_Normal\fR \fImean\fR \fIstdev\fR +Create a command (PRNG) that generates normally distributed numbers +with a given mean value and a given standard deviation. +.RS +.TP +float \fImean\fR +Mean value for the numbers +.TP +float \fIstdev\fR +Standard deviation +.RE +.sp +.TP +\fB::simulation::random::prng_Pareto\fR \fImin\fR \fIsteep\fR +Create a command (PRNG) that generates numbers distributed according to +Pareto with a given minimum value and a given distribution steepness. +.RS +.TP +float \fImin\fR +Minimum number that will be generated +.TP +float \fIsteep\fR +Steepness of the distribution +.RE +.sp +.TP +\fB::simulation::random::prng_Gumbel\fR \fImin\fR \fIf\fR +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: +.CS + + + P(v) = exp( -exp(f*(v-min))) + +.CE +.RS +.TP +float \fImin\fR +Minimum number that will be generated +.TP +float \fIf\fR +Scale factor for the values +.RE +.sp +.TP +\fB::simulation::random::prng_chiSquared\fR \fIdf\fR +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. +.RS +.TP +float \fIdf\fR +Degrees of freedom +.RE +.PP +The package defines the following public procedures for random point sets: +.TP +\fB::simulation::random::prng_Disk\fR \fIrad\fR +Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a disk of given radius. +.RS +.TP +float \fIrad\fR +Radius of the disk +.RE +.sp +.TP +\fB::simulation::random::prng_Sphere\fR \fIrad\fR +Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over the surface of a sphere of given radius. +.RS +.TP +float \fIrad\fR +Radius of the disk +.RE +.sp +.TP +\fB::simulation::random::prng_Ball\fR \fIrad\fR +Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread within a ball of given radius. +.RS +.TP +float \fIrad\fR +Radius of the ball +.RE +.sp +.TP +\fB::simulation::random::prng_Rectangle\fR \fIlength\fR \fIwidth\fR +Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a rectangle. +.RS +.TP +float \fIlength\fR +Length of the rectangle (x-direction) +.TP +float \fIwidth\fR +Width of the rectangle (y-direction) +.RE +.sp +.TP +\fB::simulation::random::prng_Block\fR \fIlength\fR \fIwidth\fR \fIdepth\fR +Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over a block +.RS +.TP +float \fIlength\fR +Length of the block (x-direction) +.TP +float \fIwidth\fR +Width of the block (y-direction) +.TP +float \fIdepth\fR +Depth of the block (z-direction) +.RE +.PP +.SH KEYWORDS +math, random numbers, simulation, statistical distribution +.SH CATEGORY +Mathematics +.SH COPYRIGHT +.nf +Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/smtpd/smtpd.n Index: embedded/man/files/modules/smtpd/smtpd.n ================================================================== --- /dev/null +++ embedded/man/files/modules/smtpd/smtpd.n @@ -0,0 +1,496 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/smtpd/smtpd.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "smtpd" n 1.5 tcllib "Tcl SMTP Server Package" +.BS +.SH NAME +smtpd \- Tcl SMTP server implementation +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBsmtpd ?1.5?\fR +.sp +\fB::smtpd::start\fR ?\fImyaddr\fR? ?\fIport\fR? +.sp +\fB::smtpd::stop\fR +.sp +\fB::smptd::configure\fR ?\fIoption\fR \fIvalue\fR? ?\fIoption\fR \fIvalue\fR \fI...\fR? +.sp +\fB::smtpd::cget\fR ?\fIoption\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBsmtpd\fR package provides a simple Tcl-only server library +for the Simple Mail Transfer Protocol as described in +RFC 821 (\fIhttp://www.rfc-editor.org/rfc/rfc821.txt\fR) and +RFC 2821 (\fIhttp://www.rfc-editor.org/rfc/rfc2821.txt\fR). +By default the server will bind to the default network address and the +standard SMTP port (25). +.PP +This package was designed to permit testing of Mail User Agent code +from a developers workstation. \fIIt does not attempt to deliver mail to your mailbox.\fR 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. +.SH 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. +.PP +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. +.SH COMMANDS +.TP +\fB::smtpd::start\fR ?\fImyaddr\fR? ?\fIport\fR? +Start the service listening on \fIport\fR or the default port 25. If +\fImyaddr\fR 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: +.sp +.CS + + + set sock [::smtpd::start [info hostname] 0] + +.CE +.sp +will bind to the hosts internet interface on the first available port. +.sp +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 \fBoptions\fR array and the \fB::smtpd::stopped\fR variable +usage. +.sp +As the server code uses \fBfileevent\fR(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 \fBwish\fR(1) or you +should \fBvwait\fR(n) on the \fB::smtpd::stopped\fR variable which is +set when the server is stopped. +.TP +\fB::smtpd::stop\fR +Halt the server and release the listening socket. If the server has +not been started then this command does nothing. +The \fB::smtpd::stopped\fR variable is set for use with +\fBvwait\fR(n). +.sp +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 \fBfork\fR(2) and the client session continues on +the child process. +.TP +\fB::smptd::configure\fR ?\fIoption\fR \fIvalue\fR? ?\fIoption\fR \fIvalue\fR \fI...\fR? +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 \fBCALLBACKS\fR section for details of the +procedures. +.RS +.TP +\fB-banner\fR \fItext\fR +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. +.TP +\fB-validate_host\fR \fIproc\fR +Callback to authenticate new connections based on the ip-address of +the client. +.TP +\fB-validate_sender\fR \fIproc\fR +Callback to authenticate new connections based on the senders email +address. +.TP +\fB-validate_recipient\fR \fIproc\fR +Callback to validate and authorize a recipient email address +.TP +\fB-deliverMIME\fR \fIproc\fR +Callback used to deliver mail as a mime token created by the tcllib +\fBmime\fR package. +.TP +\fB-deliver\fR \fIproc\fR +Callback used to deliver email. This option has no effect if +the \fB-deliverMIME\fR option has been set. +.RE +.TP +\fB::smtpd::cget\fR ?\fIoption\fR? +If no \fIoption\fR 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. +.PP +.SH CALLBACKS +.TP +\fBvalidate_host\fR 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: +.sp +.CS + + + proc validate_host {ipnum} { + if {[string match "192.168.1.*" $ipnum]} { + error "go away!" + } + } + +.CE +.sp +If access is denied the client will receive a standard message that +includes the text of your error, such as: +.sp +.CS + + + 550 Access denied: I hate you. + +.CE +.sp +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 +\fB503 Bad Sequence\fR error. +.TP +\fBvalidate_sender\fR 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": +.sp +.CS + + + proc validate_sender {address} { + eval array set addr [mime::parseaddress $address] + if {[string match "denied" $addr(local)]} { + error "mailbox $addr(local) denied" + } + return + } + +.CE +.sp +The content of any error message will not be passed back to the client. +.TP +\fBvalidate_recipient\fR 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. +.TP +\fBdeliverMIME\fR callback +] +The deliverMIME callback is called once a mail message has been +successfully passed to the server. A mime token is constructed from +the sender, recipients and data and the users procedure it called with +this single argument. When the call returns, the mime token is cleaned +up so if the user wishes to preserve the data she must make a copy. +.sp +.CS + + + 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 + } + +.CE +.TP +\fBdeliver\fR 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: +.sp +.CS + + + proc deliver {sender recipients data} { + set mail "From $sender [clock format [clock seconds]]" + append mail "\\n" [join $data "\\n"] + puts "$mail" + } + +.CE +.sp +Note that the DATA command will return an error if no sender or +recipient has yet been defined. +.PP +.SH VARIABLES +.TP +\fB::smtpd::stopped\fR +This variable is set to \fBtrue\fR during the \fB::smtpd::stop\fR +command to permit the use of the \fBvwait\fR(n) command. +.PP +.SH AUTHOR +Written by Pat Thoyts \fImailto:patthoyts@users.sourceforge.net\fR. +.SH 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 +"\fIlicense.terms\fR" for more details. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsmtpd\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +rfc 2821, rfc 821, services, smtp, smtpd, socket, vwait +.SH CATEGORY +Networking +.SH COPYRIGHT +.nf +Copyright (c) Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/snit/snit.n Index: embedded/man/files/modules/snit/snit.n ================================================================== --- /dev/null +++ embedded/man/files/modules/snit/snit.n @@ -0,0 +1,2849 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/snit/snit.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2009, by William H. Duquette +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "snit" n 2.3.2 tcllib "Snit's Not Incr Tcl, OO system" +.BS +.SH NAME +snit \- Snit's Not Incr Tcl +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBsnit ?2.3.2?\fR +.sp +\fBsnit::type\fR \fIname\fR \fIdefinition\fR +.sp +\fBtypevariable\fR \fIname\fR ?\fB-array\fR? ?\fIvalue\fR? +.sp +\fBtypemethod\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBtypeconstructor\fR \fIbody\fR +.sp +\fBvariable\fR \fIname\fR ?\fB-array\fR? ?\fIvalue\fR? +.sp +\fBmethod\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBoption\fR \fInamespec\fR ?\fIdefaultValue\fR? +.sp +\fBoption\fR \fInamespec\fR ?\fIoptions...\fR? +.sp +\fBconstructor\fR \fIarglist\fR \fIbody\fR +.sp +\fBdestructor\fR \fIbody\fR +.sp +\fBproc\fR \fIname\fR \fIargs\fR \fIbody\fR +.sp +\fBdelegate\fR \fBmethod\fR \fIname\fR \fBto\fR \fIcomp\fR ?\fBas\fR \fItarget\fR? +.sp +\fBdelegate\fR \fBmethod\fR \fIname\fR ?\fBto\fR \fIcomp\fR? \fBusing\fR \fIpattern\fR +.sp +\fBdelegate\fR \fBmethod\fR \fB*\fR ?\fBto\fR \fIcomp\fR? ?\fBusing\fR \fIpattern\fR? ?\fBexcept\fR \fIexceptions\fR? +.sp +\fBdelegate\fR \fBoption\fR \fInamespec\fR \fBto\fR \fIcomp\fR +.sp +\fBdelegate\fR \fBoption\fR \fInamespec\fR \fBto\fR \fIcomp\fR \fBas\fR \fItarget\fR +.sp +\fBdelegate\fR \fBoption\fR \fB*\fR \fBto\fR \fIcomp\fR +.sp +\fBdelegate\fR \fBoption\fR \fB*\fR \fBto\fR \fIcomp\fR \fBexcept\fR \fIexceptions\fR +.sp +\fBcomponent\fR \fIcomp\fR ?\fB-public\fR \fImethod\fR? ?\fB-inherit\fR \fIflag\fR? +.sp +\fBdelegate\fR \fBtypemethod\fR \fIname\fR \fBto\fR \fIcomp\fR ?\fBas\fR \fItarget\fR? +.sp +\fBdelegate\fR \fBtypemethod\fR \fIname\fR ?\fBto\fR \fIcomp\fR? \fBusing\fR \fIpattern\fR +.sp +\fBdelegate\fR \fBtypemethod\fR \fB*\fR ?\fBto\fR \fIcomp\fR? ?\fBusing\fR \fIpattern\fR? ?\fBexcept\fR \fIexceptions\fR? +.sp +\fBtypecomponent\fR \fIcomp\fR ?\fB-public\fR \fItypemethod\fR? ?\fB-inherit\fR \fIflag\fR? +.sp +\fBpragma\fR ?\fIoptions...\fR? +.sp +\fBexpose\fR \fIcomp\fR +.sp +\fBexpose\fR \fIcomp\fR \fBas\fR \fImethod\fR +.sp +\fBonconfigure\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBoncget\fR \fIname\fR \fIbody\fR +.sp +\fBsnit::widget\fR \fIname\fR \fIdefinition\fR +.sp +\fBwidgetclass\fR \fIname\fR +.sp +\fBhulltype\fR \fItype\fR +.sp +\fBsnit::widgetadaptor\fR \fIname\fR \fIdefinition\fR +.sp +\fBsnit::typemethod\fR \fItype\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBsnit::method\fR \fItype\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBsnit::macro\fR \fIname\fR \fIarglist\fR \fIbody\fR +.sp +\fBsnit::compile\fR \fIwhich\fR \fItype\fR \fIbody\fR +.sp +\fB$type\fR \fItypemethod\fR \fIargs\fR... +.sp +\fB$type\fR \fBcreate\fR \fIname\fR ?\fIoption\fR \fIvalue\fR ...? +.sp +\fB$type\fR \fBinfo typevars\fR ?\fIpattern\fR? +.sp +\fB$type\fR \fBinfo typemethods\fR ?\fIpattern\fR? +.sp +\fB$type\fR \fBinfo args\fR \fImethod\fR +.sp +\fB$type\fR \fBinfo body\fR \fImethod\fR +.sp +\fB$type\fR \fBinfo default\fR \fImethod\fR \fIaname\fR \fIvarname\fR +.sp +\fB$type\fR \fBinfo instances\fR ?\fIpattern\fR? +.sp +\fB$type\fR \fBdestroy\fR +.sp +\fB$object\fR \fImethod\fR \fIargs...\fR +.sp +\fB$object\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue\fR? ... +.sp +\fB$object\fR \fBconfigurelist\fR \fIoptionlist\fR +.sp +\fB$object\fR \fBcget\fR \fIoption\fR +.sp +\fB$object\fR \fBdestroy\fR +.sp +\fB$object\fR \fBinfo type\fR +.sp +\fB$object\fR \fBinfo vars\fR ?\fIpattern\fR? +.sp +\fB$object\fR \fBinfo typevars\fR ?\fIpattern\fR? +.sp +\fB$object\fR \fBinfo typemethods\fR ?\fIpattern\fR? +.sp +\fB$object\fR \fBinfo options\fR ?\fIpattern\fR? +.sp +\fB$object\fR \fBinfo methods\fR ?\fIpattern\fR? +.sp +\fB$object\fR \fBinfo args\fR \fImethod\fR +.sp +\fB$object\fR \fBinfo body\fR \fImethod\fR +.sp +\fB$object\fR \fBinfo default\fR \fImethod\fR \fIaname\fR \fIvarname\fR +.sp +\fBmymethod\fR \fIname\fR ?\fIargs...\fR? +.sp +\fBmytypemethod\fR \fIname\fR ?\fIargs...\fR? +.sp +\fBmyproc\fR \fIname\fR ?\fIargs...\fR? +.sp +\fBmyvar\fR \fIname\fR +.sp +\fBmytypevar\fR \fIname\fR +.sp +\fBfrom\fR \fIargvName\fR \fIoption\fR ?\fIdefvalue\fR? +.sp +\fBinstall\fR \fIcompName\fR \fBusing\fR \fIobjType\fR \fIobjName\fR \fIargs...\fR +.sp +\fBinstallhull\fR \fBusing\fR \fIwidgetType\fR \fIargs...\fR +.sp +\fBinstallhull\fR \fIname\fR +.sp +\fBvariable\fR \fIname\fR +.sp +\fBtypevariable\fR \fIname\fR +.sp +\fBvarname\fR \fIname\fR +.sp +\fBtypevarname\fR \fIname\fR +.sp +\fBcodename\fR \fIname\fR +.sp +\fBsnit::boolean\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::boolean\fR \fIname\fR +.sp +\fBsnit::double\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::double\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::enum\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::enum\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::fpixels\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::fpixels\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::integer\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::integer\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::listtype\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::listtype\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::pixels\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::pixels\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::stringtype\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::stringtype\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +.sp +\fBsnit::window\fR \fBvalidate\fR ?\fIvalue\fR? +.sp +\fBsnit::window\fR \fIname\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBTk\fR widget, an \fBIncr Tcl\fR object, +a \fBBWidget\fR or almost anything else. +.PP +This man page is intended to be a reference only; see the accompanying +\fBsnitfaq\fR for a gentler, more tutorial introduction to Snit +concepts. +.SH "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 \fBsnitfaq\fR. +.PP +.SH REFERENCE +.SS "TYPE AND WIDGET DEFINITIONS" +Snit provides the following commands for defining new types: +.TP +\fBsnit::type\fR \fIname\fR \fIdefinition\fR +Defines a new abstract data type called \fIname\fR. If \fIname\fR is +not a fully qualified command name, it is assumed to be a name in the +namespace in which the \fBsnit::type\fR command was called (usually the +global namespace). It returns the fully qualified name of the new type. +.sp +The type name is then a command that is used to create objects of the +new type, along with other activities. +.sp +The \fBsnit::type\fR \fIdefinition\fR block is a script that may +contain the following definitions: +.RS +.TP +\fBtypevariable\fR \fIname\fR ?\fB-array\fR? ?\fIvalue\fR? +Defines a type variable with the specified \fIname\fR, and optionally +the specified \fIvalue\fR. Type variables are shared by all instances +of the type. If the \fB-array\fR option is included, then +\fIvalue\fR should be a dictionary; it will be +assigned to the variable using \fBarray set\fR. +.TP +\fBtypemethod\fR \fIname\fR \fIarglist\fR \fIbody\fR +Defines a type method, a subcommand of the new type command, +with the specified name, argument list, and +body. The \fIarglist\fR is a normal Tcl argument list and may contain +default arguments and the \fBargs\fR argument; however, it may not +contain the argument names \fBtype\fR, \fBself\fR, \fBselfns\fR, or +\fBwin\fR. +.sp +The variable \fBtype\fR is automatically defined in the \fIbody\fR to +the type's fully-qualified name. In addition, +type variables are automatically visible in the \fIbody\fR +of every type method. +.sp +If the \fIname\fR consists of two or more tokens, Snit handles it specially: +.CS + + typemethod {a b} {arg} { puts "Got $arg" } + +.CE +.IP +This statement implicitly defines a type method called \fBa\fR which +has a subcommand \fBb\fR. \fBb\fR is called like this: +.CS + + $type a b "Hello, world!" + +.CE +.IP +\fBa\fR may have any number of subcommands. This makes it possible +to define a hierarchical command structure; see \fBmethod\fR, below, +for more examples. +.sp +Type methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +\fB::parentns::typename\fR, then the type's type methods can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the following +following two calls to this type method are equivalent: +.CS + + $type a b "Hello, world!" + $type {a b} "Hello, world!" + +.CE +.IP +In Snit 2.2, the second form is invalid. +.TP +\fBtypeconstructor\fR \fIbody\fR +The type constructor's \fIbody\fR is executed once when the +type is first defined; it is typically used to +initialize array-valued type variables and to add +entries to \fBThe Tk Option Database\fR. +.sp +The variable \fBtype\fR is automatically defined in the \fIbody\fR, +and contains the type's fully-qualified name. In addition, +type variables are automatically visible in the \fIbody\fR of the type +constructor. +.sp +A type may define at most one type constructor. +.sp +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 +\fB::parentns::typename\fR, then the type constructor can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.TP +\fBvariable\fR \fIname\fR ?\fB-array\fR? ?\fIvalue\fR? +Defines an instance variable, a private variable associated with each +instance of this type, and optionally its initial value. +If the \fB-array\fR option is included, then +\fIvalue\fR should be a dictionary; it will be +assigned to the variable using \fBarray set\fR. +.TP +\fBmethod\fR \fIname\fR \fIarglist\fR \fIbody\fR +Defines an instance method, a subcommand of each instance of this +type, with the specified name, argument list and body. +The \fIarglist\fR is a normal Tcl argument list and may contain +default arguments and the \fBargs\fR argument. +.sp +The method is implicitly passed the following arguments as well: +\fBtype\fR, which contains the fully-qualified type name; \fBself\fR, +which contains the current instance command name; \fBselfns\fR, which +contains the name of the instance's private namespace; and \fBwin\fR, +which contains the original instance name. +Consequently, the \fIarglist\fR may not contain the argument names +\fBtype\fR, \fBself\fR, \fBselfns\fR, or \fBwin\fR. +.sp +An instance method defined in this way is said to be +\fIlocally defined\fR. +.sp +Type and instance variables are +automatically visible in all instance methods. If the type has +locally defined options, the \fBoptions\fR array is also visible. +.sp +If the \fIname\fR consists of two or more tokens, Snit handles it specially: +.CS + + method {a b} {} { ... } + +.CE +.IP +This statement implicitly defines a method called \fBa\fR which +has a subcommand \fBb\fR. \fBb\fR is called like this: +.CS + + $self a b "Hello, world!" + +.CE +.IP +\fBa\fR may have any number of subcommands. This makes it possible +to define a hierarchical command structure: +.CS + +% 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 +% + +.CE +.IP +What we've done is implicitly defined a "tail" method with subcommands +"wag" and "droop". Consequently, it's an error to define "tail" +explicitly. +.sp +Methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +\fB::parentns::typename\fR, then the type's methods can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the following +following two calls to this method are equivalent: +.CS + + $self a b "Hello, world!" + $self {a b} "Hello, world!" + +.CE +.IP +In Snit 2.2, the second form is invalid. +.TP +\fBoption\fR \fInamespec\fR ?\fIdefaultValue\fR? +.TP +\fBoption\fR \fInamespec\fR ?\fIoptions...\fR? +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 \fIdefaultValue\fR is specified. +.sp +An option defined in this way is said to be \fIlocally defined\fR. +.sp +The \fInamespec\fR is a list defining the option's +name, resource name, and class name, e.g.: +.CS + + option {-font font Font} {Courier 12} + +.CE +.IP +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: +.CS + + option -font {Courier 12} + +.CE +.IP +See \fBThe Tk Option Database\fR for more information about +resource and class names. +.sp +Options are normally set and retrieved using the standard +instance methods \fBconfigure\fR and \fBcget\fR; within instance code +(method bodies, etc.), option values are available through the +\fBoptions\fR array: +.CS + + set myfont $options(-font) + +.CE +.IP +If the type defines any option handlers (e.g., \fB-configuremethod\fR), +then it should probably use \fBconfigure\fR and \fBcget\fR to +access its options to avoid subtle errors. +.sp +The \fBoption\fR statement may include the following options: +.RS +.TP +\fB-default\fR \fIdefvalue\fR +Defines the option's default value; the option's default value +will be "" otherwise. +.TP +\fB-readonly\fR \fIflag\fR +The \fIflag\fR can be any Boolean value recognized by Tcl. +If \fIflag\fR is true, then the option is read-only--it can only +be set using \fBconfigure\fR or \fBconfigurelist\fR +at creation time, i.e., in the type's constructor. +.TP +\fB-type\fR \fItype\fR +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 +.sp +For example, an option may declare that its value must be an integer +by specifying \fBsnit::integer\fR as its validation type: +.CS + + option -number -type snit::integer + +.CE +.IP +It may also declare that its value is an integer between 1 and 10 +by specifying a validation subtype: +.CS + + option -number -type {snit::integer -min 1 -max 10} + +.CE +.IP +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 \fBconfigure\fR or +\fBconfigurelist\fR methods. In addition, all such options +will have their values validated automatically immediately +after the constructor executes. +.sp +Snit defines a family of validation types and subtypes, and it's +quite simple to define new ones. See +\fBValidation Types\fR for the complete list, and +\fBDefining Validation Types\fR for an explanation of how +to define your own. +.TP +\fB-cgetmethod\fR \fImethodName\fR +Every locally-defined option may define a \fB-cgetmethod\fR; +it is called when the option's value is retrieved using the +\fBcget\fR method. Whatever the method's \fIbody\fR returns will +be the return value of the call to \fBcget\fR. +.sp +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 \fBcget\fR: +.CS + + option -font -cgetmethod GetOption + method GetOption {option} { + return $options($option) + } + +.CE +.IP +Note that it's possible for any number of options to share a +\fB-cgetmethod\fR. +.TP +\fB-configuremethod\fR \fImethodName\fR +Every locally-defined option may define a \fB-configuremethod\fR; +it is called when the option's value is set using the +\fBconfigure\fR or \fBconfigurelist\fR 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 \fBoptions()\fR array unless +the method saves it there. +.sp +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 \fBconfigure\fR: +.CS + + option -font -configuremethod SetOption + method SetOption {option value} { + set options($option) $value + } + +.CE +.IP +Note that it's possible for any number of options to share a +single \fB-configuremethod\fR. +.TP +\fB-validatemethod\fR \fImethodName\fR +Every locally-defined option may define a \fB-validatemethod\fR; +it is called when the option's value is set using the +\fBconfigure\fR or \fBconfigurelist\fR methods, just before +the \fB-configuremethod\fR (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. +.sp +The named method must take two arguments, the option name and +its new value. For example, this code verifies that +\fB-flag\fR's value is a valid Boolean value: +.CS + + option -font -validatemethod CheckBoolean + method CheckBoolean {option value} { + if {![string is boolean -strict $value]} { + error "option $option must have a boolean value." + } + } + +.CE +.IP +Note that it's possible for any number of options to share a +single \fB-validatemethod\fR. +.RE +.TP +\fBconstructor\fR \fIarglist\fR \fIbody\fR +The constructor definition specifies a \fIbody\fR of code to be +executed when a new instance is created. The \fIarglist\fR is a +normal Tcl argument list and may contain default arguments and +the \fBargs\fR argument. +.sp +As with methods, the arguments \fBtype\fR, \fBself\fR, \fBselfns\fR, +and \fBwin\fR are defined implicitly, and all type and instance +variables are automatically visible in its \fIbody\fR. +.sp +If the \fIdefinition\fR 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: +.CS + + constructor {args} { + $self configurelist $args + } + +.CE +.IP +For standard Tk widget behavior, the argument list should be +the single name \fBargs\fR, as shown. +.sp +If the \fIdefinition\fR defines neither a constructor nor +any options, the default constructor is defined as follows: +.CS + + constructor {} {} + +.CE +.IP +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 +\fB::parentns::typename\fR, then the constructor can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.TP +\fBdestructor\fR \fIbody\fR +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. +.sp +The destructor takes no explicit arguments; as with methods, the +arguments \fBtype\fR, \fBself\fR, \fBselfns\fR, and \fBwin\fR, are +defined implicitly, and all type and instance +variables are automatically visible in its \fIbody\fR. +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 +\fB::parentns::typename\fR, then the destructor can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.TP +\fBproc\fR \fIname\fR \fIargs\fR \fIbody\fR +Defines a new Tcl procedure in the type's namespace. +.sp +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 +\fBselfns\fR (with precisely that name) as one of its arguments. +.sp +Although they are not implicitly defined for procs, the argument names +\fBtype\fR, \fBself\fR, and \fBwin\fR should be avoided. +.sp +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 +\fB::parentns::typename\fR, then the proc can call +\fB::parentns::someproc\fR just as \fBsomeproc\fR. +\fISnit 1.x Incompatibility:\fR This does not work in Snit 1.x, as +it depends on \fBnamespace path\fR, a new command in Tcl 8.5. +.TP +\fBdelegate\fR \fBmethod\fR \fIname\fR \fBto\fR \fIcomp\fR ?\fBas\fR \fItarget\fR? +Delegates method \fIname\fR to component \fIcomp\fR. That is, when +method \fIname\fR 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 +.CS + + delegate method wag to tail + +.CE +.IP +is roughly equivalent to this explicitly defined method: +.CS + + method wag {args} { + uplevel $tail wag $args + } + +.CE +.IP +As with methods, the \fIname\fR may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method. +.sp +The optional \fBas\fR clause allows you to specify the delegated +method name and possibly add some arguments: +.CS + + delegate method wagtail to tail as "wag briskly" + +.CE +.sp +A method cannot be both locally defined and delegated. +.sp +\fBNote:\fR All forms of \fBdelegate method\fR can delegate to +both instance components and type components. +.TP +\fBdelegate\fR \fBmethod\fR \fIname\fR ?\fBto\fR \fIcomp\fR? \fBusing\fR \fIpattern\fR +In this form of the \fBdelegate\fR statement, the \fBusing\fR clause +is used to specify the precise form of the command to which method +\fIname\fR name is delegated. In this form, the \fBto\fR clause is +optional, since the chosen command might not involve any particular +component. +.sp +The value of the \fBusing\fR 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: +.CS + + delegate method wag to tail + delegate method wag to tail using "%c %m" + +.CE +.IP +Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string. +.sp +Substitutions: +.RS +.TP +\fB%%\fR +This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c". +.TP +\fB%c\fR +This is replaced with the named component's command. +.TP +\fB%m\fR +This is replaced with the final token of the method \fIname\fR; if +the method \fIname\fR has one token, this is identical to \fB%M\fR. +.TP +\fB%M\fR +This is replaced by the method \fIname\fR; if the \fIname\fR consists +of multiple tokens, they are joined by space characters. +.TP +\fB%j\fR +This is replaced by the method \fIname\fR; if the \fIname\fR consists +of multiple tokens, they are joined by underscores ("_"). +.TP +\fB%t\fR +This is replaced with the fully qualified type name. +.TP +\fB%n\fR +This is replaced with the name of the instance's private namespace. +.TP +\fB%s\fR +This is replaced with the name of the instance command. +.TP +\fB%w\fR +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. +.RE +.TP +\fBdelegate\fR \fBmethod\fR \fB*\fR ?\fBto\fR \fIcomp\fR? ?\fBusing\fR \fIpattern\fR? ?\fBexcept\fR \fIexceptions\fR? +The form \fBdelegate method *\fR delegates all unknown method names to the +specified \fIcomp\fRonent. The \fBexcept\fR clause can be used to +specify a list of \fIexceptions\fR, i.e., method names that will not +be so delegated. The \fBusing\fR clause is defined as given above. +In this form, the statement must contain the \fBto\fR clause, the +\fBusing\fR clause, or both. +.sp +In fact, the "*" can be a list of two or more tokens whose last +element is "*", as in the following example: +.CS + + delegate method {tail *} to tail + +.CE +.IP +This implicitly defines the method \fBtail\fR whose subcommands will +be delegated to the \fBtail\fR component. +.TP +\fBdelegate\fR \fBoption\fR \fInamespec\fR \fBto\fR \fIcomp\fR +.TP +\fBdelegate\fR \fBoption\fR \fInamespec\fR \fBto\fR \fIcomp\fR \fBas\fR \fItarget\fR +.TP +\fBdelegate\fR \fBoption\fR \fB*\fR \fBto\fR \fIcomp\fR +.TP +\fBdelegate\fR \fBoption\fR \fB*\fR \fBto\fR \fIcomp\fR \fBexcept\fR \fIexceptions\fR +Defines a delegated option; the \fInamespec\fR is defined as for the +\fBoption\fR statement. +When the \fBconfigure\fR, \fBconfigurelist\fR, or \fBcget\fR +instance method is used to set or retrieve the option's value, the +equivalent \fBconfigure\fR or \fBcget\fR command will be applied +to the component as though the option was defined with the following +\fB-configuremethod\fR and \fB-cgetmethod\fR: +.CS + + method ConfigureMethod {option value} { + $comp configure $option $value + } + + method CgetMethod {option} { + return [$comp cget $option] + } + +.CE +.IP +Note that delegated options never appear in the \fBoptions\fR array. +.sp +If the \fBas\fR clause is specified, then the \fItarget\fR option +name is used in place of \fIname\fR. +.sp +The form \fBdelegate option *\fR delegates all unknown options to the +specified \fIcomp\fRonent. The \fBexcept\fR clause can be used to +specify a list of \fIexceptions\fR, i.e., option names that will not +be so delegated. +.sp +Warning: options can only be delegated to a component if it supports +the \fBconfigure\fR and \fBcget\fR instance methods. +.sp +An option cannot be both locally defined and delegated. +TBD: Continue from here. +.TP +\fBcomponent\fR \fIcomp\fR ?\fB-public\fR \fImethod\fR? ?\fB-inherit\fR \fIflag\fR? +Explicitly declares a component called \fIcomp\fR, and automatically +defines the component's instance variable. +.sp +If the \fB-public\fR option is specified, then the option is made +public by defining a \fImethod\fR whose subcommands are delegated +to the component e.g., specifying \fB-public mycomp\fR is +equivalent to the following: +.CS + + component mycomp + delegate method {mymethod *} to mycomp + +.CE +.IP +If the \fB-inherit\fR option is specified, then \fIflag\fR must be a +Boolean value; if \fIflag\fR is true then all unknown methods and +options will be delegated to this component. The name \fB-inherit\fR +implies that instances of this new type inherit, in a sense, the +methods and options of the component. That is, \fB-inherit yes\fR is +equivalent to: +.CS + + component mycomp + delegate option * to mycomp + delegate method * to mycomp + +.CE +.TP +\fBdelegate\fR \fBtypemethod\fR \fIname\fR \fBto\fR \fIcomp\fR ?\fBas\fR \fItarget\fR? +Delegates type method \fIname\fR to type component \fIcomp\fR. That is, when +type method \fIname\fR 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 +.CS + + delegate typemethod lostdogs to pound + +.CE +.IP +is roughly equivalent to this explicitly defined method: +.CS + + typemethod lostdogs {args} { + uplevel $pound lostdogs $args + } + +.CE +.IP +As with type methods, the \fIname\fR may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method. +.sp +The optional \fBas\fR clause allows you to specify the delegated +method name and possibly add some arguments: +.CS + + delegate typemethod lostdogs to pound as "get lostdogs" + +.CE +.sp +A type method cannot be both locally defined and delegated. +.TP +\fBdelegate\fR \fBtypemethod\fR \fIname\fR ?\fBto\fR \fIcomp\fR? \fBusing\fR \fIpattern\fR +In this form of the \fBdelegate\fR statement, the \fBusing\fR clause +is used to specify the precise form of the command to which type method +\fIname\fR name is delegated. In this form, the \fBto\fR clause is +optional, since the chosen command might not involve any particular +type component. +.sp +The value of the \fBusing\fR 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: +.CS + + delegate typemethod lostdogs to pound + delegate typemethod lostdogs to pound using "%c %m" + +.CE +.IP +Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string. +.sp +Substitutions: +.RS +.TP +\fB%%\fR +This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c". +.TP +\fB%c\fR +This is replaced with the named type component's command. +.TP +\fB%m\fR +This is replaced with the final token of the type method \fIname\fR; if +the type method \fIname\fR has one token, this is identical to \fB%M\fR. +.TP +\fB%M\fR +This is replaced by the type method \fIname\fR; if the \fIname\fR consists +of multiple tokens, they are joined by space characters. +.TP +\fB%j\fR +This is replaced by the type method \fIname\fR; if the \fIname\fR consists +of multiple tokens, they are joined by underscores ("_"). +.TP +\fB%t\fR +This is replaced with the fully qualified type name. +.RE +.TP +\fBdelegate\fR \fBtypemethod\fR \fB*\fR ?\fBto\fR \fIcomp\fR? ?\fBusing\fR \fIpattern\fR? ?\fBexcept\fR \fIexceptions\fR? +The form \fBdelegate typemethod *\fR delegates all unknown type +method names to the +specified type component. The \fBexcept\fR clause can be used to +specify a list of \fIexceptions\fR, i.e., type method names that will not +be so delegated. The \fBusing\fR clause is defined as given above. +In this form, the statement must contain the \fBto\fR clause, the +\fBusing\fR clause, or both. +.sp +\fBNote:\fR By default, Snit interprets \fB$type foo\fR, where +\fBfoo\fR is +not a defined type method, as equivalent to \fB$type create foo\fR, where +\fBfoo\fR is the name of a new instance of the type. If you +use \fBdelegate typemethod *\fR, then the \fBcreate\fR type +method must always be used explicitly. +.sp +The "*" can be a list of two or more tokens whose last +element is "*", as in the following example: +.CS + + delegate typemethod {tail *} to tail + +.CE +.IP +This implicitly defines the type method \fBtail\fR whose subcommands will +be delegated to the \fBtail\fR type component. +.TP +\fBtypecomponent\fR \fIcomp\fR ?\fB-public\fR \fItypemethod\fR? ?\fB-inherit\fR \fIflag\fR? +Explicitly declares a type component called \fIcomp\fR, 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. +.sp +If the \fB-public\fR option is specified, then the type component is made +public by defining a \fItypemethod\fR whose subcommands are delegated to +the type component, e.g., specifying \fB-public mytypemethod\fR +is equivalent to the following: +.CS + + typecomponent mycomp + delegate typemethod {mytypemethod *} to mycomp + +.CE +.IP +If the \fB-inherit\fR option is specified, then \fIflag\fR must be a +Boolean value; if \fIflag\fR is true then all unknown type methods +will be delegated to this type component. (See the note on "delegate +typemethod *", above.) The name \fB-inherit\fR +implies that this type inherits, in a sense, the behavior of +the type component. That is, \fB-inherit yes\fR is equivalent to: +.CS + + typecomponent mycomp + delegate typemethod * to mycomp + +.CE +.TP +\fBpragma\fR ?\fIoptions...\fR? +The \fBpragma\fR statement provides control over how Snit generates a +type. It takes the following options; in each case, \fIflag\fR must +be a Boolean value recognized by Tcl, e.g., \fB0\fR, \fB1\fR, +\fByes\fR, \fBno\fR, and so +on. +.sp +By setting the \fB-hastypeinfo\fR, \fB-hastypedestroy\fR, and +\fB-hasinstances\fR pragmas to false and defining appropriate +type methods, you can create an ensemble command without any extraneous +behavior. +.RS +.TP +\fB-canreplace\fR \fIflag\fR +If false (the default) Snit will not create an instance of a +\fBsnit::type\fR 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. +.TP +\fB-hastypeinfo\fR \fIflag\fR +If true (the default), the generated type will have a type method +called \fBinfo\fR that is used for type introspection; the \fBinfo\fR +type method is documented below. If false, it will not. +.TP +\fB-hastypedestroy\fR \fIflag\fR +If true (the default), the generated type will have a type method +called \fBdestroy\fR that is used to destroy the type and all of its +instances. The \fBdestroy\fR type method is documented below. If +false, it will not. +.TP +\fB-hastypemethods\fR \fIflag\fR +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. +.sp +This pragma and \fB-hasinstances\fR cannot both be set false. +.TP +\fB-hasinstances\fR \fIflag\fR +If true (the default), the generated type will have a type method +called \fBcreate\fR that is used to create instances of the type, +along with a variety of instance-related features. If false, it will +not. +.sp +This pragma and \fB-hastypemethods\fR cannot both be set false. +.TP +\fB-hasinfo\fR \fIflag\fR +If true (the default), instances of the generated type will have +an instance method called \fBinfo\fR that is used for +instance introspection; the \fBinfo\fR +method is documented below. If false, it will not. +.TP +\fB-simpledispatch\fR \fIflag\fR +This pragma is intended to make simple, heavily-used abstract +data types (e.g., stacks and queues) more efficient. +.sp +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 \fB-simpledispatch yes\fR you +get the following limitations: +.RS +.IP \(bu +Methods cannot be delegated. +.IP \(bu +\fBuplevel\fR and \fBupvar\fR do not work as expected: the +caller's scope is two levels up rather than one. +.IP \(bu +The option-handling methods +(\fBcget\fR, \fBconfigure\fR, and \fBconfigurelist\fR) are very +slightly slower. +.RE +.RE +.TP +\fBexpose\fR \fIcomp\fR +.TP +\fBexpose\fR \fIcomp\fR \fBas\fR \fImethod\fR +\fBDeprecated.\fR To expose component \fIcomp\fR publicly, use +\fBcomponent\fR's \fB-public\fR option. +.TP +\fBonconfigure\fR \fIname\fR \fIarglist\fR \fIbody\fR +\fBDeprecated.\fR Define \fBoption\fR's \fB-configuremethod\fR +option instead. +.sp +As of version 0.95, the following definitions, +.CS + + option -myoption + onconfigure -myoption {value} { + # Code to save the option's value + } + +.CE +.IP +are implemented as follows: +.CS + + option -myoption -configuremethod _configure-myoption + method _configure-myoption {_option value} { + # Code to save the option's value + } + +.CE +.TP +\fBoncget\fR \fIname\fR \fIbody\fR +\fBDeprecated.\fR Define \fBoption\fR's \fB-cgetmethod\fR +option instead. +.sp +As of version 0.95, the following definitions, +.CS + + option -myoption + oncget -myoption { + # Code to return the option's value + } + +.CE +.IP +are implemented as follows: +.CS + + option -myoption -cgetmethod _cget-myoption + method _cget-myoption {_option} { + # Code to return the option's value + } + +.CE +.RE +.TP +\fBsnit::widget\fR \fIname\fR \fIdefinition\fR +This command defines a Snit megawidget type with the specified +\fIname\fR. The \fIdefinition\fR is defined as for \fBsnit::type\fR. +A \fBsnit::widget\fR differs from a \fBsnit::type\fR +in these ways: +.RS +.IP \(bu +Every instance of a \fBsnit::widget\fR has an automatically-created +component called \fBhull\fR, which is normally a Tk frame widget. +Other widgets created as part of the megawidget will be created within +this widget. +.sp +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 +\fBhull\fR. +.IP \(bu +The name of an instance must be valid Tk window name, and the parent +window must exist. +.RE +.IP +A \fBsnit::widget\fR definition can include any of statements allowed +in a \fBsnit::type\fR definition, and may also include the following: +.RS +.TP +\fBwidgetclass\fR \fIname\fR +Sets the \fBsnit::widget\fR's widget class to \fIname\fR, overriding +the default. See \fBThe Tk Option Database\fR for more +information. +.TP +\fBhulltype\fR \fItype\fR +Determines the kind of widget used as the \fBsnit::widget\fR's hull. +The \fItype\fR may be \fBframe\fR (the default), \fBtoplevel\fR, +\fBlabelframe\fR; the qualified equivalents of these, +\fBtk::frame\fR, \fBtk::toplevel\fR, and \fBtk::labelframe\fR; +or, if available, the equivalent Tile widgets: +\fBttk::frame\fR, \fBttk::toplevel\fR, and +\fBttk::labelframe\fR. In practice, any widget that supports the +\fB-class\fR option can be used as a hull widget by +\fBlappend\fR'ing its name to the variable \fBsnit::hulltypes\fR. +.RE +.TP +\fBsnit::widgetadaptor\fR \fIname\fR \fIdefinition\fR +This command defines a Snit megawidget type with the specified name. +It differs from \fBsnit::widget\fR in that the instance's \fBhull\fR +component is not created automatically, but is created in the +constructor and installed using the \fBinstallhull\fR command. Once +the hull is installed, its instance command is renamed and replaced as +with normal \fBsnit::widget\fRs. The original command is again +accessible in the instance variable \fBhull\fR. +.sp +Note that in general it is not possible to change the +\fIwidget class\fR of a \fBsnit::widgetadaptor\fR's hull widget. +.sp +See \fBThe Tk Option Database\fR for information on how +\fBsnit::widgetadaptor\fRs interact with the option database. +.TP +\fBsnit::typemethod\fR \fItype\fR \fIname\fR \fIarglist\fR \fIbody\fR +Defines a new type method (or redefines an existing type method) +for a previously existing \fItype\fR. +.TP +\fBsnit::method\fR \fItype\fR \fIname\fR \fIarglist\fR \fIbody\fR +Defines a new instance method (or redefines an existing instance +method) for a previously existing \fItype\fR. Note that delegated +instance methods can't be redefined. +.TP +\fBsnit::macro\fR \fIname\fR \fIarglist\fR \fIbody\fR +Defines a Snit macro with the specified \fIname\fR, \fIarglist\fR, and +\fIbody\fR. Macros are used to define new type and widget +definition statements in terms of the statements defined in this man +page. +.sp +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 +\fBMacros and Meta-programming\fR for more details. +.sp +The macro \fIname\fR cannot be the same as any standard Tcl command, +or any Snit type or widget definition statement, e.g., you can't +redefine the \fBmethod\fR or \fBdelegate\fR statements, or the +standard \fBset\fR, \fBlist\fR, or \fBstring\fR commands. +.TP +\fBsnit::compile\fR \fIwhich\fR \fItype\fR \fIbody\fR +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. +.sp +This command exposes the "compiler". Given a definition \fIbody\fR +for the named \fItype\fR, where \fIwhich\fR is \fBtype\fR, +\fBwidget\fR, or \fBwidgetadaptor\fR, \fBsnit::compile\fR returns a list +of two elements. The first element is the fully qualified type name; +the second element is the definition script. +.sp +\fBsnit::compile\fR 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. +.PP +.SS "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: +.PP +.TP +\fB$type\fR \fItypemethod\fR \fIargs\fR... +The \fItypemethod\fR can be any of the +\fBStandard Type Methods\fR (e.g., \fBcreate\fR), +or any type method defined in the type +definition. +The subsequent \fIargs\fR depend on the specific \fItypemethod\fR +chosen. +.sp +The type command is most often used to create new instances of the +type; hence, the \fBcreate\fR method is assumed if the first +argument to the type command doesn't name a valid type method, unless +the type definition includes \fBdelegate typemethod *\fR or the +\fB-hasinstances\fR pragma is set to false. +.sp +Furthermore, if the \fB-hastypemethods\fR 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 +\fB-hastypemethods\fR pragma is false and the type +has instances, the following commands are equivalent: +.CS + +snit::type dog { ... } + +set mydog [dog create %AUTO%] +set mydog [dog %AUTO%] +set mydog [dog] + +.CE +.IP +This doesn't work for Snit widgets, for obvious reasons. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the above behavior is +available whether \fB-hastypemethods\fR is true (the default) or false. +.PP +.SS "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: +.PP +.TP +\fB$type\fR \fBcreate\fR \fIname\fR ?\fIoption\fR \fIvalue\fR ...? +Creates a new instance of the type, giving it the specified \fIname\fR +and calling the type's constructor. +.sp +For \fBsnit::type\fRs, if \fIname\fR is not a fully-qualified command +name, it is assumed to be a name in the namespace in which the call to +\fBsnit::type\fR appears. The method returns the fully-qualified +instance name. +.sp +For \fBsnit::widget\fRs and \fBsnit::widgetadaptor\fRs, \fIname\fR +must be a valid widget name; the method returns the widget name. +.sp +So long as \fIname\fR does not conflict with any defined type method +name the \fBcreate\fR keyword may be omitted, unless +the type definition includes \fBdelegate typemethod *\fR or the +\fB-hasinstances\fR pragma is set to false. +.sp +If the \fIname\fR includes the string \fB%AUTO%\fR, it will be +replaced with the string \fB$type$counter\fR where \fB$type\fR is +the type name and \fB$counter\fR is a counter that increments each +time \fB%AUTO%\fR is used for this type. +.sp +By default, any arguments following the \fIname\fR will be a list of +\fIoption\fR names and their \fIvalue\fRs; however, a type's +constructor can specify a different argument list. +.sp +As of Snit V0.95, \fBcreate\fR will throw an error if the \fIname\fR +is the same as any existing command--note that this was always true +for \fBsnit::widget\fRs and \fBsnit::widgetadaptor\fRs. You can +restore the previous behavior using the \fB-canreplace\fR pragma. +.TP +\fB$type\fR \fBinfo typevars\fR ?\fIpattern\fR? +Returns a list of the type's type variables (excluding Snit internal +variables); all variable names are fully-qualified. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.TP +\fB$type\fR \fBinfo typemethods\fR ?\fIpattern\fR? +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. +.sp +If the type +definition includes \fBdelegate typemethod *\fR, 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. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.TP +\fB$type\fR \fBinfo args\fR \fImethod\fR +Returns a list containing the names of the arguments to the type's +\fImethod\fR, in order. This method cannot be applied to delegated +type methods. +.TP +\fB$type\fR \fBinfo body\fR \fImethod\fR +Returns the body of typemethod \fImethod\fR. This method cannot be +applied to delegated type methods. +.TP +\fB$type\fR \fBinfo default\fR \fImethod\fR \fIaname\fR \fIvarname\fR +Returns a boolean value indicating whether the argument \fIaname\fR of +the type's \fImethod\fR has a default value (\fBtrue\fR) or not +(\fBfalse\fR). If the argument has a default its value is placed into +the variable \fIvarname\fR. +.TP +\fB$type\fR \fBinfo instances\fR ?\fIpattern\fR? +Returns a list of the type's instances. For \fBsnit::type\fRs, it +will be a list of fully-qualified instance names; +for \fBsnit::widget\fRs, it will be a list of Tk widget names. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value. +.TP +\fB$type\fR \fBdestroy\fR +Destroys the type's instances, the type's namespace, and the type +command itself. +.PP +.SS "THE INSTANCE COMMAND" +A Snit type or widget's \fBcreate\fR 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: +.PP +.TP +\fB$object\fR \fImethod\fR \fIargs...\fR +The \fImethod\fR can be any of the +\fBStandard Instance Methods\fR, or any instance method +defined in the type definition. +The subsequent \fIargs\fR depend on the specific \fImethod\fR chosen. +.PP +.SS "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: +.PP +.TP +\fB$object\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue\fR? ... +Assigns new values to one or more options. If called with one +argument, an \fIoption\fR 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. +.sp +Warning: This information will be available for delegated options only +if the component to which they are delegated has a \fBconfigure\fR +method that returns this same kind of information. +.sp +Note: Snit defines this method only if the type has at least one +option. +.TP +\fB$object\fR \fBconfigurelist\fR \fIoptionlist\fR +Like \fBconfigure\fR, but takes one argument, a list of options and +their values. It's mostly useful in the type constructor, but can be +used anywhere. +.sp +Note: Snit defines this method only if the type has at least one +option. +.TP +\fB$object\fR \fBcget\fR \fIoption\fR +Returns the option's value. +.sp +Note: Snit defines this method only if the type has at least one +option. +.TP +\fB$object\fR \fBdestroy\fR +Destroys the object, calling the \fBdestructor\fR and freeing all +related memory. +.sp +\fINote:\fR +The \fBdestroy\fR method isn't defined for \fBsnit::widget\fR or +\fBsnit::widgetadaptor\fR objects; instances of these are destroyed by +calling \fBTk\fR's \fBdestroy\fR command, just as normal +widgets are. +.TP +\fB$object\fR \fBinfo type\fR +Returns the instance's type. +.TP +\fB$object\fR \fBinfo vars\fR ?\fIpattern\fR? +Returns a list of the object's instance variables (excluding Snit +internal variables). The names are fully qualified. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.TP +\fB$object\fR \fBinfo typevars\fR ?\fIpattern\fR? +Returns a list of the object's type's type variables (excluding Snit +internal variables). The names are fully qualified. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.TP +\fB$object\fR \fBinfo typemethods\fR ?\fIpattern\fR? +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. +.sp +If the type +definition includes \fBdelegate typemethod *\fR, 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. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value. +.TP +\fB$object\fR \fBinfo options\fR ?\fIpattern\fR? +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 \fB$object configure\fR like Tk widgets do, +then the result will include all possible unknown options that can +be delegated to the component. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.sp +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. +.TP +\fB$object\fR \fBinfo methods\fR ?\fIpattern\fR? +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. +.sp +If the type +definition includes \fBdelegate method *\fR, 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. +.sp +If \fIpattern\fR is given, it's used as a \fBstring match\fR +pattern; only names that match the pattern are returned. +.sp +\fISnit 1.x Incompatibility:\fR In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value. +.TP +\fB$object\fR \fBinfo args\fR \fImethod\fR +Returns a list containing the names of the arguments to the instance's +\fImethod\fR, in order. This method cannot be applied to delegated methods. +.TP +\fB$object\fR \fBinfo body\fR \fImethod\fR +Returns the body of the instance's method \fImethod\fR. This method +cannot be applied to delegated methods. +.TP +\fB$object\fR \fBinfo default\fR \fImethod\fR \fIaname\fR \fIvarname\fR +Returns a boolean value indicating whether the argument \fIaname\fR of +the instance's \fImethod\fR has a default value (\fBtrue\fR) or not +(\fBfalse\fR). If the argument has a default its value is placed into +the variable \fIvarname\fR. +.PP +.SS "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. +.TP +\fBmymethod\fR \fIname\fR ?\fIargs...\fR? +The \fBmymethod\fR command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke method \fIname\fR 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 +\fBdosomething\fR method to be called when the \fB$button\fR is pressed: +.CS + + $button configure -command [list $self dosomething myargument] + + $button configure -command [mymethod dosomething myargument] + +.CE +.IP +The chief distinction between the two is that the latter form will not +break if the object's command is renamed. +.TP +\fBmytypemethod\fR \fIname\fR ?\fIargs...\fR? +The \fBmytypemethod\fR command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke type method \fIname\fR 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 \fBdosomething\fR type method +to be called when \fB$button\fR is pressed: +.CS + + $button configure -command [list $type dosomething myargument] + + $button configure -command [mytypemethod dosomething myargument] + +.CE +.IP +Type commands cannot be renamed, so in practice there's little +difference between the two forms. \fBmytypemethod\fR is provided for +parallelism with \fBmymethod\fR. +.TP +\fBmyproc\fR \fIname\fR ?\fIargs...\fR? +The \fBmyproc\fR 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 \fIname\fR 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 \fBdosomething\fR proc +to be called when \fB$button\fR is pressed: +.CS + + $button configure -command [list ${type}::dosomething myargument] + + $button configure -command [myproc dosomething myargument] + +.CE +.TP +\fBmyvar\fR \fIname\fR +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 \fB-textvariable\fR to a Tk label widget. +.TP +\fBmytypevar\fR \fIname\fR +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 +\fB-textvariable\fR to a Tk label widget. +.TP +\fBfrom\fR \fIargvName\fR \fIoption\fR ?\fIdefvalue\fR? +The \fBfrom\fR command plucks an option value from a list of options +and their values, such as is passed into a type's \fBconstructor\fR. +\fIargvName\fR must be the name of a variable containing such a list; +\fIoption\fR is the name of the specific option. +.sp +\fBfrom\fR looks for \fIoption\fR in the option list. If it is found, +it and its value are removed from the list, and the value is returned. +If \fIoption\fR doesn't appear in the list, then the \fIdefvalue\fR is +returned. +If the option is locally-defined option, and \fIdefvalue\fR is +not specified, then the option's default value as specified in the +type definition will be returned instead. +.TP +\fBinstall\fR \fIcompName\fR \fBusing\fR \fIobjType\fR \fIobjName\fR \fIargs...\fR +Creates a new object of type \fIobjType\fR called \fIobjName\fR +and installs it as component \fIcompName\fR, +as described in \fBComponents and Delegation\fR. Any additional +\fIargs...\fR are passed along with the name to the \fIobjType\fR +command. +If this is a \fBsnit::type\fR, then the following two commands are +equivalent: +.CS + + install myComp using myObjType $self.myComp args... + + set myComp [myObjType $self.myComp args...] + +.CE +.IP +Note that whichever method is used, \fIcompName\fR must still be +declared in the type definition using \fBcomponent\fR, or must be +referenced in at least one \fBdelegate\fR statement. +.sp +If this is a \fBsnit::widget\fR or \fBsnit::widgetadaptor\fR, and if +options have been delegated to component \fIcompName\fR, 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 \fBThe Tk Option Database\fR for more +information. +.sp +\fBinstall\fR cannot be used to install type components; just assign +the type component's command name to the type component's variable +instead. +.TP +\fBinstallhull\fR \fBusing\fR \fIwidgetType\fR \fIargs...\fR +.TP +\fBinstallhull\fR \fIname\fR +The constructor of a \fBsnit::widgetadaptor\fR 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 \fB$win\fR. +This command has two forms. +.sp +The first form specifies the \fIwidgetType\fR and the \fIargs...\fR +(that is, the hardcoded option list) to use in creating the hull. +Given this form, \fBinstallhull\fR creates the hull widget, and +initializes any options delegated to the hull from the Tk option +database. +.sp +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 +\fInot\fR 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 \fBBWidgets\fR tabbed notebook or pages manager widget. +.sp +See \fBThe Tk Option Database\fR for more information +about \fBsnit::widgetadaptor\fRs and the option database. +.TP +\fBvariable\fR \fIname\fR +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 \fBvariable\fR 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. +.sp +It's generally clearest to define all instance variables in the type +definition, and omit declaring them in methods and so forth. +.sp +Note that this is an instance-specific version of the standard Tcl +\fB::variable\fR command. +.TP +\fBtypevariable\fR \fIname\fR +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 \fBtypevariable\fR to declare type +variables that don't appear in the type definition. +.sp +It's generally clearest to declare all type variables in the type +definition, and omit declaring them in methods, type methods, etc. +.TP +\fBvarname\fR \fIname\fR +\fBDeprecated.\fR Use \fBmyvar\fR instead. +.sp +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 \fB-textvariable\fR to a Tk label widget. +.TP +\fBtypevarname\fR \fIname\fR +\fBDeprecated.\fR Use \fBmytypevar\fR instead. +.sp +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 +\fB-textvariable\fR to a Tk label widget. +.TP +\fBcodename\fR \fIname\fR +\fBDeprecated.\fR Use \fBmyproc\fR 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. +.PP +.PP +.SS "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 +\fBcomponent\fR, which creates a component instance variable. +In the following example, a \fBdog\fR object has a +\fBtail\fR object: +.PP +.CS + + 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."} + } + +.CE +.PP +Because the \fBtail\fR object's name is stored in an instance +variable, it's easily accessible in any method. +.PP +The \fBinstall\fR command provides an alternate way +to create and install the component: +.PP +.CS + + snit::type dog { + component mytail + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + + method wag {} { + $mytail wag + } + } + +.CE +.PP +For \fBsnit::type\fRs, the two methods are equivalent; for +\fBsnit::widget\fRs and \fBsnit::widgetadaptor\fRs, the \fBinstall\fR +command properly initializes the widget's options by querying +\fBThe Tk Option Database\fR. +.PP +In the above examples, the \fBdog\fR object's \fBwag\fR method +simply calls the \fBtail\fR component's \fBwag\fR method. In OO +jargon, this is called delegation. Snit provides an easier way to do +this: +.PP +.CS + + snit::type dog { + delegate method wag to mytail + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } + } + +.CE +.PP +The \fBdelegate\fR statement in the type definition implicitly defines +the instance variable \fBmytail\fR to hold the component's name +(though it's good form to use \fBcomponent\fR to declare it explicitly); it +also defines the \fBdog\fR object's \fBwag\fR method, delegating it +to the \fBmytail\fR component. +.PP +If desired, all otherwise unknown methods can be delegated to a +specific component: +.PP +.CS + + + snit::type dog { + delegate method * to mytail + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } + + method bark { return "Bark, bark, bark!" } + } + +.CE +.PP +In this case, a \fBdog\fR object will handle its own \fBbark\fR +method; but \fBwag\fR will be passed along to \fBmytail\fR. Any +other method, being recognized by neither \fBdog\fR nor \fBtail\fR, +will simply raise an error. +.PP +Option delegation is similar to method delegation, except for the +interactions with the Tk option database; this is described in +\fBThe Tk Option Database\fR. +.SS "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. +.PP +Just as \fBdelegate method\fR can be used to delegate methods to +instance components, as described in +\fBComponents and Delegation\fR, so \fBdelegate typemethod\fR +can be used to delegate type methods to type components. +.PP +Note also that as of Snit 0.95 \fBdelegate method\fR can delegate +methods to both instance components and type components. +.SS "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 \fIPractical Programming in Tcl and Tk\fR +by Welch et al has a good introduction to the option database, as does +\fIEffective Tcl/Tk Programming\fR. +.PP +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. +.PP +.IP \(bu +If the \fBsnit::widget\fR's default widget class is not what is desired, set it +explicitly using \fBwidgetclass\fR in the widget definition. +.IP \(bu +When defining or delegating options, specify the resource and class +names explicitly when if the defaults aren't what you want. +.IP \(bu +Use \fBinstallhull using\fR to install the hull for +\fBsnit::widgetadaptor\fRs. +.IP \(bu +Use \fBinstall\fR to install all other components. +.PP +.PP +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. +.PP +\fBSetting the widget class:\fR 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 +\fBbutton\fR widgets is "Button". +.PP +Similarly, the widget class of a \fBsnit::widget\fR defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of +.PP +.CS + + snit::widget ::mylibrary::scrolledText { ... } +.CE +.PP +is "ScrolledText". The widget class can also be set explicitly using +the \fBwidgetclass\fR statement within the \fBsnit::widget\fR +definition. +.PP +Any widget can be used as the \fBhulltype\fR provided that it supports +the \fB-class\fR option for changing its widget class name. See +the discussion of the \fBhulltype\fR command, above. The user may pass +\fB-class\fR to the widget at instantion. +.PP +The widget class of a \fBsnit::widgetadaptor\fR is just the widget +class of its hull widget; this cannot be changed unless the hull +widget supports \fB-class\fR, in which case it will +usually make more sense to use \fBsnit::widget\fR rather than +\fBsnit::widgetadaptor\fR. +.PP +\fBSetting option resource names and classes:\fR 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 \fBconfigure\fR and +\fBcget\fR commands. +.PP +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 +\fBtext\fR widget options: +.PP +.CS + + -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad + +.CE +.PP +As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always. +.PP +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: +.PP +.CS + + snit::widget mywidget { + option -background + delegate option -borderwidth to hull + delegate option * to text + # ... + } + +.CE +.PP +In this case, the widget class name is "Mywidget". The widget has the +following options: \fB-background\fR, which is locally defined, and +\fB-borderwidth\fR, which is explicitly delegated; all other widgets are +delegated to a component called "text", which is probably a Tk +\fBtext\fR widget. If so, \fBmywidget\fR has all the same options as +a \fBtext\fR widget. The option, resource, and class names are as +follows: +.PP +.CS + + -background background Background + -borderwidth borderwidth Borderwidth + -padx padX Pad + +.CE +.PP +Note that the locally defined option, \fB-background\fR, happens to have +the same three names as the standard Tk \fB-background\fR option; and +\fB-pad\fR, which is delegated implicitly to the \fBtext\fR +component, has the +same three names for \fBmywidget\fR as it does for the \fBtext\fR +widget. \fB-borderwidth\fR, 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: +.PP +.CS + + snit::widget mywidget { + option -background + delegate option {-borderwidth borderWidth} to hull + delegate option * to text + # ... + } + +.CE +.PP +The class name will default to "BorderWidth", as expected. +.PP +Suppose, however, that \fBmywidget\fR also delegated +\fB-padx\fR and +\fB-pady\fR to the hull. In this case, both the resource name and the +class name must be specified explicitly: +.PP +.CS + + 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 + # ... + } + +.CE +.PP +\fBQuerying the option database:\fR 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. +.PP +\fBInitializing locally defined options:\fR +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, +.PP +.CS + + option add *Mywidget.texture pebbled + + snit::widget mywidget { + option -texture smooth + # ... + } + + mywidget .mywidget -texture greasy + +.CE +.PP +Here, \fB-texture\fR 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". +.PP +\fBInitializing options delegated to the hull:\fR +A \fBsnit::widget\fR'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: +.PP +.CS + + 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] + +.CE +.PP +The question is, what are the values of variables A, B, C and D? +.PP +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 \fB-relief\fR +option is implicitly delegated to the hull, Snit takes no action. +.PP +The value of B is "red". The hull will automatically pick up the +value "green" for its \fB-background\fR option, just as it picked up the +\fB-relief\fR value. However, Snit knows that +\fB-hullbackground\fR is mapped to +the hull's \fB-background\fR option; hence, it queries the option database +for \fB-hullbackground\fR and gets "red" and updates the hull +accordingly. +.PP +The value of C is also "red", because \fB-background\fR is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +\fB-hullbackground\fR. Note that this case is unusual; in practice, +\fB-background\fR would probably be explicitly delegated to some other +component. +.PP +The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for \fB-borderwidth\fR +defaults to "borderwidth", whereas the option database entry is +"borderWidth". As with \fB-relief\fR, the hull picks up its +own \fB-borderwidth\fR 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. +.PP +For \fBsnit::widgetadaptor\fRs, 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 \fBsnit::widgetadaptor\fR +must call \fBinstallhull\fR in its constructor. The normal way to do +this is as follows: +.PP +.CS + + snit::widgetadaptor mywidget { + # ... + constructor {args} { + # ... + installhull using text -foreground white + # + } + #... + } + +.CE +.PP +In this case, the \fBinstallhull\fR command will create the hull using +a command like this: +.PP +.CS + + set hull [text $win -foreground white] + +.CE +.PP +The hull is a \fBtext\fR widget, so its widget class is "Text". Just +as with \fBsnit::widget\fR 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. +.PP +\fBInitializing options delegated to other components:\fR +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 \fBinstall\fR command is used to create it. +.PP +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: +.PP +.CS + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + set myComp [text $win.text -foreground black] + } + } + +.CE +.PP +The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used: +.PP +.CS + + snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + install myComp using text $win.text -foreground black + } + } + +.CE +.PP +The \fBinstall\fR command does the following: +.PP +.IP \(bu +Builds a list of the options explicitly included in the \fBinstall\fR +command -- in this case, \fB-foreground\fR. +.IP \(bu +Queries the option database for all options delegated explicitly to +the named component. +.IP \(bu +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 (\fB-foreground\fR) will override +anything read from the option database. +.IP \(bu +If the widget definition implicitly delegated options to the component +using \fBdelegate option *\fR, then Snit calls the newly created +component's \fBconfigure\fR 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 \fBinstall\fR command. For all such options, Snit +queries the option database and configures the component accordingly. +.PP +.PP +\fBNon-widget components:\fR The option database is never queried +for \fBsnit::type\fRs, since it can only be queried given a Tk widget +name. +However, \fBsnit::widget\fRs can have non-widget components. And if +options are delegated to those components, and if the \fBinstall\fR +command is used to install those components, then they will be +initialized from the option database just as widget components are. +.PP +.SS "MACROS AND META-PROGRAMMING" +The \fBsnit::macro\fR 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: +.CS + + snit::type dog { + variable mood happy + + method getmood {} { + return $mood + } + + method setmood {newmood} { + set mood $newmood + } + } + +.CE +That's nine lines of text per property. Or, you could define the +following \fBsnit::macro\fR: +.CS + + snit::macro property {name initValue} { + variable $name $initValue + + method get$name {} "return $name" + + method set$name {value} "set $name \\$value" + } + +.CE +Note that a \fBsnit::macro\fR 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. +.PP +Given this new macro, you can define a property in one line of code: +.CS + + snit::type dog { + property mood happy + } + +.CE +Within a macro, the commands \fBvariable\fR and \fBproc\fR refer to +the Snit type-definition commands, not the standard Tcl commands. To +get the standard Tcl commands, use \fB_variable\fR and \fB_proc\fR. +.PP +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 \fBsnit::macro\fRs, define them in your package +namespace: +.CS + + snit::macro mypkg::property {name initValue} { ... } + + snit::type dog { + mypkg::property mood happy + } + +.CE +This leaves the global namespace open for application authors. +.PP +.SS "VALIDATION TYPES" +A validation type is an object that can be used to validate +Tcl values of a particular kind. For example, +\fBsnit::integer\fR is used to validate that a Tcl value is +an integer. +.PP +Every validation type has a \fBvalidate\fR 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: +.CS + + snit::integer validate 5 ;# Does nothing + snit::integer validate 5.0 ;# Throws an error (not an integer!) + +.CE +.PP +The \fBvalidate\fR method will always return the validated value on success, +and throw the \fB-errorcode\fR INVALID on error. +.PP +Snit defines a family of validation types, all of which are +implemented as \fBsnit::type\fR'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: +.CS + + snit::double probability -min 0.0 -max 1.0 + +.CE +The example above creates an instance of \fBsnit::double\fR--a +validation subtype--called +\fBprobability\fR, which can be used to validate probability values: +.CS + + probability validate 0.5 ;# Does nothing + probability validate 7.9 ;# Throws an error + +.CE +Validation subtypes can be defined explicitly, as in the above +example; when a locally-defined option's \fB-type\fR is specified, +they may also be created on the fly: +.CS + + 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 + } + +.CE +.PP +Any object that has a \fBvalidate\fR method with the semantics +described above can be used as a validation type; see +\fBDefining Validation Types\fR for information on how to define +new ones. +.PP +Snit defines the following validation types: +.TP +\fBsnit::boolean\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::boolean\fR \fIname\fR +Validates Tcl boolean values: 1, 0, \fBon\fR, \fBoff\fR, +\fByes\fR, \fBno\fR, \fBtrue\fR, \fBfalse\fR. +It's possible to define subtypes--that is, instances--of +\fBsnit::boolean\fR, but as it has no options there's no reason to do +so. +.TP +\fBsnit::double\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::double\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +Validates floating-point values. Subtypes may be created with the +following options: +.RS +.TP +\fB-min\fR \fImin\fR +Specifies a floating-point minimum bound; a value is invalid if it is strictly +less than \fImin\fR. +.TP +\fB-max\fR \fImax\fR +Specifies a floating-point maximum bound; a value is invalid if it is strictly +greater than \fImax\fR. +.RE +.TP +\fBsnit::enum\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::enum\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +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: +.RS +.TP +\fB-values\fR \fIlist\fR +Specifies a list of valid values. A value is valid if and only if +it's included in the list. +.RE +.TP +\fBsnit::fpixels\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::fpixels\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +\fITk programs only.\fR Validates screen distances, in any of the +forms accepted by \fBwinfo fpixels\fR. Subtypes may be created with the +following options: +.RS +.TP +\fB-min\fR \fImin\fR +Specifies a minimum bound; a value is invalid if it is strictly +less than \fImin\fR. The bound may be expressed in any of the +forms accepted by \fBwinfo fpixels\fR. +.TP +\fB-max\fR \fImax\fR +Specifies a maximum bound; a value is invalid if it is strictly +greater than \fImax\fR. The bound may be expressed in any of the +forms accepted by \fBwinfo fpixels\fR. +.RE +.TP +\fBsnit::integer\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::integer\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +Validates integer values. Subtypes may be created with the +following options: +.RS +.TP +\fB-min\fR \fImin\fR +Specifies an integer minimum bound; a value is invalid if it is strictly +less than \fImin\fR. +.TP +\fB-max\fR \fImax\fR +Specifies an integer maximum bound; a value is invalid if it is strictly +greater than \fImax\fR. +.RE +.TP +\fBsnit::listtype\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::listtype\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +Validates Tcl lists. Subtypes may be created with the +following options: +.RS +.TP +\fB-minlen\fR \fImin\fR +Specifies a minimum list length; the value is invalid if it has +fewer than \fImin\fR elements. Defaults to 0. +.TP +\fB-maxlen\fR \fImax\fR +Specifies a maximum list length; the value is invalid if it +more than \fImax\fR elements. +.TP +\fB-type\fR \fItype\fR +Specifies the type of the list elements; \fItype\fR must be +the name of a validation type or subtype. In the +following example, the value of \fB-numbers\fR must be a list +of integers. +.CS + + option -numbers -type {snit::listtype -type snit::integer} + +.CE +.IP +Note that this option doesn't support defining new validation subtypes +on the fly; that is, the following code will not work (yet, anyway): +.CS + + option -numbers -type { + snit::listtype -type {snit::integer -min 5} + } + +.CE +.IP +Instead, define the subtype explicitly: +.CS + + snit::integer gt4 -min 5 + + snit::type mytype { + option -numbers -type {snit::listtype -type gt4} + } + +.CE +.RE +.TP +\fBsnit::pixels\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::pixels\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +\fITk programs only.\fR Validates screen distances, in any of the +forms accepted by \fBwinfo pixels\fR. Subtypes may be created with the +following options: +.RS +.TP +\fB-min\fR \fImin\fR +Specifies a minimum bound; a value is invalid if it is strictly +less than \fImin\fR. The bound may be expressed in any of the +forms accepted by \fBwinfo pixels\fR. +.TP +\fB-max\fR \fImax\fR +Specifies a maximum bound; a value is invalid if it is strictly +greater than \fImax\fR. The bound may be expressed in any of the +forms accepted by \fBwinfo pixels\fR. +.RE +.TP +\fBsnit::stringtype\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::stringtype\fR \fIname\fR ?\fIoption\fR \fIvalue\fR...? +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: +.RS +.TP +\fB-minlen\fR \fImin\fR +Specifies a minimum string length; the value is invalid if it has +fewer than \fImin\fR characters. Defaults to 0. +.TP +\fB-maxlen\fR \fImax\fR +Specifies a maximum string length; the value is invalid if it has +more than \fImax\fR characters. +.TP +\fB-glob\fR \fIpattern\fR +Specifies a \fBstring match\fR pattern; the value is invalid +if it doesn't match the pattern. +.TP +\fB-regexp\fR \fIregexp\fR +Specifies a regular expression; the value is invalid if it doesn't +match the regular expression. +.TP +\fB-nocase\fR \fIflag\fR +By default, both \fB-glob\fR and \fB-regexp\fR matches are +case-sensitive. If \fB-nocase\fR is set to true, then both +\fB-glob\fR and \fB-regexp\fR matches are case-insensitive. +.RE +.TP +\fBsnit::window\fR \fBvalidate\fR ?\fIvalue\fR? +.TP +\fBsnit::window\fR \fIname\fR +\fITk programs only.\fR Validates Tk window names. The value must +cause \fBwinfo exists\fR to return true; otherwise, the value is +invalid. It's possible to define subtypes--that is, instances--of +\fBsnit::window\fR, but as it has no options at present there's no +reason to do so. +.PP +.PP +.SS "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 \fBValidation Types\fR. +.PP +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 \fBvalidate\fR method; the \fBvalidate\fR +method must take one argument, a value, return the value if it is +valid, and throw an error with \fB-errorcode\fR INVALID if the +value is invalid. This can be done with a simple \fBproc\fR. For +example, the \fBsnit::boolean\fR validate type could have been +implemented like this: +.CS + + 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 + } + +.CE +A validation type defined in this way cannot be subtyped, of course; +but for many applications this will be sufficient. +.PP +Finally, one can define a full-fledged, subtype-able validation type +as a \fBsnit::type\fR. Here's a skeleton to get you started: +.CS + + 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 + } + } + +.CE +And now you have a type that can be subtyped. +.PP +The file "validate.tcl" in the Snit distribution defines all of Snit's +validation types; you can find the complete implementation for +\fBsnit::integer\fR and the other types there, to use as examples for +your own types. +.PP +.SH 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 at the +SourceForge trackers for tcllib, which can be found at +\fIhttp://sourceforge.net/projects/tcllib/\fR. +The relevant category is \fIsnit\fR. +.PP +Additionally, you might wish to join the Snit mailing list; +see \fIhttp://www.wjduquette.com/snit\fR for details. +.PP +One particular area to watch is using \fBsnit::widgetadaptor\fR to +adapt megawidgets created by other megawidget packages; correct +widget destruction depends on the order of the <Destroy> bindings. +The wisest course is simply not to do this. +.SH "KNOWN BUGS" +.IP \(bu +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. +.IP \(bu +Also see the SourceForge Trackers at +\fIhttp://sourceforge.net/projects/tcllib/\fR, category \fIsnit\fR. +.PP +.SH HISTORY +During the course of developing Notebook +(See \fIhttp://www.wjduquette.com/notebook\fR), 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 \fIhttp://www.wjduquette.com/tcl/objects.html\fR), 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. +.PP +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. +.PP +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. +.PP +If you have any comments or suggestions (or bug reports!) don't +hesitate to send me e-mail at \fIwill@wjduquette.com\fR. In addition, +there's a Snit mailing list; you can find out more about it at the +Snit home page (see \fIhttp://www.wjduquette.com/snit\fR). +.PP +.SH 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsnit\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +BWidget, C++, Incr Tcl, Snit, adaptors, class, mega widget, object, object oriented, type, widget, widget adaptors +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2009, by William H. Duquette + +.fi ADDED embedded/man/files/modules/snit/snitfaq.n Index: embedded/man/files/modules/snit/snitfaq.n ================================================================== --- /dev/null +++ embedded/man/files/modules/snit/snitfaq.n @@ -0,0 +1,3786 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/snit/snitfaq.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2006, by William H. Duquette +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "snitfaq" n 2.2 tcllib "Snit's Not Incr Tcl, OO system" +.BS +.SH NAME +snitfaq \- Snit Frequently Asked Questions +.SH DESCRIPTION +.PP +.SH OVERVIEW +.SS "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 \fBsnit\fR man page. +.SS "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. +.PP +The primary purpose of Snit is to be \fIobject glue\fR--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. +.PP +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. +.PP +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 \fIis\fR 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. +.PP +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. +.SS "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 \fBSNIT VERSIONS\fR for the differences between Snit +1.3 and Snit 2.2. +.SS "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, +\fIhttp://www.wjduquette.com/snit\fR. +.SS "WHAT ARE SNIT'S GOALS?" +.PP +.IP \(bu +A Snit object should be at least as efficient as a hand-coded Tcl +object (see \fIhttp://www.wjduquette.com/tcl/objects.html\fR). +.IP \(bu +The fact that Snit was used in an object's implementation should be +transparent (and irrelevant) to clients of that object. +.IP \(bu +Snit should be able to encapsulate objects from other sources, +particularly Tk widgets. +.IP \(bu +Snit megawidgets should be (to the extent possible) indistinguishable +in interface from Tk widgets. +.IP \(bu +Snit should be Tclish--that is, rather than trying to emulate C++, +Smalltalk, or anything else, it should try to emulate Tcl itself. +.IP \(bu +It should have a simple, easy-to-use, easy-to-remember syntax. +.PP +.SS "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. +.PP +Note that you can achieve the effect of inheritance using +\fBCOMPONENTS\fR and \fBDELEGATION\fR--and you can inherit +from anything that looks like a Tcl object. +.SS "WHAT CAN I DO WITH SNIT?" +Using Snit, a programmer can: +.IP \(bu +Create abstract data types and Tk megawidgets. +.IP \(bu +Define instance variables, type variables, and Tk-style options. +.IP \(bu +Define constructors, destructors, instance methods, type methods, procs. +.IP \(bu +Assemble a type out of component types. Instance methods and options +can be delegated to the component types automatically. +.PP +.SH "SNIT VERSIONS" +.SS "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. +.PP +Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but +requires only Tcl 8.3 and later. +.PP +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. +.SS "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: +.CS + +package require snit 1.3 + +.CE +To always use Snit 2.2 (or a later version of Snit 2.x), say this +instead: +.CS + +package require snit 2.2 + +.CE +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. +.PP +If you wish your application to always use the latest available +version of Snit, don't specify a version number: +.CS + +package require snit + +.CE +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. +.SS "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 +\fBnamespace ensemble\fR 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. +.PP +There are four specific incompatibilities between Snit 1.3 and Snit 2.2. +.PP +.IP \(bu +Snit 1.3 supports implicit naming of objects. Suppose you define a +new \fBsnit::type\fR called \fBdog\fR. You can create instances of +\fBdog\fR in three ways: +.CS + +dog spot ;# Explicit naming +set obj1 [dog %AUTO%] ;# Automatic naming +set obj2 [dog] ;# Implicit naming + +.CE +.IP +In Snit 2.2, type commands are defined using the \fBnamespace ensemble\fR +mechanism; and \fBnamespace ensemble\fR doesn't allow an ensemble command +to be called without a subcommand. In short, using +\fBnamespace ensemble\fR there's no way to support implicit naming. +.sp +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 +\fBnamespace ensemble\fR is not used. In this case, implicit naming +is still possible. +.sp +In short, you can have implicit naming if you're willing to do without +type methods (including the standard type methods, like +\fB$type info\fR). To do so, use the \fB-hastypemethods\fR pragma: +.CS + +pragma -hastypemethods 0 +.CE +.IP \(bu +Hierarchical methods and type methods are implemented differently in +Snit 2.2. +.sp +A hierarchical method is an instance method which has +subcommands; these subcommands are themselves methods. The Tk text +widget's \fBtag\fR 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: +.CS + +method {tag configure} {tag args} { ... } + +method {tag cget} {tag option} {...} + +.CE +.IP +Here we've implicitly defined a \fBtag\fR method which has two +subcommands, \fBconfigure\fR and \fBcget\fR. +.sp +In Snit 1.3, hierarchical methods could be called in two ways: +.CS + +$obj tag cget -myoption ;# The good way +$obj {tag cget} -myoption ;# The weird way + +.CE +.IP +In the second call, we see that a hierarchical method or type method +is simply one whose name contains multiple words. +.sp +In Snit 2.2 this is no longer the case, and the "weird" way of calling +hierarchical methods and type methods no longer works. +.IP \(bu +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, \fB$obj info methods\fR returned the +full names of all hierarchical methods. In the example above, +the list returned by \fB$obj info methods\fR would include +\fBtag configure\fR and \fBtag cget\fR but not \fBtag\fR, since +\fBtag\fR is defined only implicitly. +.sp +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 \fB$obj info methods\fR would include \fBtag\fR but not +\fBtag configure\fR or \fBtag cget\fR. +.IP \(bu +The fourth incompatibility is due to a new feature. Snit 2.2 uses +the new \fBnamespace path\fR 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 \fBmypackage\fR which defines a number of commands +including a type, \fB::mypackage::mytype\fR. Thanks to +\fBnamespace path\fR, the type's code can call any of the other +commands defined in \fB::mypackage::\fR. +.sp +This is extremely convenient. However, it also means that commands +defined in the parent namespace, \fB::mypackage::\fR 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 +\fB::tie::std::file\fR. This type's code calls the standard +\fBfile\fR command. When run with Snit 2.2, the code broke-- +the type's command, \fB::tie::std::file\fR, is itself a command +in the type's parent namespace, and so instead of calling +the standard \fBfile\fR command, the type found itself calling +itself. +.PP +.SS "ARE THERE OTHER DIFFERENCES BETWEEN SNIT 1.X AND SNIT 2.2?" +Yes. +.IP \(bu +Method dispatch is considerably faster. +.IP \(bu +Many error messages and stack traces are cleaner. +.IP \(bu +The \fB-simpledispatch\fR pragma is obsolete, and ignored if +present. In Snit 1.x, \fB-simpledispatch\fR 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 +\fB-simpledispatch\fR is no longer needed. +.IP \(bu +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 \fB::parentns::mytype\fR's code can call +\fB::parentns::someproc\fR as just \fBsomeproc\fR. +.sp +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. +.sp +This feature depends on the new Tcl 8.5 \fBnamespace path\fR command, +which is why it hasn't been implemented for V1.x. V1.x code can +achieve something similar by placing +.CS + +namespace import [namespace parent]::* +.CE +.IP +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. +.PP +.SH OBJECTS +.SS "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. +.PP +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 \fBconfigure\fR and +\fBcget\fR methods. Snit uses the same conventions as Tk widgets do. +.SS "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 \fIclass\fR is +usually used instead of \fIabstract data type\fR, but as Snit +doesn't implement inheritance as it's ordinarily understood +the older term seems more appropriate. Sometimes this is called +\fIobject-based\fR programming as opposed to object-oriented +programming. Note that you can easily create the effect of +inheritance using \fBCOMPONENTS\fR and \fBDELEGATION\fR. +.PP +In Snit, as in Tk, a \fItype\fR is a command that creates instances +-- objects -- which belong to the type. Most types define some number +of \fIoptions\fR which can be set at creation time, and usually can be +changed later. +.PP +Further, an \fIinstance\fR 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 \fBinsert\fR +subcommand: +.PP +.CS + + # Create a text widget and insert some text in it. + text .mytext -width 80 -height 24 + .mytext insert end "Howdy!" + +.CE +.PP +In this example, \fBtext\fR is the \fItype\fR command and \fB.mytext\fR is the \fIinstance\fR command. +.PP +In Snit, object subcommands are generally called +\fBINSTANCE METHODS\fR. +.SS "WHAT KINDS OF ABSTRACT DATA TYPES DOES SNIT PROVIDE?" +Snit allows you to define three kinds of abstract data type: +.PP +.IP \(bu +\fBsnit::type\fR +.IP \(bu +\fBsnit::widget\fR +.IP \(bu +\fBsnit::widgetadaptor\fR +.PP +.SS "WHAT IS A SNIT::TYPE?" +A \fBsnit::type\fR is a non-GUI abstract data type, e.g., a stack or a +queue. \fBsnit::type\fRs are defined using the \fBsnit::type\fR +command. For example, if you were designing a kennel management +system for a dog breeder, you'd need a dog type. +.PP +.CS + +% snit::type dog { + # ... +} +::dog +% + +.CE +.PP +This definition defines a new command (\fB::dog\fR, in this case) +that can be used to define dog objects. +.PP +An instance of a \fBsnit::type\fR can have \fBINSTANCE METHODS\fR, +\fBINSTANCE VARIABLES\fR, \fBOPTIONS\fR, and \fBCOMPONENTS\fR. +The type itself can have \fBTYPE METHODS\fR, +\fBTYPE VARIABLES\fR, \fBTYPE COMPONENTS\fR, and +\fBPROCS\fR. +.SS "WHAT IS A SNIT::WIDGET?, THE SHORT STORY" +A \fBsnit::widget\fR is a Tk megawidget built using Snit; it is very +similar to a \fBsnit::type\fR. See \fBWIDGETS\fR. +.SS "WHAT IS A SNIT::WIDGETADAPTOR?, THE SHORT STORY" +A \fBsnit::widgetadaptor\fR 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 \fBsnit::widget\fR. +See \fBWIDGET ADAPTORS\fR. +.SS "HOW DO I CREATE AN INSTANCE OF A SNIT::TYPE?" +You create an instance of a \fBsnit::type\fR by passing the new +instance's name to the type's create method. In the following +example, we create a \fBdog\fR object called \fBspot\fR. +.PP +.CS + +% snit::type dog { + # .... +} +::dog +% dog create spot +::spot +% + +.CE +.PP +In general, the \fBcreate\fR method name can be omitted so long as +the instance name doesn't conflict with any defined +\fBTYPE METHODS\fR. (See \fBTYPE COMPONENTS\fR for the +special case in which this doesn't work.) +So the following example is identical to the +previous example: +.PP +.CS + +% snit::type dog { + # .... +} +::dog +% dog spot +::spot +% + +.CE +.PP +This document generally uses the shorter form. +.PP +If the \fBdog\fR type defines \fBOPTIONS\fR, these can usually be +given defaults at creation time: +.PP +.CS + +% 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 +% + +.CE +.PP +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: +.PP +.CS + +% spot bark +::spot barks. +% + +.CE +.PP +.SS "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, +.PP +.CS + +% snit::type dog { ... } +::dog +% set d [dog spot -breed dalmation -color spotted] +::spot +% $d cget -breed +dalmation +% $d bark +::spot barks. +% + +.CE +.PP +If you prefer this style, you might prefer to have Snit +generate the instance's name automatically. +.SS "HOW CAN I GENERATE THE OBJECT NAME AUTOMATICALLY?" +If you'd like Snit to generate an object name for you, +use the \fB%AUTO%\fR keyword as the requested name: +.PP +.CS + +% snit::type dog { ... } +::dog +% set d [dog %AUTO%] +::dog2 +% $d bark +::dog2 barks. +% + +.CE +.PP +The \fB%AUTO%\fR keyword can be embedded in a longer string: +.PP +.CS + +% set d [dog obj_%AUTO%] +::obj_dog4 +% $d bark +::obj_dog4 barks. +% + +.CE +.PP +.SS "CAN TYPES BE RENAMED?" +Tcl's \fBrename\fR 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. +.PP +\fBsnit::type\fR commands, however, should never be renamed; to do so breaks +the connection between the type and its objects. +.SS "CAN OBJECTS BE RENAMED?" +Tcl's \fBrename\fR 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. +.PP +All Snit objects (including \fIwidgets\fR and \fIwidgetadaptors\fR) +can be renamed, though this flexibility has some consequences: +.PP +.IP \(bu +In an instance method, the implicit argument \fBself\fR will always +contain the object's current name, so instance methods can always call +other instance methods using \fB$self\fR. +.IP \(bu +If the object is renamed, however, then \fB$self\fR's value will change. +Therefore, don't use \fB$self\fR for anything that will break if +\fB$self\fR changes. For example, don't pass a callback command to +another object like this: +.CS + + + .btn configure -command [list $self ButtonPress] + +.CE +.IP +You'll get an error if \fB.btn\fR calls your command after your object is +renamed. +.IP \(bu +Instead, your object should define its callback command like this: +.CS + + + .btn configure -command [mymethod ButtonPress] + +.CE +.IP +The \fBmymethod\fR 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. +.IP \(bu +Every object has a private namespace; the name of this namespace is +available in method bodies, etc., as the value of the implicit +argument \fBselfns\fR. This value is constant for the life of the +object. Use \fB$selfns\fR instead of \fB$self\fR if you need a +unique token to identify the object. +.IP \(bu +When a \fBsnit::widget\fR'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 \fBwin\fR. +This value is constant for the +life of the object. When creating child windows, it's best to use +\fB$win.child\fR rather than \fB$self.child\fR as the name of the +child window. +.PP +.SS "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 \fBrename\fR command. +.PP +Snit megawidgets (i.e., instances of \fBsnit::widget\fR and +\fBsnit::widgetadaptor\fR) can be destroyed like any other widget: by +using the Tk \fBdestroy\fR command on the widget or on one of its +ancestors in the window hierarchy. +.PP +Every instance of a \fBsnit::type\fR has a \fBdestroy\fR method: +.PP +.CS + +% snit::type dog { ... } +::dog +% dog spot +::spot +% spot bark +::spot barks. +% spot destroy +% spot barks +invalid command name "spot" +% + +.CE +.PP +Finally, every Snit type has a type method called \fBdestroy\fR; calling it +destroys the type and all of its instances: +.CS + +% 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" +% + +.CE +.SH "INSTANCE METHODS" +.SS "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. +.SS "HOW DO I DEFINE AN INSTANCE METHOD?" +Instance methods are defined in the type definition using +the \fBmethod\fR statement. Consider the following code that might be +used to add dogs to a computer simulation: +.PP +.CS + +% snit::type dog { + method bark {} { + return "$self barks." + } + + method chase {thing} { + return "$self chases $thing." + } +} +::dog +% + +.CE +.PP +A dog can bark, and it can chase things. +.PP +The \fBmethod\fR statement looks just like a normal Tcl \fBproc\fR, +except that it appears in a \fBsnit::type\fR definition. Notice that +every instance method gets an implicit argument called \fBself\fR; +this argument contains the object's name. (There's more on +implicit method arguments below.) +.SS "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: +.PP +.CS + +% dog spot +::spot +% spot bark +::spot barks. +% spot chase cat +::spot chases cat. +% + +.CE +.PP +.SS "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 \fBself\fR. +.PP +Suppose, for example, that our dogs never chase anything without +barking at them: +.PP +.CS + +% 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. +% + +.CE +.PP +.SS "ARE THERE ANY LIMITATIONS ON INSTANCE METHOD NAMES?" +Not really, so long as you avoid the standard instance method names: +\fBconfigure\fR, \fBconfigurelist\fR, \fBcget\fR, +\fBdestroy\fR, and \fBinfo\fR. Also, method names consisting of +multiple words define hierarchical methods. +.SS "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 \fBtext\fR widget's \fBtag\fR method are hierarchical methods. +.SS "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 \fBtag\fR method with subcommands \fBcget\fR and +\fBconfigure\fR: +.CS + +snit::widget mytext { + method {tag configure} {tag args} { ... } + + method {tag cget} {tag option} {...} +} + +.CE +Note that there is no explicit definition for the \fBtag\fR method; +it is implicit in the definition of \fBtag configure\fR and +\fBtag cget\fR. If you tried to define \fBtag\fR explicitly in this +example, you'd get an error. +.SS "HOW DO I CALL HIERARCHICAL METHODS?" +As subcommands of subcommands. +.CS + +% mytext .text +.text +% .text tag configure redtext -foreground red -background black +% .text tag cget redtext -foreground +red +% + +.CE +.SS "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. +.PP +Snit doesn't implement any access control on instance methods, so all +methods are \fIde facto\fR 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. +.PP +For example, suppose our simulated dogs only bark in response to other +stimuli; they never bark just for fun. So the \fBbark\fR method +becomes \fBBark\fR to indicate that it is private: +.PP +.CS + +% 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. +% + +.CE +.PP +.SS "ARE THERE ANY LIMITATIONS ON INSTANCE METHOD ARGUMENTS?" +Method argument lists are defined just like normal Tcl \fBproc\fR argument +lists; in particular, they can include arguments with default values +and the \fBargs\fR argument. +.PP +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. +.SS "WHAT IMPLICIT ARGUMENTS ARE PASSED TO EACH INSTANCE METHOD?" +The arguments implicitly passed to every method are \fBtype\fR, +\fBselfns\fR, \fBwin\fR, and \fBself\fR. +.SS "WHAT IS $TYPE?" +The implicit argument \fBtype\fR contains the fully qualified name of +the object's type: +.PP +.CS + +% snit::type thing { + method mytype {} { + return $type + } +} +::thing +% thing something +::something +% something mytype +::thing +% + +.CE +.PP +.SS "WHAT IS $SELF?" +The implicit argument \fBself\fR contains the object's fully +qualified name. +.PP +If the object's command is renamed, then \fB$self\fR will change to +match in subsequent calls. Thus, your code should not assume that +\fB$self\fR is constant unless you know for sure that the object +will never be renamed. +.PP +.CS + +% snit::type thing { + method myself {} { + return $self + } +} +::thing +% thing mutt +::mutt +% mutt myself +::mutt +% rename mutt jeff +% jeff myself +::jeff +% + +.CE +.PP +.SS "WHAT IS $SELFNS?" +Each Snit object has a private namespace in which to store its +\fBINSTANCE VARIABLES\fR and \fBOPTIONS\fR. The implicit argument +\fBselfns\fR 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: +.PP +.CS + +% snit::type thing { + method myNameSpace {} { + return $selfns + } +} +::thing +% thing jeff +::jeff +% jeff myNameSpace +::thing::Snit_inst3 +% rename jeff mutt +% mutt myNameSpace +::thing::Snit_inst3 +% + +.CE +.PP +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. +.SS "WHAT IS $WIN?" +The implicit argument \fBwin\fR is defined for all Snit methods, +though it really makes sense only for those of +\fBWIDGETS\fR and \fBWIDGET ADAPTORS\fR. \fB$win\fR 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. +.PP +When a \fBsnit::widgetadaptor\fR 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. +.PP +Thus, using \fBwin\fR whenever the Tk window name is called for +means that a \fBsnit::widget\fR or \fBsnit::widgetadaptor\fR can be +adapted by a \fBsnit::widgetadaptor\fR. See \fBWIDGETS\fR for +more information. +.SS "HOW DO I PASS AN INSTANCE METHOD AS A CALLBACK?" +It depends on the context. +.PP +Suppose in my application I have a \fBdog\fR object named \fBfido\fR, +and I want \fBfido\fR to bark when a Tk button called \fB.bark\fR is +pressed. In this case, I create the callback command in the usual +way, using \fBlist\fR: +.PP +.CS + + button .bark -text "Bark!" -command [list fido bark] + +.CE +.PP +In typical Tcl style, we use a callback to hook two independent +components together. But suppose that the \fBdog\fR object has +a graphical interface and owns the button itself? In this case, +the \fBdog\fR must pass one of its own instance methods to the +button it owns. The obvious thing to do is this: +.PP +.CS + +% snit::widget dog { + constructor {args} { + #... + button $win.barkbtn -text "Bark!" -command [list $self bark] + #... + } +} +::dog +% + +.CE +.PP +(Note that in this example, our \fBdog\fR +becomes a \fBsnit::widget\fR, because it has GUI behavior. See +\fBWIDGETS\fR for more.) Thus, if we create a \fBdog\fR called \fB.spot\fR, it will create a Tk button called \fB.spot.barkbtn\fR; +when pressed, the button will call \fB$self bark\fR. +.PP +Now, this will work--provided that \fB.spot\fR is never renamed to +something else. But surely renaming widgets is +abnormal? And so it is--unless \fB.spot\fR is the hull component of a +\fBsnit::widgetadaptor\fR. If it is, then it will be renamed, and \fB.spot\fR will become the name of the \fBsnit::widgetadaptor\fR +object. When the button is pressed, the command \fB$self bark\fR +will be handled by the \fBsnit::widgetadaptor\fR, which might or might +not do the right thing. +.PP +There's a safer way to do it, and it looks like this: +.PP +.CS + +% snit::widget dog { + constructor {args} { + #... + button $win.barkbtn -text "Bark!" -command [mymethod bark] + #... + } +} +::dog +% + +.CE +.PP +The command \fBmymethod\fR takes any number of arguments, and can be +used like \fBlist\fR to build up a callback command; the only +difference is that \fBmymethod\fR returns a +form of the command that won't change even if the instance's name +changes. +.PP +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 \fB[list $self bark]\fR will do what you want...but +this is a technique which should be used only in carefully controlled +circumstances. +.SS "HOW DO I DELEGATE INSTANCE METHODS TO A COMPONENT?" +See \fBDELEGATION\fR. +.SH "INSTANCE VARIABLES" +.SS "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. +.SS "HOW IS A SCALAR INSTANCE VARIABLE DEFINED?" +Scalar instance variables are defined in the type definition using the +\fBvariable\fR statement. You can simply name it, or you can +initialize it with a value: +.PP +.CS + +snit::type mytype { + # Define variable "greeting" and initialize it with "Howdy!" + variable greeting "Howdy!" +} + +.CE +.PP +.SS "HOW IS AN ARRAY INSTANCE VARIABLE DEFINED?" +Array instance variables are also defined in the type definition +using the \fBvariable\fR command. You can initialize them at the same +time by specifying the \fB-array\fR option: +.PP +.CS + +snit::type mytype { + # Define array variable "greetings" + variable greetings -array { + formal "Good Evening" + casual "Howdy!" + } +} + +.CE +.PP +.SS "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. +.SS "ARE THERE ANY LIMITATIONS ON INSTANCE VARIABLE NAMES?" +Just a few. +.PP +First, every Snit object has a built-in instance variable called +\fBoptions\fR, which should never be redefined. +.PP +Second, all names beginning with "Snit_" are reserved for +use by Snit internal code. +.PP +Third, instance variable names containing the namespace delimiter +(\fB::\fR) are likely to cause great confusion. +.SS "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. +.PP +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. +.PP +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 \fBdict\fR command might come to your rescue. +.PP +The second method is to declare your instance variables explicitly +in your instance code, while \fInot\fR including them in the type +definition: +.CS + +snit::type dog { + constructor {} { + variable mood + + set mood happy + } + + method setmood {newMood} { + variable mood + + set mood $newMood + } + + method getmood {} { + variable mood + + return $mood + } +} + +.CE +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. +.SS "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 \fB-textvariable\fR 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. +.PP +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 \fBmyvar\fR command: +.PP +.CS + +snit::widget mywidget { + variable labeltext "" + + constructor {args} { + # ... + + label $win.label -textvariable [myvar labeltext] + + # ... + } +} + +.CE +.PP +.SS "HOW DO I MAKE AN INSTANCE VARIABLE PUBLIC?" +Practically speaking, you don't. Instead, you'll implement public +variables as \fBOPTIONS\fR. +Alternatively, you can write \fBINSTANCE METHODS\fR to set and get +the variable's value. +.SH OPTIONS +.SS "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. +.PP +Snit's implementation of options follows the Tk model fairly exactly, +except that \fBsnit::type\fR objects usually don't interact with +\fBTHE TK OPTION DATABASE\fR; \fBsnit::widget\fR and +\fBsnit::widgetadaptor\fR objects, on the other hand, always do. +.SS "HOW DO I DEFINE AN OPTION?" +Options are defined in the type definition using the \fBoption\fR +statement. Consider the following type, to be used in an application +that manages a list of dogs for a pet store: +.PP +.CS + +snit::type dog { + option -breed -default mongrel + option -color -default brown + option -akc -default 0 + option -shots -default 0 +} + +.CE +.PP +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. +.PP +There are a number of options you can specify when defining an option; +if \fB-default\fR is the only one, you can omit the word +\fB-default\fR as follows: +.PP +.CS + +snit::type dog { + option -breed mongrel + option -color brown + option -akc 0 + option -shots 0 +} + +.CE +.PP +If no \fB-default\fR value is specified, the option's default value +will be the empty string (but see \fBTHE TK OPTION DATABASE\fR). +.PP +The Snit man page refers to options like these as "locally defined" options. +.SS "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 \fB::dog\fR 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. +.PP +.CS + +% dog spot -breed beagle -color "mottled" -akc 1 -shots 1 +::spot +% dog fido -shots 1 +::fido +% + +.CE +.PP +So \fB::spot\fR is a pedigreed beagle; \fB::fido\fR is a typical mutt, +but his owners evidently take care of him, because he's had his shots. +.PP +\fINote:\fR If the type defines a constructor, it can specify a +different object-creation syntax. See \fBCONSTRUCTORS\fR for more +information. +.SS "HOW CAN A CLIENT RETRIEVE AN OPTION'S VALUE?" +Retrieve option values using the \fBcget\fR method: +.PP +.CS + +% spot cget -color +mottled +% fido cget -breed +mongrel +% + +.CE +.PP +.SS "HOW CAN A CLIENT SET OPTIONS AFTER OBJECT CREATION?" +Any number of options may be set at one time using the +\fBconfigure\fR 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: +.PP +.CS + +% fido configure -color dun -breed "Arctic Boar Hound" +% fido cget -color +dun +% fido cget -breed +Arctic Boar Hound + +.CE +.PP +Alternatively, the \fBconfigurelist\fR method takes a list of +options and values; occasionally this is more convenient: +.PP +.CS + +% 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 +% + +.CE +.PP +In Tcl 8.5, the \fB*\fR keyword can be used with +\fBconfigure\fR in this case: +.PP +.CS + +% 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 +% + +.CE +.PP +The results are the same. +.SS "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 \fBconfigure\fR and \fBcget\fR +methods, as shown below. +.PP +.CS + +% 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 +% + +.CE +.PP +Alternatively, Snit provides a built-in array instance variable called +\fBoptions\fR. The indices are the option names; the values are the +option values. The method \fBgainWeight\fR can thus be rewritten as +follows: +.PP +.CS + + + method gainWeight {} { + incr options(-weight) + } + +.CE +.PP +As you can see, using the \fBoptions\fR variable involves considerably +less typing and is the usual way to do it. But if you use +\fB-configuremethod\fR or \fB-cgetmethod\fR (described in the following +answers), you might wish to use the \fBconfigure\fR and +\fBcget\fR 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 \fBconfigure\fR and \fBcget\fR are the only way +to access it without accessing the component directly. See +\fBDELEGATION\fR for more information. +.SS "HOW CAN I MAKE AN OPTION READ-ONLY?" +Define the option with \fB-readonly yes\fR. +.PP +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. \fB-breed\fR should be read-only, but +\fB-shots\fR should not be. +.PP +.CS + +% 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 +% + +.CE +.PP +.SS "HOW CAN I CATCH ACCESSES TO AN OPTION'S VALUE?" +Define a \fB-cgetmethod\fR for the option. +.SS "WHAT IS A -CGETMETHOD?" +A \fB-cgetmethod\fR is a method that's called whenever the related +option's value is queried via the +\fBcget\fR 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. +.PP +Here's what the default behavior would look like if +written using a \fB-cgetmethod\fR: +.PP +.CS + +snit::type dog { + option -color -default brown -cgetmethod GetOption + + method GetOption {option} { + return $options($option) + } +} + +.CE +.PP +Any instance method can be used, provided that it takes one argument, +the name of the option whose value is to be retrieved. +.SS "HOW CAN I CATCH CHANGES TO AN OPTION'S VALUE?" +Define a \fB-configuremethod\fR for the option. +.SS "WHAT IS A -CONFIGUREMETHOD?" +A \fB-configuremethod\fR is a method that's called whenever the +related option is given a new value via the \fBconfigure\fR or +\fBconfigurelist\fR 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. +.PP +Here's what the default configuration behavior would look like if +written using a \fB-configuremethod\fR: +.PP +.CS + +snit::type dog { + option -color -default brown -configuremethod SetOption + + method SetOption {option value} { + set options($option) $value + } +} + +.CE +.PP +Any instance method can be used, provided that it takes two arguments, +the name of the option and the new value. +.PP +Note that if your method doesn't store the value in the \fBoptions\fR +array, the \fBoptions\fR array won't get updated. +.SS "HOW CAN I VALIDATE AN OPTION'S VALUE?" +Define a \fB-validatemethod\fR. +.SS "WHAT IS A -VALIDATEMETHOD?" +A \fB-validatemethod\fR is a method that's called whenever the +related option is given a new value via the \fBconfigure\fR or +\fBconfigurelist\fR 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 \fB-validatemethod\fR, if any, is called +before the value is stored in the \fBoptions\fR array; in particular, +it's called before the \fB-configuremethod\fR, if any. +.PP +For example, suppose an option always takes a Boolean value. You can +ensure that the value is in fact a valid Boolean like this: +.CS + +% 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" +% + +.CE +Note that the same \fB-validatemethod\fR can be used to validate any number +of boolean options. +.PP +Any method can be a \fB-validatemethod\fR provided that it takes +two arguments, the option name and the new option value. +.SH "TYPE VARIABLES" +.SS "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 \fIstatic member variable\fR is used for the same notion. +Type variables can be scalars or arrays. +.SS "HOW IS A SCALAR TYPE VARIABLE DEFINED?" +Scalar type variables are defined in the type definition using the +\fBtypevariable\fR statement. You can simply name it, or you can +initialize it with a value: +.PP +.CS + + +snit::type mytype { + # Define variable "greeting" and initialize it with "Howdy!" + typevariable greeting "Howdy!" +} + +.CE +.PP +Every object of type \fBmytype\fR now has access to a single variable +called \fBgreeting\fR. +.SS "HOW IS AN ARRAY-VALUED TYPE VARIABLE DEFINED?" +Array-valued type variables are also defined using the +\fBtypevariable\fR command; to initialize them, include the +\fB-array\fR option: +.PP +.CS + +snit::type mytype { + # Define typearray variable "greetings" + typevariable greetings -array { + formal "Good Evening" + casual "Howdy!" + } +} + +.CE +.PP +.SS "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. +.SS "ARE THERE ANY LIMITATIONS ON TYPE VARIABLE NAMES?" +Type variable names have the same restrictions as +the names of \fBINSTANCE VARIABLES\fR do. +.SS "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 \fBINSTANCE METHODS\fR or \fBTYPE METHODS\fR without +declaration. This differs from normal Tcl practice, in which all +non-local variables in a proc need to be declared. +.PP +Type variables are subject to the same speed/readability tradeoffs +as instance variables; see +\fBDo I need to declare my instance variables in my methods?\fR +.SS "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 \fB-textvariable\fR 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. +.PP +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 \fBmytypevar\fR command: +.PP +.CS + +snit::widget mywidget { + typevariable labeltext "" + + constructor {args} { + # ... + + label $win.label -textvariable [mytypevar labeltext] + + # ... + } +} + +.CE +.PP +.SS "HOW DO I MAKE A TYPE VARIABLE PUBLIC?" +There are two ways to do this. The preferred way is to write a pair +of \fBTYPE METHODS\fR to set and query the type variable's value. +.PP +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, +.PP +.CS + +snit::type mytype { + typevariable myvariable +} + +set ::mytype::myvariable "New Value" + +.CE +.PP +.SH "TYPE METHODS" +.SS "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. +.SS "HOW DO I DEFINE A TYPE METHOD?" +Type methods are defined in the type definition using the +\fBtypemethod\fR statement: +.PP +.CS + +snit::type dog { + # List of pedigreed dogs + typevariable pedigreed + + typemethod pedigreedDogs {} { + return $pedigreed + } +} + +.CE +.PP +Suppose the \fBdog\fR type maintains a list of the names of the dogs +that have pedigrees. The \fBpedigreedDogs\fR type method returns this +list. +.PP +The \fBtypemethod\fR statement looks just like a normal Tcl +\fBproc\fR, except that it appears in a \fBsnit::type\fR definition. +Notice that every type method gets an implicit argument called +\fBtype\fR, which contains the fully-qualified type name. +.SS "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 \fBpedigreedDogs\fR, +.PP +.CS + +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] { ... } + +.CE +.PP +.SS "ARE THERE ANY LIMITATIONS ON TYPE METHOD NAMES?" +Not really, so long as you avoid the standard type method names: +\fBcreate\fR, \fBdestroy\fR, and \fBinfo\fR. +.SS "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. +.PP +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. +.PP +Alternatively, a Snit \fBproc\fR can be used as a private type method; see +\fBPROCS\fR. +.SS "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 \fBargs\fR argument. +.PP +However, every type method is called with an implicit argument called +\fBtype\fR 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 \fBINSTANCE METHODS\fR. +.SS "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 \fB$type\fR to do so: +.PP +.CS + +snit::type dog { + + typemethod pedigreedDogs {} { ... } + + typemethod printPedigrees {} { + foreach obj [$type pedigreedDogs] { ... } + } +} + +.CE +.PP +.SS "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, \fBtype\fR. For example, suppose we want to print a +list of pedigreed dogs when a Tk button is pushed: +.PP +.CS + + +button .btn -text "Pedigrees" -command [list dog printPedigrees] +pack .btn + +.CE +Alternatively, from a method or type method you can use the +\fBmytypemethod\fR command, just as you would use \fBmymethod\fR +to define a callback command for \fBINSTANCE METHODS\fR. +.SS "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 +\fBINSTANCE METHODS\fR for more. +.SH PROCS +.SS "WHAT IS A PROC?" +A Snit \fBproc\fR 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. +.SS "HOW DO I DEFINE A PROC?" +Procs are defined by including a \fBproc\fR statement in the type +definition: +.PP +.CS + +snit::type mytype { + # Pops and returns the first item from the list stored in the + # listvar, updating the listvar + proc pop {listvar} { ... } + + # ... +} + +.CE +.PP +.SS "ARE THERE ANY LIMITATIONS ON PROC NAMES?" +Any name can be used, so long as it does not begin with \fBSnit_\fR; +names beginning with \fBSnit_\fR are reserved for Snit's own use. +However, the wise programmer will avoid \fBproc\fR names (\fBset\fR, +\fBlist\fR, \fBif\fR, etc.) that would shadow standard Tcl +command names. +.PP +\fBproc\fR names, being private, should begin with a capital letter according +to convention; however, as there are typically no public \fBproc\fRs +in the type's namespace it doesn't matter much either way. +.SS "HOW DOES A METHOD CALL A PROC?" +Just like it calls any Tcl command. For example, +.PP +.CS + +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] + } +} + +.CE +.PP +.SS "HOW CAN I PASS A PROC TO ANOTHER OBJECT AS A CALLBACK?" +The \fBmyproc\fR command returns a callback command for the +\fBproc\fR, just as \fBmymethod\fR does for a method. +.SH "TYPE CONSTRUCTORS" +.SS "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. +.PP +A type can have at most one type constructor. +.SS "HOW DO I DEFINE A TYPE CONSTRUCTOR?" +A type constructor is defined by using the \fBtypeconstructor\fR +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. +.PP +.CS + +% snit::type mytype { + typevariable lookupTable + + typeconstructor { + array set lookupTable {key value...} + } +} + +.CE +.PP +.SH CONSTRUCTORS +.SS "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 \fBsnit::type\fR command's +\fBcreate\fR 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. +.PP +The constructor's return value is ignored (unless it's an +error, of course). +.SS "HOW DO I DEFINE A CONSTRUCTOR?" +A constructor is defined by using the \fBconstructor\fR 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. +.PP +.CS + +% 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 +% + +.CE +.PP +.SS "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: +.PP +.CS + +snit::type dog { + constructor {args} { + $self configurelist $args + } +} + +.CE +.PP +When the constructor is called, \fBargs\fR 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 \fBconfigurelist\fR method, as shown. +.SS "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: +.PP +.CS + +% 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 + +.CE +.PP +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 +\fBCOMPONENTS\fR using the standard creation syntax. +.SS "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 +\fBargs\fR argument. +.SS "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 +\fBsnit::widget\fRs and \fBsnit::widgetadaptor\fRs. See +\fBDELEGATION\fR, \fBWIDGETS\fR, +\fBWIDGET ADAPTORS\fR, and \fBTHE TK OPTION DATABASE\fR. +.SH DESTRUCTORS +.SS "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 \fBCOMPONENTS\fR, closing files, +and so forth. +.SS "HOW DO I DEFINE A DESTRUCTOR?" +Destructors are defined by using the \fBdestructor\fR statement in the +type definition. +.PP +Suppose we're maintaining a list of pedigreed dogs; +then we'll want to remove dogs from it when they are destroyed. +.PP +.CS + +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 + } +} + +.CE +.PP +.SS "ARE THERE ANY LIMITATIONS ON DESTRUCTOR ARGUMENTS?" +Yes; a destructor has no explicit arguments. +.SS "WHAT IMPLICIT ARGUMENTS ARE PASSED TO THE DESTRUCTOR?" +The destructor gets the same implicit arguments that are passed to +\fBINSTANCE METHODS\fR: \fBtype\fR, \fBselfns\fR, \fBwin\fR, and +\fBself\fR. +.SS "MUST COMPONENTS BE DESTROYED EXPLICITLY?" +Yes and no. +.PP +Any Tk widgets created by a \fBsnit::widget\fR or +\fBsnit::widgetadaptor\fR 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). +.PP +Components of normal \fBsnit::types\fR, 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. +.SS "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. +.PP +For example, a \fBdog\fR might create a \fBtail\fR 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 \fBtail\fR to destroy. The simplest solution is +generally to catch and ignore any errors while destroying components. +.CS + +snit::type dog { + component tail + + constructor {args} { + $self configurelist $args + + set tail [tail %AUTO%] + } + + destructor { + catch {$tail destroy} + } +} + +.CE +.SH COMPONENTS +.SS "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. +.PP +But Snit also has a more precise meaning for +\fBCOMPONENT\fR. The components of a Snit object are those +objects to which methods or options can be delegated. +(See \fBDELEGATION\fR for more information about delegation.) +.SS "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 \fBcomponent\fR statement. The \fBcomponent\fR +statement declares an \fIinstance variable\fR which is used to +store the component's command name when the component is created. +.PP +For example, suppose your \fBdog\fR object +creates a \fBtail\fR object (the better to wag with, no doubt): +.PP +.CS + +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 + } +} + +.CE +.PP +As shown here, it doesn't matter what the \fBtail\fR object's real +name is; the \fBdog\fR object refers to it by its component name. +.PP +The above example shows one way to delegate the \fBwag\fR method to +the \fBmytail\fR component; see \fBDELEGATION\fR for an easier way. +.SS "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. +.PP +In the example in the previous question, the component name is +\fBmytail\fR; the \fBmytail\fR component's object name is chosen +automatically by Snit since \fB%AUTO%\fR was used when the component +object was created. +.SS "ARE THERE ANY LIMITATIONS ON COMPONENT NAMES?" +Yes. \fBsnit::widget\fR and \fBsnit::widgetadaptor\fR objects have a special +component called the \fBhull\fR component; thus, the name \fBhull\fR +should be used for no other purpose. +.PP +Otherwise, since component names are in fact instance variable names +they must follow the rules for \fBINSTANCE VARIABLES\fR. +.SS "WHAT IS AN OWNED COMPONENT?" +An \fIowned\fR component is a component whose object command's +lifetime is controlled by the \fBsnit::type\fR or \fBsnit::widget\fR. +.PP +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: +.CS + +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 + } + } + +.CE +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. +.SS "WHAT DOES THE INSTALL COMMAND DO?" +The \fBinstall\fR command creates an owned component using a specified +command, and assigns the result to the component's instance variable. +For example: +.CS + +snit::type dog { + component mytail + + constructor {args} { + # set mytail [tail %AUTO% -partof $self] + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } +} + +.CE +In a \fBsnit::type\fR's code, the \fBinstall\fR +command shown above is equivalent to the \fBset mytail\fR command +that's commented out. In a \fBsnit::widget\fR's or +\fBsnit::widgetadaptor\fR's, code, however, the +\fBinstall\fR command also queries \fBTHE TK OPTION DATABASE\fR +and initializes the new component's options accordingly. For consistency, +it's a good idea to get in the habit of using \fBinstall\fR for all +owned components. +.SS "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. +.SS "ARE THERE ANY LIMITATIONS ON COMPONENT OBJECT NAMES?" +Yes. +.PP +Component objects which are Tk widgets or megawidgets must have valid +Tk window names. +.PP +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. +.PP +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: +.PP +.CS + +snit::type tail { ... } + +snit::type dog { + delegate method wag to mytail + + constructor {} { + install mytail using tail mytail + } +} + +.CE +.PP +This code uses the component name, \fBmytail\fR, 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 \fBmytail\fR component is +created in the \fB::dog::\fR namespace, and will thus have the name +\fB::dog::mytail\fR. +.PP +Now, suppose you create two dogs. Both dogs will attempt to +create a tail called \fB::dog::mytail\fR. 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: +.PP +First, if the component type is a \fBsnit::type\fR you can +specify \fB%AUTO%\fR as its name, and be guaranteed to get a unique name. +This is the safest thing to do: +.PP +.CS + + + install mytail using tail %AUTO% + +.CE +.PP +If the component type isn't a \fBsnit::type\fR you can create +the component in the object's instance namespace: +.PP +.CS + + + install mytail using tail ${selfns}::mytail + +.CE +.PP +Make sure you pick a unique name within the instance namespace. +.SS "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 \fBsnit::widget\fR +or \fBsnit::widgetadaptor\fR you don't need to destroy any components +that are widgets, because they will generally be children or +descendants of your megawidget. +.PP +If your object is an instance of \fBsnit::type\fR, though, none of its +owned components will be destroyed automatically, nor will be +non-widget components of a \fBsnit::widget\fR be destroyed +automatically. All such owned components must be destroyed +explicitly, or they won't be destroyed at all. +.SS "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 \fBDELEGATION\fR. 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. +.PP +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. +.SS "HOW DO I EXPOSE A COMPONENT'S OBJECT COMMAND?" +When you declare the component, specify the \fBcomponent\fR +statement's \fB-public\fR option. The value of this option is the +name of a method which will be delegated to your component's object +command. +.PP +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: +.PP +.CS + +snit::widget combobox { + component listbox -public listbox + + constructor {args} { + install listbox using listbox $win.listbox .... + } +} + +combobox .mycombo +.mycombo listbox configure -width 30 + +.CE +.PP +Your comobox widget, \fB.mycombo\fR, now has a \fBlistbox\fR 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. +.PP +Usually you'll let the method name be the same as the component name; +however, you can name it anything you like. +.SH "TYPE COMPONENTS" +.SS "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 \fBINSTANCE VARIABLES\fR and +\fBTYPE VARIABLES\fR. Both \fBINSTANCE METHODS\fR and +\fBTYPE METHODS\fR can be delegated to type components. +.PP +Once you understand \fBCOMPONENTS\fR and +\fBDELEGATION\fR, type components are just more of the same. +.SS "HOW DO I DECLARE A TYPE COMPONENT?" +Declare a type component using the \fBtypecomponent\fR statement. It +takes the same options (\fB-inherit\fR and \fB-public\fR) as the +\fBcomponent\fR statement does, and defines a type variable to hold +the type component's object command. +.PP +Suppose in your model you've got many dogs, but only one +veterinarian. You might make the veterinarian a type component. +.CS + +snit::type veterinarian { ... } + +snit::type dog { + typecomponent vet + + # ... +} + +.CE +.SS "HOW DO I INSTALL A TYPE COMPONENT?" +Just use the \fBset\fR command to assign the component's object +command to the type component. Because types +(even \fBsnit::widget\fR types) are not widgets, and do not have +options anyway, the extra features of the \fBinstall\fR command are +not needed. +.PP +You'll usually install type components in the type constructor, as +shown here: +.CS + +snit::type veterinarian { ... } + +snit::type dog { + typecomponent vet + + typeconstructor { + set vet [veterinarian %AUTO%] + } +} + +.CE +.SS "ARE THERE ANY LIMITATIONS ON TYPE COMPONENT NAMES?" +Yes, the same as on \fBINSTANCE VARIABLES\fR, +\fBTYPE VARIABLES\fR, and normal \fBCOMPONENTS\fR. +.SH DELEGATION +.SS "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 \fBdog\fR object can delegate its \fBwag\fR method and its +\fB-taillength\fR option to its \fBtail\fR component. +.PP +.CS + +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 + } + +} + +.CE +.PP +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. +.PP +Note that the constructor calls the \fBconfigurelist\fR method +\fBafter\fR it creates its \fBtail\fR; otherwise, +if \fB-taillength\fR appeared in the list of \fBargs\fR we'd get an +error. +.SS "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 \fBdelegate\fR statement in the type definition. +(See \fBCOMPONENTS\fR and \fBTYPE COMPONENTS\fR +for more information about component names.) +.PP +For example, here's a much better way to delegate the \fBdog\fR +object's \fBwag\fR method: +.PP +.CS + +% 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. + +.CE +.PP +This code has the same effect as the code shown under the previous +question: when a \fBdog\fR's \fBwag\fR method is called, the call and +its arguments are passed along automatically to the \fBtail\fR object. +.PP +Note that when a component is mentioned in a \fBdelegate\fR statement, +the component's instance variable is defined implicitly. However, +it's still good practice to declare it explicitly using the +\fBcomponent\fR statement. +.PP +Note also that you can define a method name using the \fBmethod\fR +statement, or you can define it using \fBdelegate\fR; you can't do +both. +.SS "CAN I DELEGATE TO A METHOD WITH A DIFFERENT NAME?" +Suppose you wanted to delegate the \fBdog\fR's \fBwagtail\fR method to +the \fBtail\fR's \fBwag\fR method. After all you wag the tail, not +the dog. It's easily done: +.PP +.CS + +snit::type dog { + delegate method wagtail to mytail as wag + + constructor {args} { + install mytail using tail %AUTO% -partof $self + $self configurelist $args + } +} + +.CE +.PP +.SS "CAN I DELEGATE TO A METHOD WITH ADDITIONAL ARGUMENTS?" +Suppose the \fBtail\fR's \fBwag\fR method takes as an argument the +number of times the tail should be wagged. You want to delegate the +\fBdog\fR's \fBwagtail\fR method to the \fBtail\fR's \fBwag\fR +method, specifying that the tail should be wagged exactly three times. +This is easily done, too: +.PP +.CS + +snit::type dog { + delegate method wagtail to mytail as {wag 3} + # ... +} + +snit::type tail { + method wag {count} { + return [string repeat "Wag " $count] + } + # ... +} + +.CE +.PP +.SS "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 \fBdelegate\fR statement's \fBusing\fR clause. +.PP +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, \fBsaverec\fR +saves a record. If you let the record ID be the name of the dog +object, you can delegate the dog's \fBsave\fR method to the +\fBsaverec\fR command as follows: +.CS + +snit::type dog { + delegate method save using {saverec %s} +} + +.CE +The \fB%s\fR is replaced with the instance name when the +\fBsave\fR method is called; any additional arguments are the +appended to the resulting command. +.PP +The \fBusing\fR clause understands a number of other %-conversions; +in addition to the instance name, you can substitute in the method +name (\fB%m\fR), the type name (\fB%t\fR), the instance +namespace (\fB%n\fR), the Tk window name (\fB%w\fR), and, +if a component or typecomponent name was given in the +\fBdelegate\fR statement, the component's object command +(\fB%c\fR). +.SS "HOW CAN I DELEGATE A METHOD TO A TYPE COMPONENT OBJECT?" +Just exactly as you would to a component object. The +\fBdelegate method\fR statement accepts both component and type +component names in its \fBto\fR clause. +.SS "HOW CAN I DELEGATE A TYPE METHOD TO A TYPE COMPONENT OBJECT?" +Use the \fBdelegate typemethod\fR statement. It works like +\fBdelegate method\fR, with these differences: first, it defines +a type method instead of an instance method; second, the +\fBusing\fR clause ignores the \fB%s\fR, \fB%n\fR, +and \fB%w\fR %-conversions. +.PP +Naturally, you can't delegate a type method to an instance +component...Snit wouldn't know which instance should receive it. +.SS "HOW CAN I DELEGATE AN OPTION TO A COMPONENT OBJECT?" +The first question in this section (see \fBDELEGATION\fR) shows +one way to delegate an option to a component; but this pattern occurs +often enough that Snit makes it easy. For example, every \fBtail\fR +object has a \fB-length\fR option; we want to allow the creator of +a \fBdog\fR object to set the tail's length. We can do this: +.PP +.CS + +% 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 + +.CE +.PP +This produces nearly the same result as the \fB-configuremethod\fR and +\fB-cgetmethod\fR shown under the first question in this +section: whenever a \fBdog\fR object's \fB-length\fR option is set +or retrieved, the underlying \fBtail\fR object's option is set or +retrieved in turn. +.PP +Note that you can define an option name using the \fBoption\fR +statement, or you can define it using \fBdelegate\fR; you can't do +both. +.SS "CAN I DELEGATE TO AN OPTION WITH A DIFFERENT NAME?" +In the previous answer we delegated the \fBdog\fR's \fB-length\fR +option down to its \fBtail\fR. 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 \fBdog\fR a \fB-taillength\fR +option, but delegate it to the \fBtail\fR's \fB-length\fR option: +.PP +.CS + +snit::type dog { + delegate option -taillength to mytail as -length + + constructor {args} { + set mytail [tail %AUTO% -partof $self] + $self configurelist $args + } +} + +.CE +.PP +.SS "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 \fBsnit::widgetadaptors\fR, +for example, where we wish to slightly the modify the behavior of an +existing widget. To carry on with our \fBdog\fR example, however, suppose +that we have a \fBsnit::type\fR called \fBanimal\fR that implements a +variety of animal behaviors--moving, eating, sleeping, and so forth. +We want our \fBdog\fR objects to inherit these same behaviors, while +adding dog-like behaviors of its own. +Here's how we can give a \fBdog\fR methods and options of its own +while delegating all other methods and options to its \fBanimal\fR +component: +.PP +.CS + +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" + } +} + +.CE +.PP +That's it. A \fBdog\fR is now an \fBanimal\fR that has a +\fB-akc\fR option and can \fBwag\fR its tail. +.PP +Note that we don't need to specify the full list of method names or +option names that \fBanimal\fR will receive. +It gets anything \fBdog\fR doesn't recognize--and if it doesn't +recognize it either, it will simply throw an error, just as it should. +.PP +You can also delegate all unknown type methods to a type component +using \fBdelegate typemethod *\fR. +.SS "HOW CAN I DELEGATE ALL BUT CERTAIN METHODS OR OPTIONS TO A COMPONENT?" +In the previous answer, we said that every \fBdog\fR is +an \fBanimal\fR by delegating all unknown methods and options to the +\fBanimal\fR component. But what if the \fBanimal\fR type has some +methods or options that we'd like to suppress? +.PP +One solution is to explicitly delegate all the options and methods, +and forgo the convenience of \fBdelegate method *\fR and +\fBdelegate option *\fR. But if we wish to suppress only a few +options or methods, there's an easier way: +.PP +.CS + +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 + } + + # ... +} + +.CE +.PP +Dogs have four legs, so we specify that explicitly when we create the +\fBanimal\fR component, and explicitly exclude \fB-numlegs\fR from the +set of delegated options. Similarly, dogs can neither +\fBfly\fR nor \fBclimb\fR, +so we exclude those \fBanimal\fR methods as shown. +.SS "CAN A HIERARCHICAL METHOD BE DELEGATED?" +Yes; just specify multiple words in the delegated method's name: +.PP +.CS + +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 + } + + # ... +} + +.CE +.PP +Unrecognized hierarchical methods can also be delegated; the following +code delegates all subcommands of the "tail" method to the "mytail" +component: +.PP +.CS + +snit::type dog { + delegate method {tail *} to mytail + + # ... +} + +.CE +.PP +.SH WIDGETS +.SS "WHAT IS A SNIT::WIDGET?" +A \fBsnit::widget\fR is the Snit version of what Tcl programmers +usually call a \fImegawidget\fR: a widget-like object usually +consisting of one or more Tk widgets all contained within a Tk frame. +.PP +A \fBsnit::widget\fR is also a special kind of \fBsnit::type\fR. Just +about everything in this FAQ list that relates to \fBsnit::types\fR +also applies to \fBsnit::widgets\fR. +.SS "HOW DO I DEFINE A SNIT::WIDGET?" +\fBsnit::widgets\fR are defined using the \fBsnit::widget\fR command, +just as \fBsnit::types\fR are defined by the \fBsnit::type\fR command. +.PP +The body of the definition can contain all of the same kinds of +statements, plus a couple of others which will be mentioned below. +.SS "HOW DO SNIT::WIDGETS DIFFER FROM SNIT::TYPES?" +.IP \(bu +The name of an instance of a \fBsnit::type\fR can be any valid Tcl +command name, in any namespace. +The name of an instance of a \fBsnit::widget\fR must be a valid Tk +widget name, and its parent widget must already exist. +.IP \(bu +An instance of a \fBsnit::type\fR can be destroyed by calling +its \fBdestroy\fR method. Instances of a \fBsnit::widget\fR have no +destroy method; use the Tk \fBdestroy\fR command instead. +.IP \(bu +Every instance of a \fBsnit::widget\fR has one predefined component +called its \fBhull\fR component. +The hull is usually a Tk \fBframe\fR or \fBtoplevel\fR widget; any other +widgets created as part of the \fBsnit::widget\fR will usually be +contained within the hull. +.IP \(bu +\fBsnit::widget\fRs can have their options receive default values from +\fBTHE TK OPTION DATABASE\fR. +.PP +.SS "WHAT IS A HULL COMPONENT?" +Snit can't create a Tk widget object; only Tk can do that. +Thus, every instance of a \fBsnit::widget\fR must be wrapped around a +genuine Tk widget; this Tk widget is called the \fIhull component\fR. +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. +.PP +For \fBsnit::widget\fRs the hull component must be a Tk widget that +defines the \fB-class\fR option. +.PP +\fBsnit::widgetadaptor\fRs differ from \fBsnit::widget\fRs chiefly in +that any kind of widget can be used as the hull component; see +\fBWIDGET ADAPTORS\fR. +.SS "HOW CAN I SET THE HULL TYPE FOR A SNIT::WIDGET?" +A \fBsnit::widget\fR's hull component will usually be a Tk \fBframe\fR +widget; however, it may be any Tk widget that defines the +\fB-class\fR option. You can +explicitly choose the hull type you prefer by including the \fBhulltype\fR +command in the widget definition: +.PP +.CS + +snit::widget mytoplevel { + hulltype toplevel + + # ... +} + +.CE +.PP +If no \fBhulltype\fR command appears, the hull will be a \fBframe\fR. +.PP +By default, Snit recognizes the following hull types: the Tk widgets +\fBframe\fR, \fBlabelframe\fR, \fBtoplevel\fR, and the Tile widgets +\fBttk::frame\fR, \fBttk::labelframe\fR, and \fBttk::toplevel\fR. To +enable the use of some other kind of widget as the hull type, you can +\fBlappend\fR the widget command to the variable \fBsnit::hulltypes\fR (always +provided the widget defines the \fB-class\fR option. For example, +suppose Tk gets a new widget type called a \fBprettyframe\fR: +.PP +.CS + +lappend snit::hulltypes prettyframe + +snit::widget mywidget { + hulltype prettyframe + + # ... +} + +.CE +.PP +.SS "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 \fBsnit::widget\fR is first +created, its instance name, \fBself\fR, is a Tk window name; +however, if the \fBsnit::widget\fR is used as the hull component by a +\fBsnit::widgetadaptor\fR its instance name will be changed to +something else. For this reason, every \fBsnit::widget\fR method, +constructor, destructor, and so forth is passed another implicit +argument, \fBwin\fR, which is the window name of the megawidget. Any +children should be named using \fBwin\fR as the root. +.PP +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: +.PP +.CS + +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 + + } +} + +.CE +.PP +See also the question on renaming objects, toward the top of this +file. +.SH "WIDGET ADAPTORS" +.SS "WHAT IS A SNIT::WIDGETADAPTOR?" +A \fBsnit::widgetadaptor\fR is a kind of \fBsnit::widget\fR. Whereas +a \fBsnit::widget\fR's hull is automatically created and is always a +Tk frame, a \fBsnit::widgetadaptor\fR can be based on any Tk +widget--or on any Snit megawidget, or even (with luck) on megawidgets +defined using some other package. +.PP +It's called a \fIwidget adaptor\fR because it allows you to take an +existing widget and customize its behavior. +.SS "HOW DO I DEFINE A SNIT::WIDGETADAPTOR?" +Use the \fBsnit::widgetadaptor\fR command. The definition for a +\fBsnit::widgetadaptor\fR looks just like that for a \fBsnit::type\fR +or \fBsnit::widget\fR, except that the constructor must create and +install the hull component. +.PP +For example, the following code creates a read-only text widget by the +simple device of turning its \fBinsert\fR and \fBdelete\fR +methods into no-ops. Then, we define new methods, \fBins\fR and +\fBdel\fR, +which get delegated to the hull component as \fBinsert\fR and +\fBdelete\fR. Thus, we've adapted the text widget and given it new +behavior while still leaving it fundamentally a text widget. +.PP +.CS + +::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 +} + +.CE +.PP +The most important part is in the constructor. +Whereas \fBsnit::widget\fR creates the hull for you, +\fBsnit::widgetadaptor\fR 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 \fBinstallhull\fR command. +.PP +\fINote:\fR There is no instance command until you create one by +installing a hull component. Any attempt to pass methods to \fB$self\fR +prior to calling \fBinstallhull\fR will fail. +.SS "CAN I ADAPT A WIDGET CREATED ELSEWHERE IN THE PROGRAM?" +Yes. +.PP +At times, it can be convenient to adapt a pre-existing widget instead +of creating your own. +For example, the Bwidget \fBPagesManager\fR widget manages a +set of \fBframe\fR widgets, only one of which is visible at a time. +The application chooses which \fBframe\fR is visible. All of the +These \fBframe\fRs are created by the \fBPagesManager\fR itself, using +its \fBadd\fR method. It's convenient to adapt these frames to +do what we'd like them to do. +.PP +In a case like this, the Tk widget will already exist when the +\fBsnit::widgetadaptor\fR is created. Snit provides an alternate form +of the \fBinstallhull\fR command for this purpose: +.PP +.CS + +snit::widgetadaptor pageadaptor { + constructor {args} { + # The widget already exists; just install it. + installhull $win + + # ... + } +} + +.CE +.SS "CAN I ADAPT ANOTHER MEGAWIDGET?" +Maybe. If the other megawidget is a \fBsnit::widget\fR or +\fBsnit::widgetadaptor\fR, 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 \fB<Destroy>\fR event before the +megawidget you're adapting does. +.SH "THE TK OPTION DATABASE" +.SS "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). +.PP +Full details about the Tk option database are beyond the scope of this +document; both \fIPractical Programming in Tcl and Tk\fR by Welch, +Jones, and Hobbs, and \fIEffective Tcl/Tk Programming\fR by +Harrison and McClennan., have good introductions to it. +.PP +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. +.PP +.IP \(bu +If the widget's default widget class is not what is desired, set it +explicitly using the \fBwidgetclass\fR statement in the widget +definition. +.IP \(bu +When defining or delegating options, specify the resource and class +names explicitly when necessary. +.IP \(bu +Use the \fBinstallhull using\fR command to create and install the +hull for \fBsnit::widgetadaptor\fRs. +.IP \(bu +Use the \fBinstall\fR command to create and install all +components which are widgets. +.IP \(bu +Use the \fBinstall\fR command to create and install +components which aren't widgets if you'd like them to +receive option values from the option database. +.PP +.PP +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. +.SS "DO SNIT::TYPES USE THE TK OPTION DATABASE?" +No, they don't; querying the option database requires a Tk window +name, and \fBsnit::type\fRs don't have one. +.PP +If you create an instance of a \fBsnit::type\fR as a +component of a \fBsnit::widget\fR or \fBsnit::widgetadaptor\fR, on the +other hand, and if any options are delegated to the component, +and if you use \fBinstall\fR to create and install it, then +the megawidget will query the option database on the +\fBsnit::type\fR's behalf. This might or might not be what you +want, so take care. +.SS "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 \fBbutton\fR widget is +\fBButton\fR. +.PP +Similarly, the widget class of a \fBsnit::widget\fR defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of +.PP +.CS + +snit::widget ::mylibrary::scrolledText { ... } + +.CE +.PP +is \fBScrolledText\fR. +.PP +The widget class can also be set explicitly using the +\fBwidgetclass\fR statement within the \fBsnit::widget\fR definition: +.PP +.CS + +snit::widget ::mylibrary::scrolledText { + widgetclass Text + + # ... +} + +.CE +.PP +The above definition says that a \fBscrolledText\fR megawidget has the +same widget class as an ordinary \fBtext\fR 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. +.SS "WHAT IS MY SNIT::WIDGETADAPTOR'S WIDGET CLASS?" +The widget class of a \fBsnit::widgetadaptor\fR is just the widget +class of its hull widget; Snit has no control over this. +.PP +Note that the widget class can be changed only for \fBframe\fR and +\fBtoplevel\fR widgets, which is why these are the valid hull types +for \fBsnit::widget\fRs. +.PP +Try to use \fBsnit::widgetadaptor\fRs 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. +.SS "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 \fBconfigure\fR and \fBcget\fR +commands. +.PP +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 \fBtext\fR +widget options: +.PP +.CS + + -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad + +.CE +.PP +As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always. +.SS "WHAT ARE THE RESOURCE AND CLASS NAMES FOR MY MEGAWIDGET'S OPTIONS?" +For options implicitly delegated to a component using +\fBdelegate option *\fR, the resource and class names will be +exactly those defined by the component. The \fBconfigure\fR method +returns these names, along with the option's default and current +values: +.PP +.CS + +% 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 +% + +.CE +.PP +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. +.PP +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": +.PP +.CS + +% 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 +% + +.CE +.PP +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: +.PP +.CS + +% snit::widget mytext { + delegate option {-padx padX Pad} to text + + # ... +} +::mytext +% mytext .text +.text +% .text configure -padx +-padx padX Pad 1 1 +% + +.CE +.SS "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, +.PP +.CS + +option add *Mywidget.texture pebbled + +snit::widget mywidget { + option -texture smooth + # ... +} + +mywidget .mywidget -texture greasy + +.CE +.PP +Here, \fB-texture\fR 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". +.SS "HOW DOES SNIT INITIALIZE DELEGATED OPTIONS?" +That depends on whether the options are delegated to the hull, or to +some other component. +.SS "HOW DOES SNIT INITIALIZE OPTIONS DELEGATED TO THE HULL?" +A \fBsnit::widget\fR'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: +.PP +.CS + +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] + +.CE +.PP +The question is, what are the values of variables A, B, C and D? +.PP +The value of A is "sunken". The hull is a Tk frame which has been +given the widget class \fBMywidget\fR; it will automatically query the +option database and pick up this value. Since the \fB-relief\fR option is +implicitly delegated to the hull, Snit takes no action. +.PP +The value of B is "red". The hull will automatically pick up the +value "green" for its \fB-background\fR option, just as it picked up the +\fB-relief\fR value. However, Snit knows that \fB-hullbackground\fR +is mapped to the hull's \fB-background\fR option; hence, it queries +the option database for \fB-hullbackground\fR and gets "red" and +updates the hull accordingly. +.PP +The value of C is also "red", because \fB-background\fR is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +\fB-hullbackground\fR. Note that this case is unusual; the +\fB-background\fR option should probably have been excluded using the delegate +statement's \fBexcept\fR clause, or (more likely) delegated to some other +component. +.PP +The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for \fB-borderwidth\fR defaults to +\fBborderwidth\fR, whereas the option database entry is +\fBborderWidth\fR, in +accordance with the standard Tk naming for this option. As with +\fB-relief\fR, the hull picks up its own \fB-borderwidth\fR +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 +\fB-borderwidth\fR option +should have been delegated like this: +.PP +.CS + + delegate option {-borderwidth borderWidth BorderWidth} to hull + +.CE +.PP +For \fBsnit::widgetadaptor\fRs, 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 \fBsnit::widgetadaptor\fR +must call \fBinstallhull\fR in its constructor. The normal way +to do this is as follows: +.PP +.CS + +snit::widgetadaptor mywidget { + # ... + constructor {args} { + # ... + installhull using text -foreground white + # ... + } + # ... +} + +.CE +.PP +In this case, the \fBinstallhull\fR command will create the hull using +a command like this: +.PP +.CS + + set hull [text $win -foreground white] + +.CE +.PP +The hull is a \fBtext\fR widget, so its widget class is \fBText\fR. Just +as with \fBsnit::widget\fR 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. +.PP +In earlier versions of Snit, \fBsnit::widgetadaptor\fRs were expected +to call \fBinstallhull\fR like this: +.PP +.CS + + installhull [text $win -foreground white] + +.CE +.PP +This form still works--but Snit will not query the option database as +described above. +.SS "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. +.PP +A component widget remains a widget still, and is therefore +initialized from the option database in the usual way. A \fBtext\fR +widget remains a \fBtext\fR widget whether it is a component of a +megawidget or not, and will be created as such. +.PP +But then, the option database is queried for all options delegated to +the component, and the component is initialized accordingly--provided +that the \fBinstall\fR command is used to create it. +.PP +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: +.PP +.CS + +snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + set myComp [text $win.text -foreground black] + } +} + +.CE +.PP +The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used: +.PP +.CS + +snit::widget mywidget { + delegate option -background to myComp + + constructor {args} { + install myComp using text $win.text -foreground black + } +} + +.CE +.PP +The \fBinstall\fR command does the following: +.PP +.IP \(bu +Builds a list of the options explicitly included in the \fBinstall\fR +command--in this case, \fB-foreground\fR. +.IP \(bu +Queries the option database for all options delegated explicitly to +the named component. +.IP \(bu +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 \fB-foreground\fR) will +override anything read from the option database. +.IP \(bu +If the widget definition implicitly delegated options to the component +using \fBdelegate option *\fR, then Snit calls the newly created +component's \fBconfigure\fR 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 \fBinstall\fR command. For all such options, Snit +queries the option database and configures the component accordingly. +.PP +You don't really need to know all of this; just use \fBinstall\fR to +install your components, and Snit will try to do the right thing. +.SS "WHAT HAPPENS IF I INSTALL A NON-WIDGET AS A COMPONENT OF WIDGET?" +A \fBsnit::type\fR never queries the option database. +However, a \fBsnit::widget\fR can have non-widget components. And if +options are delegated to those components, and if the \fBinstall\fR +command is used to install those components, then they will be +initialized from the option database just as widget components are. +.PP +However, when used within a megawidget, \fBinstall\fR assumes that the +created component uses a reasonably standard widget-like creation +syntax. If it doesn't, don't use \fBinstall\fR. +.SH "ENSEMBLE COMMANDS" +.SS "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 \fBstring\fR, \fBfile\fR, +and \fBclock\fR. In a sense, these are singleton objects--there's +only one instance of them. +.SS "HOW CAN I CREATE AN ENSEMBLE COMMAND USING SNIT?" +There are two ways--as a \fBsnit::type\fR, or as an instance of +a \fBsnit::type\fR. +.SS "HOW CAN I CREATE AN ENSEMBLE COMMAND USING AN INSTANCE OF A SNIT::TYPE?" +Define a type whose \fBINSTANCE METHODS\fR are the subcommands +of your ensemble command. Then, create an instance of the type with +the desired name. +.PP +For example, the following code uses \fBDELEGATION\fR to create +a work-alike for the standard \fBstring\fR command: +.CS + +snit::type ::mynamespace::mystringtype { + delegate method * to stringhandler + + constructor {} { + set stringhandler string + } +} + +::mynamespace::mystringtype mystring + +.CE +We create the type in a namespace, so that the type command is hidden; +then we create a single instance with the desired name-- +\fBmystring\fR, in this case. +.PP +This method has two drawbacks. First, it leaves the type command +floating about. More seriously, your shiny new ensemble +command will have \fBinfo\fR and \fBdestroy\fR subcommands that +you probably have no use for. But read on. +.SS "HOW CAN I CREATE AN ENSEMBLE COMMAND USING A SNIT::TYPE?" +Define a type whose \fBTYPE METHODS\fR are the subcommands +of your ensemble command. +.PP +For example, the following code uses \fBDELEGATION\fR to create +a work-alike for the standard \fBstring\fR command: +.CS + +snit::type mystring { + delegate typemethod * to stringhandler + + typeconstructor { + set stringhandler string + } +} + +.CE +Now the type command itself is your ensemble command. +.PP +This method has only one drawback, and though it's major, it's +also surmountable. Your new ensemble command will have +\fBcreate\fR, \fBinfo\fR and \fBdestroy\fR subcommands +you don't want. And worse yet, since the \fBcreate\fR method +can be implicit, users of your command will accidentally be creating +instances of your \fBmystring\fR 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. +.PP +The work around is to set some \fBPRAGMAS\fR, as shown here: +.CS + +snit::type mystring { + pragma -hastypeinfo no + pragma -hastypedestroy no + pragma -hasinstances no + + delegate typemethod * to stringhandler + + typeconstructor { + set stringhandler string + } +} + +.CE +Here we've used the \fBpragma\fR statement to tell Snit that we don't +want the \fBinfo\fR typemethod or the \fBdestroy\fR typemethod, +and that our type has no instances; this eliminates the +\fBcreate\fR typemethod and all related code. As +a result, our ensemble command will be well-behaved, with no +unexpected subcommands. +.SH PRAGMAS +.SS "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. +.SS "HOW DO I SET A PRAGMA?" +Use the \fBpragma\fR statement. Each pragma is an option with a +value; each time you use the \fBpragma\fR statement you can set one or +more of them. +.SS "HOW CAN I GET RID OF THE "INFO" TYPE METHOD?" +Set the \fB-hastypeinfo\fR pragma to \fBno\fR: +.CS + +snit::type dog { + pragma -hastypeinfo no + # ... +} + +.CE +Snit will refrain from defining the \fBinfo\fR type method. +.SS "HOW CAN I GET RID OF THE "DESTROY" TYPE METHOD?" +Set the \fB-hastypedestroy\fR pragma to \fBno\fR: +.CS + +snit::type dog { + pragma -hastypedestroy no + # ... +} + +.CE +Snit will refrain from defining the \fBdestroy\fR type method. +.SS "HOW CAN I GET RID OF THE "CREATE" TYPE METHOD?" +Set the \fB-hasinstances\fR pragma to \fBno\fR: +.CS + +snit::type dog { + pragma -hasinstances no + # ... +} + +.CE +Snit will refrain from defining the \fBcreate\fR 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. +.PP +This is useful if you wish to use a \fBsnit::type\fR to define +an ensemble command rather than a type with instances. +.PP +Pragmas \fB-hastypemethods\fR and \fB-hasinstances\fR cannot +both be false (or there'd be nothing left). +.SS "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 +\fBcreate\fR type method directly. To get the same behavior from +Snit, set the \fB-hastypemethods\fR pragma to \fBno\fR: +.CS + +snit::type dog { + pragma -hastypemethods no + #... +} + +# Creates ::spot +dog spot + +# Tries to create an instance called ::create +dog create spot + +.CE +Pragmas \fB-hastypemethods\fR and \fB-hasinstances\fR cannot +both be false (or there'd be nothing left). +.SS "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 +\fBsnit::type\fR, even if the name was already in use by some other +object or command. You could do the following, for example: +.CS + +snit::type dog { ... } + +dog proc + +.CE +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 \fB-canreplace\fR pragma to \fByes\fR: +.CS + +snit::type dog { + pragma -canreplace yes + # ... +} + +.CE +.SS "HOW CAN I MAKE MY SIMPLE TYPE RUN FASTER?" +In Snit 1.x, you can set the \fB-simpledispatch\fR pragma to \fByes\fR. +.PP +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 +\fB-simpledispatch\fR pragma allows you to substitute a simpler +dispatch mechanism that runs quite a bit faster. The limitations +are these: +.IP \(bu +Methods cannot be delegated. +.IP \(bu +\fBuplevel\fR and \fBupvar\fR do not work as expected: the +caller's scope is two levels up rather than one. +.IP \(bu +The option-handling methods +(\fBcget\fR, \fBconfigure\fR, and \fBconfigurelist\fR) are very +slightly slower. +.PP +In Snit 2.2, the \fB-simpledispatch\fR macro is obsolete, and +ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's +\fB-simpledispatch\fR. +.SH MACROS +.SS "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. +.SS "WHAT ARE MACROS GOOD FOR?" +You can use Snit macros to define new type definition syntax, and to +support conditional compilation. +.SS "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? +.PP +It's easily done. Outside of any type definition, define a macro that +returns 1 if the extension is available, and 0 otherwise: +.CS + +if {$gotFastExtension} { + snit::macro fastcode {} {return 1} +} else { + snit::macro fastcode {} {return 0} +} + +.CE +Then, use your macro in your type definition: +.CS + +snit::type dog { + + if {[fastcode]} { + # Fast methods + method bark {} {...} + method wagtail {} {...} + } else { + # Slow methods + method bark {} {...} + method wagtail {} {...} + } +} + +.CE +.SS "HOW DO I DEFINE NEW TYPE DEFINITION SYNTAX?" +Use a macro. For example, your \fBsnit::widget\fR's +\fB-background\fR option should be propagated to a number +of component widgets. You could implement that like this: +.CS + +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 + } +} + +.CE +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: +.CS + +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 +} + +.CE +Then you can use it like this: +.CS + +snit::widget mywidget { + option -background default -white + option -foreground default -black + + propagate -background to {comp1 comp2 comp3} + propagate -foreground to {comp1 comp2 comp3} +} + +.CE +.SS "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. +.PP +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. +.PP +If my fancy \fBsnit::widget\fR is called \fB::mylib::mywidget\fR, +for example, then I should define my \fBpropagate\fR macro as +\fB::mylib::propagate\fR: +.CS + +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} +} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsnit\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +BWidget, C++, Incr Tcl, adaptors, class, mega widget, object, object oriented, widget, widget adaptors +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2003-2006, by William H. Duquette + +.fi ADDED embedded/man/files/modules/soundex/soundex.n Index: embedded/man/files/modules/soundex/soundex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/soundex/soundex.n @@ -0,0 +1,293 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/soundex/soundex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) ????, Algorithm: Donald E. Knuth +'\" Copyright (c) 2003, Documentation: Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 1998, Tcl port: Evan Rempel <erempel@uvic.ca> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "soundex" n 1.0 tcllib "Soundex" +.BS +.SH NAME +soundex \- Soundex +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBsoundex ?1.0?\fR +.sp +\fB::soundex::knuth\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides soundex algorithms which allow the +comparison of words based on their phonetic likeness. +.PP +Currently only an algorithm by Knuth is provided, which +is tuned to english names and words. +.TP +\fB::soundex::knuth\fR \fIstring\fR +Computes the soundex code of the input \fIstring\fR using +Knuth's algorithm and returns it as the result of the +command. +.PP +.SH EXAMPLES +.CS + + + % ::soundex::knuth Knuth + K530 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIsoundex\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +knuth, soundex, text comparison, text likeness +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) ????, Algorithm: Donald E. Knuth +Copyright (c) 2003, Documentation: Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 1998, Tcl port: Evan Rempel <erempel@uvic.ca> + +.fi ADDED embedded/man/files/modules/stooop/stooop.n Index: embedded/man/files/modules/stooop/stooop.n ================================================================== --- /dev/null +++ embedded/man/files/modules/stooop/stooop.n @@ -0,0 +1,447 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/stooop/stooop.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "stooop" n 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming" +.BS +.SH NAME +stooop \- Object oriented extension. +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBstooop ?4.4.1?\fR +.sp +\fB::stooop::class\fR \fIname body\fR +.sp +\fB::stooop::new\fR \fIclass\fR ?\fIarg arg ...\fR? +.sp +\fB::stooop::delete\fR \fIobject\fR ?\fIobject ...\fR? +.sp +\fB::stooop::virtual\fR \fBproc\fR \fIname\fR {\fBthis\fR ?\fIarg arg ...\fR?} ?\fIbody\fR? +.sp +\fB::stooop::classof\fR \fIobject\fR +.sp +\fB::stooop::new\fR \fIobject\fR +.sp +\fB::stooop::printObjects\fR ?\fIpattern\fR? +.sp +\fB::stooop::record\fR +.sp +\fB::stooop::report\fR ?\fIpattern\fR? +.sp +.BE +.SH DESCRIPTION +.PP +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: \fBclass\fR, \fBnew\fR, \fBdelete\fR, +\fBvirtual\fR and \fBclassof\fR. 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. +.PP +This manual is very succinct and is to be used as a quick reminder for +the programmer, who should have read the thorough \fIstooop_man.html\fR +HTML documentation at this point. +.TP +\fB::stooop::class\fR \fIname body\fR +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 \fBclass::\fR, as you would +proceed with namespace procedures. +.RS +.TP +\fBproc\fR \fIclass\fR {\fBthis\fR ?\fIarg arg ...\fR?} ?\fIbase\fR {?\fIarg arg ...\fR?} ...? \fIbody\fR +This is the constructor procedure for the class. It is invoked +following a \fBnew\fR invocation on the class. It must have the same +name as the class and a first argument named \fBthis\fR. Any number +of base classes specifications, including arguments to be passed to +their constructor, are allowed before the actual body of the +procedure. +.TP +\fBproc\fR ~\fIclass\fR {\fBthis\fR} \fIbody\fR +This is the destructor procedure for the class. It is invoked +following a \fBdelete\fR invocation. Its name must be the +concatenation of a single \fB~\fR character followed by the class +name (as in C++). It must have a single argument named \fBthis\fR. +.TP +\fBproc\fR \fIname\fR {\fBthis\fR ?\fIarg arg ...\fR?} \fIbody\fR +This is a member procedure of the class, as its first argument is +named \fBthis\fR. It allows a simple access of member data for the +object referenced by \fBthis\fR inside the procedure. For example: +.CS + + + set ($this,data) 0 + +.CE +.TP +\fBproc\fR \fIname\fR {?\fIarg arg ...\fR?} \fIbody\fR +This is a static (as in C++) member procedure of the class, as its +first argument is not named \fBthis\fR. Static (global) class data +can be accessed as in: +.CS + + + set (data) 0 + +.CE +.TP +\fBproc\fR \fIclass\fR {\fBthis copy\fR} \fIbody\fR +This is the optional copy procedure for the class. It must have the +same name as the class and exactly 2 arguments named \fBthis\fR and +\fBcopy\fR. It is invoked following a \fBnew\fR invocation on an +existing object of the class. +.RE +.TP +\fB::stooop::new\fR \fIclass\fR ?\fIarg arg ...\fR? +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. +.TP +\fB::stooop::delete\fR \fIobject\fR ?\fIobject ...\fR? +This command is used to delete one or several objects. It takes one or +more object identifiers as argument(s). +.TP +\fB::stooop::virtual\fR \fBproc\fR \fIname\fR {\fBthis\fR ?\fIarg arg ...\fR?} ?\fIbody\fR? +The \fBvirtual\fR 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. +.TP +\fB::stooop::classof\fR \fIobject\fR +This command returns the class of the existing object passed as single +parameter. +.TP +\fB::stooop::new\fR \fIobject\fR +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. +.PP +.SH DEBUGGING +.TP +Environment variables +.RS +.TP +\fBSTOOOPCHECKDATA\fR +Setting this variable to any true value will cause stooop to check for +invalid member or class data access. +.TP +\fBSTOOOPCHECKPROCEDURES\fR +Setting this variable to any true value will cause stooop to check for +invalid member procedure arguments and pure interface classes +instanciation. +.TP +\fBSTOOOPCHECKALL\fR +Setting this variable to any true value will cause stooop to activate +both procedure and data member checking. +.TP +\fBSTOOOPCHECKOBJECTS\fR +Setting this variable to any true value will cause stooop to activate +object checking. The following stooop namespace procedures then become +available for debugging: \fBprintObjects\fR, \fBrecord\fR and +\fBreport\fR. +.TP +\fBSTOOOPTRACEPROCEDURES\fR +Setting this environment variable to either \fBstdout\fR, +\fBstderr\fR 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. +.TP +\fBSTOOOPTRACEPROCEDURESFORMAT\fR +Defines the trace procedures output format. Defaults to +\fB"class: %C, procedure: %p, object: %O, arguments: %a"\fR. +.TP +\fBSTOOOPTRACEDATA\fR +Setting this environment variable to either \fBstdout\fR, +\fBstderr\fR 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. +.TP +\fBSTOOOPTRACEDATAFORMAT\fR +Defines the trace data output format. Defaults to +\fB"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v"\fR. +.TP +\fBSTOOOPTRACEDATAOPERATIONS\fR +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 \fBr\fR, \fBw\fR, and \fBu\fR for +more specific tracing (please refer to the \fBtrace\fR Tcl manual page +for more information). +.TP +\fBSTOOOPTRACEALL\fR +Setting this environment variable to either \fBstdout\fR, +\fBstderr\fR or a file name, enables both procedure and data +tracing. +.RE +.TP +\fB::stooop::printObjects\fR ?\fIpattern\fR? +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 \fBstring match\fR command) can be used to +limit the output to matching class names. +.TP +\fB::stooop::record\fR +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. +.TP +\fB::stooop::report\fR ?\fIpattern\fR? +Prints the created and deleted objects since the \fB::stooop::record\fR +procedure was invoked last. If present, the pattern argument limits +the output to matching class names. +.PP +.SH EXAMPLES +Please see the full HTML documentation in \fIstooop_man.html\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstooop\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +C++, class, object, object oriented +.SH CATEGORY +Programming tools ADDED embedded/man/files/modules/stringprep/stringprep.n Index: embedded/man/files/modules/stringprep/stringprep.n ================================================================== --- /dev/null +++ embedded/man/files/modules/stringprep/stringprep.n @@ -0,0 +1,358 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/stringprep/stringprep.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2009, Sergei Golovan <sgolovan@nes.ru> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "stringprep" n 1.0.1 tcllib "Preparation of Internationalized Strings" +.BS +.SH NAME +stringprep \- Implementation of stringprep +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBstringprep 1.0.1\fR +.sp +\fB::stringprep::register\fR \fIprofile\fR ?\fI-mapping list\fR? ?\fI-normalization form\fR? ?\fI-prohibited list\fR? ?\fI-prohibitedList list\fR? ?\fI-prohibitedCommand command\fR? ?\fI-prohibitedBidi boolean\fR? +.sp +\fB::stringprep::stringprep\fR \fIprofile\fR \fIstring\fR +.sp +\fB::stringprep::compare\fR \fIprofile\fR \fIstring1\fR \fIstring2\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::stringprep::register\fR \fIprofile\fR ?\fI-mapping list\fR? ?\fI-normalization form\fR? ?\fI-prohibited list\fR? ?\fI-prohibitedList list\fR? ?\fI-prohibitedCommand command\fR? ?\fI-prohibitedBidi boolean\fR? +Register the \fBstringprep\fR profile named \fIprofile\fR. Options +are the following. +.sp +Option \fI-mapping\fR specifies \fBstringprep\fR 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. +.sp +Option \fI-normalization\fR 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. +.sp +Option \fI-prohibited\fR 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}. +.sp +Option \fI-prohibitedList\fR 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} (\\" \\& \\' / : < > @). +.sp +Option \fI-prohibitedCommand\fR 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 \fI-prohibitedList\fR is too large. +.sp +Option \fI-prohibitedBidi\fR takes boolean value and if it is true then the +bidirectional character processing rules defined in section 6 of RFC-3454 are +used. +.TP +\fB::stringprep::stringprep\fR \fIprofile\fR \fIstring\fR +Performs \fBstringprep\fR operations defined in profile \fIprofile\fR +to string \fIstring\fR. Result is a prepared string or one of the following +errors: \fIinvalid_profile\fR (profile \fIprofile\fR is not defined), +\fIprohibited_character\fR (string \fIstring\fR contains a prohibited character) +or \fIprohibited_bidi\fR (string \fIstring\fR contains a prohibited bidirectional +sequence). +.TP +\fB::stringprep::compare\fR \fIprofile\fR \fIstring1\fR \fIstring2\fR +Compares two unicode strings prepared accordingly to \fBstringprep\fR +profile \fIprofile\fR. The command returns 0 if prepared strings are equal, +-1 if \fIstring1\fR is lexicographically less than \fIstring2\fR, or +1 if \fIstring1\fR is lexicographically greater than \fIstring2\fR. +.PP +.SH EXAMPLES +Nameprep profile definition (see RFC-3491): +.CS + + +::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 + +.CE +Nodeprep and resourceprep profile definitions (see RFC-3920): +.CS + + +::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 + +.CE +.SH REFERENCES +.IP [1] +"Preparation of Internationalized Strings ('stringprep')", +(\fIhttp://www.ietf.org/rfc/rfc3454.txt\fR) +.IP [2] +"Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)", +(\fIhttp://www.ietf.org/rfc/rfc3491.txt\fR) +.IP [3] +"Extensible Messaging and Presence Protocol (XMPP): Core", +(\fIhttp://www.ietf.org/rfc/rfc3920.txt\fR) +.PP +.SH AUTHORS +Sergei Golovan +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstringprep\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +unicode(n) +.SH KEYWORDS +stringprep, unicode +.SH COPYRIGHT +.nf +Copyright (c) 2007-2009, Sergei Golovan <sgolovan@nes.ru> + +.fi ADDED embedded/man/files/modules/stringprep/stringprep_data.n Index: embedded/man/files/modules/stringprep/stringprep_data.n ================================================================== --- /dev/null +++ embedded/man/files/modules/stringprep/stringprep_data.n @@ -0,0 +1,271 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/stringprep/stringprep_data.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2009, Sergei Golovan <sgolovan@nes.ru> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "stringprep::data" n 1.0.1 tcllib "Preparation of Internationalized Strings" +.BS +.SH NAME +stringprep::data \- stringprep data tables, generated, internal +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBstringprep::data 1.0.1\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBstringprep::data\fR package is a helper for +\fBstringprep\fR, providing it with the data tables needed to +perform its functions. It is an \fIinternal\fR 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstringprep\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +stringprep, unicode +.SH COPYRIGHT +.nf +Copyright (c) 2007-2009, Sergei Golovan <sgolovan@nes.ru> + +.fi ADDED embedded/man/files/modules/stringprep/unicode.n Index: embedded/man/files/modules/stringprep/unicode.n ================================================================== --- /dev/null +++ embedded/man/files/modules/stringprep/unicode.n @@ -0,0 +1,326 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/stringprep/unicode.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007, Sergei Golovan <sgolovan@nes.ru> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "unicode" n 1.0.0 tcllib "Unicode normalization" +.BS +.SH NAME +unicode \- Implementation of Unicode normalization +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBunicode 1.0\fR +.sp +\fB::unicode::fromstring\fR \fIstring\fR +.sp +\fB::unicode::tostring\fR \fIuclist\fR +.sp +\fB::unicode::normalize\fR \fIform\fR \fIuclist\fR +.sp +\fB::unicode::normalizeS\fR \fIform\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +.PP +This is an implementation in Tcl of the Unicode normalization forms. +.SH COMMANDS +.TP +\fB::unicode::fromstring\fR \fIstring\fR +Converts \fIstring\fR to list of integer Unicode character codes which +is used in \fBunicode\fR for internal string representation. +.TP +\fB::unicode::tostring\fR \fIuclist\fR +Converts list of integers \fIuclist\fR back to Tcl string. +.TP +\fB::unicode::normalize\fR \fIform\fR \fIuclist\fR +Normalizes Unicode characters list \fIulist\fR according to \fIform\fR +and returns the normalized list. Form \fIform\fR takes one of the following +values: \fID\fR (canonical decomposition), \fIC\fR (canonical decomposition, followed +by canonical composition), \fIKD\fR (compatibility decomposition), or \fIKC\fR +(compatibility decomposition, followed by canonical composition). +.TP +\fB::unicode::normalizeS\fR \fIform\fR \fIstring\fR +A shortcut to +::unicode::tostring [unicode::normalize \\$form [::unicode::fromstring \\$string]]. +Normalizes Tcl string and returns normalized string. +.PP +.SH EXAMPLES +.CS + + +% ::unicode::fromstring "\\u0410\\u0411\\u0412\\u0413" +1040 1041 1042 1043 +% ::unicode::tostring {49 50 51 52 53} +12345 +% + +.CE +.CS + + +% ::unicode::normalize D {7692 775} +68 803 775 +% ::unicode::normalizeS KD "\\u1d2c" +A +% + +.CE +.SH REFERENCES +.IP [1] +"Unicode Standard Annex #15: Unicode Normalization Forms", +(\fIhttp://unicode.org/reports/tr15/\fR) +.PP +.SH AUTHORS +Sergei Golovan +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstringprep\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +stringprep(n) +.SH KEYWORDS +normalization, unicode +.SH COPYRIGHT +.nf +Copyright (c) 2007, Sergei Golovan <sgolovan@nes.ru> + +.fi ADDED embedded/man/files/modules/stringprep/unicode_data.n Index: embedded/man/files/modules/stringprep/unicode_data.n ================================================================== --- /dev/null +++ embedded/man/files/modules/stringprep/unicode_data.n @@ -0,0 +1,271 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/stringprep/unicode_data.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007, Sergei Golovan <sgolovan@nes.ru> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "unicode::data" n 1.0.0 tcllib "Preparation of Internationalized Strings" +.BS +.SH NAME +unicode::data \- unicode data tables, generated, internal +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBunicode::data 1.0.0\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBunicode::data\fR package is a helper for +\fBunicode\fR, providing it with the data tables needed to +perform its functions. It is an \fIinternal\fR 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstringprep\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +stringprep, unicode +.SH COPYRIGHT +.nf +Copyright (c) 2007, Sergei Golovan <sgolovan@nes.ru> + +.fi ADDED embedded/man/files/modules/struct/disjointset.n Index: embedded/man/files/modules/struct/disjointset.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/disjointset.n @@ -0,0 +1,391 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/disjointset.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::disjointset" n 1.0 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::disjointset \- Disjoint set data structure +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::disjointset ?1.0?\fR +.sp +\fB::struct::disjointset\fR \fIdisjointsetName\fR +.sp +\fIdisjointsetName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIdisjointsetName\fR \fBadd-partition\fR \fIelements\fR +.sp +\fIdisjointsetName\fR \fBpartitions\fR +.sp +\fIdisjointsetName\fR \fBnum-partitions\fR +.sp +\fIdisjointsetName\fR \fBequal\fR \fIa\fR \fIb\fR +.sp +\fIdisjointsetName\fR \fBmerge\fR \fIa\fR \fIb\fR +.sp +\fIdisjointsetName\fR \fBfind\fR \fIe\fR +.sp +\fIdisjointsetName\fR \fBdestroy\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides \fIdisjoint sets\fR. An alternative name for +this kind of structure is \fImerge-find\fR. +.PP +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. +.PP +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 \fImerge-find\fR for this. +.PP +Why now is this named a \fIdisjoint-set\fR ? +Because another way of describing the whole situation is that we have +.IP \(bu +a finite \fIset\fR S, containing +.IP \(bu +a number of \fIelements\fR E, split into +.IP \(bu +a set of \fIpartitions\fR 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. +.IP \(bu +An alternative name for the \fIpartitions\fR would be +\fIequvalence classes\fR, and all elements in the same +class are considered as equal. +.PP +Here is a pictorial representation of the concepts listed above: +.CS + + + +-----------------+ 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. + | / * \\ | + | / * / | + | * /\\ * / | + | / \\ / | + | / \\/ * | + | / * \\ | + | / * \\ | + +-----------------+ + +.CE +.PP +For more information see \fIhttp://en.wikipedia.org/wiki/Disjoint_set_data_structure\fR. +.SH API +The package exports a single command, \fB::struct::disjointset\fR. All +functionality provided here can be reached through a subcommand of +this command. +.PP +.TP +\fB::struct::disjointset\fR \fIdisjointsetName\fR +Creates a new disjoint set object with an associated global Tcl +command whose name is \fIdisjointsetName\fR. This command may be used +to invoke various operations on the disjointset. It has the following +general form: +.RS +.TP +\fIdisjointsetName\fR \fIoption\fR ?\fIarg arg ...\fR? +The \fBoption\fR and the \fIarg\fRs determine the exact behavior of +the command. The following commands are possible for disjointset +objects: +.RE +.TP +\fIdisjointsetName\fR \fBadd-partition\fR \fIelements\fR +Creates a new partition in specified disjoint set, and fills it with +the values found in the set of \fIelements\fR. The command maintains +the integrity of the disjoint set, i.e. it verifies that none of the +\fIelements\fR are already part of the disjoint set and throws an +error otherwise. +.sp +The result of the command is the empty string. +.TP +\fIdisjointsetName\fR \fBpartitions\fR +Returns the set of partitions the named disjoint set currently +consists of. +.TP +\fIdisjointsetName\fR \fBnum-partitions\fR +Returns the number of partitions the named disjoint set currently +consists of. +.TP +\fIdisjointsetName\fR \fBequal\fR \fIa\fR \fIb\fR +Determines if the two elements \fIa\fR and \fIb\fR of the disjoint set +belong to the same partition. The result of the method is a boolean +value, \fBTrue\fR if the two elements are contained in the same +partition, and \fBFalse\fR otherwise. +.sp +An error will be thrown if either \fIa\fR or \fIb\fR are not elements +of the disjoint set. +.TP +\fIdisjointsetName\fR \fBmerge\fR \fIa\fR \fIb\fR +Determines the partitions the elements \fIa\fR and \fIb\fR are +contained in and merges them into a single partition. If the two +elements were already contained in the same partition nothing will +change. +.sp +The result of the method is the empty string. +.TP +\fIdisjointsetName\fR \fBfind\fR \fIe\fR +Returns the partition of the disjoint set which contains the element +\fIe\fR. +.TP +\fIdisjointsetName\fR \fBdestroy\fR +Destroys the disjoint set object and all associated memory. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: disjointset\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +disjoint set, equivalence class, find, merge find, partition, partitioned set, union +.SH CATEGORY +Data structures ADDED embedded/man/files/modules/struct/graph.n Index: embedded/man/files/modules/struct/graph.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/graph.n @@ -0,0 +1,1130 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/graph.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::graph" n 2.4 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::graph \- Create and manipulate directed graph objects +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::graph ?2.4?\fR +.sp +package require \fBstruct::list ?1.5?\fR +.sp +package require \fBstruct::set ?2.2.3?\fR +.sp +\fB::struct::graph\fR ?\fIgraphName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +.sp +\fBgraphName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIgraphName\fR \fB=\fR \fIsourcegraph\fR +.sp +\fIgraphName\fR \fB-->\fR \fIdestgraph\fR +.sp +\fIgraphName\fR \fBappend\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBdeserialize\fR \fIserialization\fR +.sp +\fIgraphName\fR \fBdestroy\fR +.sp +\fIgraphName\fR \fBarc append\fR \fIarc\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBarc attr\fR \fIkey\fR +.sp +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-arcs\fR \fIlist\fR +.sp +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.sp +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +.sp +\fIgraphName\fR \fBarc delete\fR \fIarc\fR ?\fIarc\fR ...? +.sp +\fIgraphName\fR \fBarc exists\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc flip\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc get\fR \fIarc\fR \fIkey\fR +.sp +\fIgraphName\fR \fBarc getall\fR \fIarc\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBarc getunweighted\fR +.sp +\fIgraphName\fR \fBarc getweight\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc keys\fR \fIarc\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBarc keyexists\fR \fIarc\fR \fIkey\fR +.sp +\fIgraphName\fR \fBarc insert\fR \fIstart\fR \fIend\fR ?\fIchild\fR? +.sp +\fIgraphName\fR \fBarc lappend\fR \fIarc\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBarc rename\fR \fIarc\fR \fInewname\fR +.sp +\fIgraphName\fR \fBarc set\fR \fIarc\fR \fIkey\fR ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBarc setunweighted\fR ?\fIweight\fR? +.sp +\fIgraphName\fR \fBarc setweight\fR \fIarc\fR \fIweight\fR +.sp +\fIgraphName\fR \fBarc unsetweight\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc hasweight\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc source\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc target\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc nodes\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc move-source\fR \fIarc\fR \fInewsource\fR +.sp +\fIgraphName\fR \fBarc move-target\fR \fIarc\fR \fInewtarget\fR +.sp +\fIgraphName\fR \fBarc move\fR \fIarc\fR \fInewsource\fR \fInewtarget\fR +.sp +\fIgraphName\fR \fBarc unset\fR \fIarc\fR \fIkey\fR +.sp +\fIgraphName\fR \fBarc weights\fR +.sp +\fIgraphName\fR \fBarcs\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-filter \fIcmdprefix\fR? ?-in|-out|-adj|-inner|-embedding \fInode node...\fR? +.sp +\fIgraphName\fR \fBlappend\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBnode append\fR \fInode\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBnode attr\fR \fIkey\fR +.sp +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-nodes\fR \fIlist\fR +.sp +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.sp +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +.sp +\fIgraphName\fR \fBnode degree\fR ?-in|-out? \fInode\fR +.sp +\fIgraphName\fR \fBnode delete\fR \fInode\fR ?\fInode\fR...? +.sp +\fIgraphName\fR \fBnode exists\fR \fInode\fR +.sp +\fIgraphName\fR \fBnode get\fR \fInode\fR \fIkey\fR +.sp +\fIgraphName\fR \fBnode getall\fR \fInode\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBnode keys\fR \fInode\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBnode keyexists\fR \fInode\fR \fIkey\fR +.sp +\fIgraphName\fR \fBnode insert\fR ?\fInode\fR...? +.sp +\fIgraphName\fR \fBnode lappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +.sp +\fIgraphName\fR \fBnode opposite\fR \fInode\fR \fIarc\fR +.sp +\fIgraphName\fR \fBnode rename\fR \fInode\fR \fInewname\fR +.sp +\fIgraphName\fR \fBnode set\fR \fInode\fR \fIkey\fR ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBnode unset\fR \fInode\fR \fIkey\fR +.sp +\fIgraphName\fR \fBnodes\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-filter \fIcmdprefix\fR? ?-in|-out|-adj|-inner|-embedding \fInode\fR \fInode\fR...? +.sp +\fIgraphName\fR \fBget\fR \fIkey\fR +.sp +\fIgraphName\fR \fBgetall\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBkeys\fR ?\fIpattern\fR? +.sp +\fIgraphName\fR \fBkeyexists\fR \fIkey\fR +.sp +\fIgraphName\fR \fBserialize\fR ?\fInode\fR...? +.sp +\fIgraphName\fR \fBset\fR \fIkey\fR ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBswap\fR \fInode1\fR \fInode2\fR +.sp +\fIgraphName\fR \fBunset\fR \fIkey\fR +.sp +\fIgraphName\fR \fBwalk\fR \fInode\fR ?-order \fIorder\fR? ?-type \fItype\fR? ?-dir \fIdirection\fR? -command \fIcmd\fR +.sp +.BE +.SH DESCRIPTION +.PP +A directed graph is a structure containing two collections of +elements, called \fInodes\fR and \fIarcs\fR respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs. +.PP +Each arc is connected to two nodes, one of which is called the +\fIsource\fR and the other the \fItarget\fR. 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 \fIloop\fR. +Whenever a node is either the source or target of an arc both are said +to be \fIadjacent\fR. This extends into a relation between nodes, +i.e. if two nodes are connected through at least one arc they are said +to be \fIadjacent\fR too. +.PP +Each node can be the source and target for any number of arcs. The +former are called the \fIoutgoing arcs\fR of the node, the latter +the \fIincoming arcs\fR of the node. The number of arcs in either +set is called the \fIin-degree\fR resp. the \fIout-degree\fR of the +node. +.PP +In addition to maintaining the node and arc relationships, this graph +implementation allows any number of named \fIattributes\fR to be +associated with the graph itself, and each node or arc. +.PP +\fINote:\fR The major version of the package \fBstruct\fR has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +\fBChanges for 2.0\fR for a full list of all changes, +incompatible and otherwise. +.PP +\fINote:\fR A C-implementation of the command can be had from the +location \fIhttp://www.purl.org/NET/schlenker/tcl/cgraph\fR. See also +\fIhttp://wiki.tcl.tk/cgraph\fR. 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. +.PP +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. +.PP +The main command of the package is: +.TP +\fB::struct::graph\fR ?\fIgraphName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +The command creates a new graph object with an associated global Tcl +command whose name is \fIgraphName\fR. This command may be used to +invoke various operations on the graph. It has the following general +form: +.RS +.TP +\fBgraphName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.sp +If \fIgraphName\fR is not specified a unique name will be generated by +the package itself. If a \fIsource\fR is specified the new graph will +be initialized to it. For the operators \fB=\fR, \fB:=\fR, and +\fBas\fR the \fIsource\fR argument is interpreted as the name of +another graph object, and the assignment operator \fB=\fR will be +executed. For the operator \fBdeserialize\fR the \fIsource\fR is a +serialized graph object and \fBdeserialize\fR will be executed. +.sp +In other words +.sp +.CS + + + ::struct::graph mygraph = b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::graph mygraph + mygraph = b + +.CE +.sp +and +.sp +.CS + + + ::struct::graph mygraph deserialize $b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::graph mygraph + mygraph deserialize $b + +.CE +.PP +.PP +The following commands are possible for graph objects: +.TP +\fIgraphName\fR \fB=\fR \fIsourcegraph\fR +This is the \fIassignment\fR operator for graph objects. It copies +the graph contained in the graph object \fIsourcegraph\fR over the +graph data in \fIgraphName\fR. The old contents of \fIgraphName\fR are +deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIgraphName\fR \fBdeserialize\fR [\fIsourcegraph\fR \fBserialize\fR] + +.CE +.sp +The operation assumes that the \fIsourcegraph\fR provides the method +\fBserialize\fR and that this method returns a valid graph +serialization. +.TP +\fIgraphName\fR \fB-->\fR \fIdestgraph\fR +This is the \fIreverse assignment\fR operator for graph objects. It +copies the graph contained in the graph object \fIgraphName\fR over +the graph data in the object \fIdestgraph\fR. +The old contents of \fIdestgraph\fR are deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdestgraph\fR \fBdeserialize\fR [\fIgraphName\fR \fBserialize\fR] + +.CE +.sp +The operation assumes that the \fIdestgraph\fR provides the method +\fBdeserialize\fR and that this method takes a graph serialization. +.TP +\fIgraphName\fR \fBappend\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with the graph. +Returns the new value given to the attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBdeserialize\fR \fIserialization\fR +This is the complement to \fBserialize\fR. It replaces the graph +data in \fIgraphName\fR with the graph described by the +\fIserialization\fR value. The old contents of \fIgraphName\fR are +deleted by this operation. +.TP +\fIgraphName\fR \fBdestroy\fR +Destroys the graph, including its storage space and associated command. +.TP +\fIgraphName\fR \fBarc append\fR \fIarc\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +\fIarc\fR. Returns the new value given to the attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBarc attr\fR \fIkey\fR +.TP +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-arcs\fR \fIlist\fR +.TP +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.TP +\fIgraphName\fR \fBarc attr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +This method retrieves the value of the attribute named \fIkey\fR, for +all arcs in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute. +.sp +The result is a dictionary mapping from arc names to the value of +attribute \fIkey\fR at that arc. +Arcs not having the attribute \fIkey\fR, or not passing a +specified restriction, are not listed in the result. +.sp +The possible restrictions are: +.RS +.TP +\fB-arcs\fR +The value is a list of arcs. Only the arcs mentioned in this list +are searched for the attribute. +.TP +\fB-glob\fR +The value is a glob pattern. Only the arcs in the graph whose names +match this pattern are searched for the attribute. +.TP +\fB-regexp\fR +The value is a regular expression. Only the arcs in the graph whose +names match this pattern are searched for the attribute. +.RE +.sp +.TP +\fIgraphName\fR \fBarc delete\fR \fIarc\fR ?\fIarc\fR ...? +Remove the specified arcs from the graph. +.TP +\fIgraphName\fR \fBarc exists\fR \fIarc\fR +Return true if the specified \fIarc\fR exists in the graph. +.TP +\fIgraphName\fR \fBarc flip\fR \fIarc\fR +Reverses the direction of the named \fIarc\fR, i.e. the source and +target nodes of the arc are exchanged with each other. +.TP +\fIgraphName\fR \fBarc get\fR \fIarc\fR \fIkey\fR +Returns the value associated with the key \fIkey\fR for the \fIarc\fR. +.TP +\fIgraphName\fR \fBarc getall\fR \fIarc\fR ?\fIpattern\fR? +Returns a dictionary (suitable for use with [\fBarray set\fR]) +for the \fIarc\fR. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a \fBglob\fR pattern. +.TP +\fIgraphName\fR \fBarc getunweighted\fR +Returns a list containing the names of all arcs in the graph which +have no weight associated with them. +.TP +\fIgraphName\fR \fBarc getweight\fR \fIarc\fR +Returns the weight associated with the \fIarc\fR. Throws an error if +the arc has no weight associated with it. +.TP +\fIgraphName\fR \fBarc keys\fR \fIarc\fR ?\fIpattern\fR? +Returns a list of keys for the \fIarc\fR. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +\fBglob\fR pattern. +.TP +\fIgraphName\fR \fBarc keyexists\fR \fIarc\fR \fIkey\fR +Return true if the specified \fIkey\fR exists for the \fIarc\fR. +.TP +\fIgraphName\fR \fBarc insert\fR \fIstart\fR \fIend\fR ?\fIchild\fR? +Insert an arc named \fIchild\fR into the graph beginning at the node +\fIstart\fR and ending at the node \fIend\fR. If the name of the new +arc is not specified the system will generate a unique name of the +form \fIarc\fR\fIx\fR. +.TP +\fIgraphName\fR \fBarc lappend\fR \fIarc\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fIarc\fR. Returns the new value given to the +attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBarc rename\fR \fIarc\fR \fInewname\fR +Renames the arc \fIarc\fR to \fInewname\fR. An error is thrown if +either the arc does not exist, or a arc with name \fInewname\fR does +exist. The result of the command is the new name of the arc. +.TP +\fIgraphName\fR \fBarc set\fR \fIarc\fR \fIkey\fR ?\fIvalue\fR? +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 \fIvalue\fR is not specified, this command returns the current value assigned to the key; +if \fIvalue\fR is specified, this command assigns that value to the key, and returns +that value. +.TP +\fIgraphName\fR \fBarc setunweighted\fR ?\fIweight\fR? +Sets the weight of all arcs without a weight to \fIweight\fR. Returns +the empty string as its result. If not present \fIweight\fR defaults +to \fB0\fR. +.TP +\fIgraphName\fR \fBarc setweight\fR \fIarc\fR \fIweight\fR +Sets the weight of the \fIarc\fR to \fIweight\fR. Returns \fIweight\fR. +.TP +\fIgraphName\fR \fBarc unsetweight\fR \fIarc\fR +Removes the weight of the \fIarc\fR, if present. Does nothing +otherwise. Returns the empty string. +.TP +\fIgraphName\fR \fBarc hasweight\fR \fIarc\fR +Determines if the \fIarc\fR has a weight associated with it. The +result is a boolean value, \fBTrue\fR if a weight is defined, and +\fBFalse\fR otherwise. +.TP +\fIgraphName\fR \fBarc source\fR \fIarc\fR +Return the node the given \fIarc\fR begins at. +.TP +\fIgraphName\fR \fBarc target\fR \fIarc\fR +Return the node the given \fIarc\fR ends at. +.TP +\fIgraphName\fR \fBarc nodes\fR \fIarc\fR +Return the nodes the given \fIarc\fR begins and ends at, +as a two-element list. +.TP +\fIgraphName\fR \fBarc move-source\fR \fIarc\fR \fInewsource\fR +Changes the source node of the arc to \fInewsource\fR. It can be said +that the arc rotates around its target node. +.TP +\fIgraphName\fR \fBarc move-target\fR \fIarc\fR \fInewtarget\fR +Changes the target node of the arc to \fInewtarget\fR. It can be said +that the arc rotates around its source node. +.TP +\fIgraphName\fR \fBarc move\fR \fIarc\fR \fInewsource\fR \fInewtarget\fR +Changes both source and target nodes of the arc to \fInewsource\fR, +and \fInewtarget\fR resp. +.TP +\fIgraphName\fR \fBarc unset\fR \fIarc\fR \fIkey\fR +Remove a keyed value from the arc \fIarc\fR. The method will do +nothing if the \fIkey\fR does not exist. +.TP +\fIgraphName\fR \fBarc weights\fR +Returns a dictionary whose keys are the names of all arcs which have a +weight associated with them, and the values are these weights. +.TP +\fIgraphName\fR \fBarcs\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-filter \fIcmdprefix\fR? ?-in|-out|-adj|-inner|-embedding \fInode node...\fR? +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. +.sp +The restrictions imposed by either \fB-in\fR, \fB-out\fR, +\fB-adj\fR, \fB-inner\fR, or \fB-embedded\fR are applied +first. Specifying more than one of them is illegal. +.sp +After that the restrictions set via \fB-key\fR (and +\fB-value\fR) are applied. Specifying more than one \fB-key\fR +(and \fB-value\fR) is illegal. Specifying \fB-value\fR alone, +without \fB-key\fR is illegal as well. +.sp +Any restriction set through \fB-filter\fR is applied +last. Specifying more than one \fB-filter\fR is illegal. +.sp +Coming back to the restrictions based on a set of nodes, the command +recognizes the following switches: +.RS +.TP +\fB-in\fR +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. +.TP +\fB-out\fR +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. +.TP +\fB-adj\fR +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 \fB-in\fR and +\fB-out\fR. +.TP +\fB-inner\fR +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. +.TP +\fB-embedding\fR +Return a list of all arcs adjacent to exactly one of the nodes in the +set. This is the set of arcs connecting the subgraph spawned by the +specified nodes to the rest of the graph. +.TP +\fB-key\fR \fIkey\fR +Limit the list of arcs that are returned to those arcs that have an +associated key \fIkey\fR. +.TP +\fB-value\fR \fIvalue\fR +This restriction can only be used in combination with +\fB-key\fR. It limits the list of arcs that are returned to those +arcs whose associated key \fIkey\fR has the value \fIvalue\fR. +.TP +\fB-filter\fR \fIcmdrefix\fR +Limit the list of arcs that are returned to those arcs that pass the +test. The command in \fIcmdprefix\fR 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 \fBfalse\fR are removed +from the result list before it is returned to the caller. +.RE +.TP +\fIgraphName\fR \fBlappend\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with the graph. Returns the new value given to the +attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBnode append\fR \fInode\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +\fInode\fR. Returns the new value given to the attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBnode attr\fR \fIkey\fR +.TP +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-nodes\fR \fIlist\fR +.TP +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.TP +\fIgraphName\fR \fBnode attr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +This method retrieves the value of the attribute named \fIkey\fR, for +all nodes in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute. +.sp +The result is a dictionary mapping from node names to the value of +attribute \fIkey\fR at that node. +Nodes not having the attribute \fIkey\fR, or not passing a +specified restriction, are not listed in the result. +.sp +The possible restrictions are: +.RS +.TP +\fB-nodes\fR +The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute. +.TP +\fB-glob\fR +The value is a glob pattern. Only the nodes in the graph whose names +match this pattern are searched for the attribute. +.TP +\fB-regexp\fR +The value is a regular expression. Only the nodes in the graph whose +names match this pattern are searched for the attribute. +.RE +.sp +.TP +\fIgraphName\fR \fBnode degree\fR ?-in|-out? \fInode\fR +Return the number of arcs adjacent to the specified \fInode\fR. If one +of the restrictions \fB-in\fR or \fB-out\fR is given only the +incoming resp. outgoing arcs are counted. +.TP +\fIgraphName\fR \fBnode delete\fR \fInode\fR ?\fInode\fR...? +Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs. +.TP +\fIgraphName\fR \fBnode exists\fR \fInode\fR +Return true if the specified \fInode\fR exists in the graph. +.TP +\fIgraphName\fR \fBnode get\fR \fInode\fR \fIkey\fR +Return the value associated with the key \fIkey\fR for the \fInode\fR. +.TP +\fIgraphName\fR \fBnode getall\fR \fInode\fR ?\fIpattern\fR? +Returns a dictionary (suitable for use with [\fBarray set\fR]) +for the \fInode\fR. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a \fBglob\fR pattern. +.TP +\fIgraphName\fR \fBnode keys\fR \fInode\fR ?\fIpattern\fR? +Returns a list of keys for the \fInode\fR. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +\fBglob\fR pattern. +.TP +\fIgraphName\fR \fBnode keyexists\fR \fInode\fR \fIkey\fR +Return true if the specified \fIkey\fR exists for the \fInode\fR. +.TP +\fIgraphName\fR \fBnode insert\fR ?\fInode\fR...? +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 +\fInode\fR\fIx\fR for it. +.TP +\fIgraphName\fR \fBnode lappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fInode\fR. Returns the new value given to the +attribute \fIkey\fR. +.TP +\fIgraphName\fR \fBnode opposite\fR \fInode\fR \fIarc\fR +Return the node at the other end of the specified \fIarc\fR, which has +to be adjacent to the given \fInode\fR. +.TP +\fIgraphName\fR \fBnode rename\fR \fInode\fR \fInewname\fR +Renames the node \fInode\fR to \fInewname\fR. An error is thrown if +either the node does not exist, or a node with name \fInewname\fR does +exist. The result of the command is the new name of the node. +.TP +\fIgraphName\fR \fBnode set\fR \fInode\fR \fIkey\fR ?\fIvalue\fR? +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 \fIvalue\fR is not +specified, this command returns the current value assigned to the key; +if \fIvalue\fR is specified, this command assigns that value to the +key. +.TP +\fIgraphName\fR \fBnode unset\fR \fInode\fR \fIkey\fR +Remove a keyed value from the node \fInode\fR. The method will do +nothing if the \fIkey\fR does not exist. +.TP +\fIgraphName\fR \fBnodes\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-filter \fIcmdprefix\fR? ?-in|-out|-adj|-inner|-embedding \fInode\fR \fInode\fR...? +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. +.sp +The possible restrictions are the same as for method +\fBarcs\fR. The exact meanings change slightly, as they operate on +nodes instead of arcs. The command recognizes: +.RS +.TP +\fB-in\fR +Return a list of all nodes with at least one outgoing arc ending in a +node found in the specified set of nodes. Alternatively specified as +the set of source nodes for the \fB-in\fR arcs of the node set. The +\fIincoming neighbours\fR. +.TP +\fB-out\fR +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 \fB-out\fR arcs of the node +set. The \fIoutgoing neighbours\fR. +.TP +\fB-adj\fR +This is the union of the nodes returned by \fB-in\fR and +\fB-out\fR. The \fIneighbours\fR. +.TP +\fB-inner\fR +The set of neighbours (see \fB-adj\fR above) which are also in the +set of nodes. I.e. the intersection between the set of nodes and the +neighbours per \fB-adj\fR. +.TP +\fB-embedding\fR +The set of neighbours (see \fB-adj\fR above) which are not in the +set of nodes. I.e. the difference between the neighbours as per +\fB-adj\fR, and the set of nodes. +.TP +\fB-key\fR \fIkey\fR +Limit the list of nodes that are returned to those nodes that have an +associated key \fIkey\fR. +.TP +\fB-value\fR \fIvalue\fR +This restriction can only be used in combination with +\fB-key\fR. It limits the list of nodes that are returned to those +nodes whose associated key \fIkey\fR has the value \fIvalue\fR. +.TP +\fB-filter\fR \fIcmdrefix\fR +Limit the list of nodes that are returned to those nodes that pass the +test. The command in \fIcmdprefix\fR 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 \fBfalse\fR are removed +from the result list before it is returned to the caller. +.RE +.TP +\fIgraphName\fR \fBget\fR \fIkey\fR +Return the value associated with the key \fIkey\fR for the graph. +.TP +\fIgraphName\fR \fBgetall\fR ?\fIpattern\fR? +Returns a dictionary (suitable for use with [\fBarray set\fR]) +for the whole graph. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a \fBglob\fR pattern. +.TP +\fIgraphName\fR \fBkeys\fR ?\fIpattern\fR? +Returns a list of keys for the whole graph. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +\fBglob\fR pattern. +.TP +\fIgraphName\fR \fBkeyexists\fR \fIkey\fR +Return true if the specified \fIkey\fR exists for the whole graph. +.TP +\fIgraphName\fR \fBserialize\fR ?\fInode\fR...? +This method serializes the sub-graph spanned up by the \fInode\fRs. 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. +.sp +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. +.sp +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, ... +.sp +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 +.RS +.IP [1] +The name of the node to be described, +.IP [2] +A dictionary containing the attributes associated with the node, +.IP [3] +And a list describing all the arcs starting at that node. +.RE +.sp +The elements of the arc list are lists containing three or four +elements each, i.e. +.RS +.IP [1] +The name of the arc described by the element, +.IP [2] +A reference to the destination node of the arc. This reference is an +integer number given the index of that node in the main serialization +list. As that it is greater than or equal to zero, less than the +length of the serialization, and a multiple of three. +\fINote:\fR 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. +.IP [3] +And a dictionary containing the attributes associated with the arc. +.IP [4] +The weight associated with the arc. This value is optional. Its +non-presence means that the arc in question has no weight associated +with it. +.sp +\fINote:\fR This information is new, compared to the +serialization of \fBgraph\fR 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. +.RE +.sp +For all attribute dictionaries they keys are the names of the +attributes, and the values are the values for each name. +.sp +\fINote:\fR The order of the nodes in the serialization has no +relevance, nor has the order of the arcs per node. +.CS + + + # 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. + +.CE +.sp +.TP +\fIgraphName\fR \fBset\fR \fIkey\fR ?\fIvalue\fR? +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 \fIvalue\fR +is not specified, this command returns the current value assigned to +the key; if \fIvalue\fR is specified, this command assigns that value +to the key. +.TP +\fIgraphName\fR \fBswap\fR \fInode1\fR \fInode2\fR +Swap the position of \fInode1\fR and \fInode2\fR in the graph. +.TP +\fIgraphName\fR \fBunset\fR \fIkey\fR +Remove a keyed value from the graph. The method will do nothing if the +\fIkey\fR does not exist. +.TP +\fIgraphName\fR \fBwalk\fR \fInode\fR ?-order \fIorder\fR? ?-type \fItype\fR? ?-dir \fIdirection\fR? -command \fIcmd\fR +Perform a breadth-first or depth-first walk of the graph starting at +the node \fInode\fR going in either the direction of outgoing or +opposite to the incoming arcs. +.sp +The type of walk, breadth-first or depth-first, is determined by the +value of \fItype\fR; \fBbfs\fR indicates breadth-first, +\fBdfs\fR indicates depth-first. Depth-first is the default. +.sp +The order of the walk, pre-order, post-order or both-order is +determined by the value of \fIorder\fR; \fBpre\fR indicates +pre-order, \fBpost\fR indicates post-order, \fBboth\fR 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 +\fIdirection\fR, 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 \fIand\fR after any of its neighbors. The +combination of a breadth-first walk with post- or both-order is illegal. +.sp +The direction of the walk is determined by the value of \fIdir\fR; +\fBbackward\fR indicates the direction opposite to the incoming +arcs, \fBforward\fR indicates the direction of the outgoing arcs. +.sp +As the walk progresses, the command \fIcmd\fR will be evaluated at +each node, with the mode of the call (\fBenter\fR or +\fBleave\fR) and values \fIgraphName\fR and the name of the current +node appended. For a pre-order walk, all nodes are \fBenter\fRed, for a +post-order all nodes are left. In a both-order walk the first visit of +a node \fBenter\fRs it, the second visit \fBleave\fRs it. +.PP +.SH "CHANGES FOR 2.0" +The following noteworthy changes have occurred: +.IP [1] +The API for accessing attributes and their values has been +simplified. +.sp +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 \fIincompatible\fR change allowed us to +simplify the signature of all methods handling attributes. +.sp +Especially the flag \fB-key\fR is not required anymore, even more, +its use is now forbidden. Please read the documentation for the arc +and node methods \fBset\fR, \fBget\fR, \fBgetall\fR, +\fBunset\fR, \fBappend\fR, \fBlappend\fR, \fBkeyexists\fR +and \fBkeys\fR for a description of the new API's. +.IP [2] +The methods \fBkeys\fR and \fBgetall\fR now take an optional +pattern argument and will return only attribute data for keys matching +this pattern. +.IP [3] +Arcs and nodes can now be renamed. See the documentation for the +methods \fBarc rename\fR and \fBnode rename\fR. +.IP [4] +The structure has been extended with API's for the serialization and +deserialization of graph objects, and a number of operations based on +them (graph assignment, copy construction). +.sp +Please read the documentation for the methods \fBserialize\fR, +\fBdeserialize\fR, \fB=\fR, and \fB-->\fR, and the +documentation on the construction of graph objects. +.sp +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. +.IP [5] +A new method, \fBattr\fR, was added to both \fBarc\fR and +\fBnode\fR allowing the query and retrieval of attribute data +without regard to arc and node relationships. +.IP [6] +Both methods \fBarcs\fR and \fBnodes\fR have been extended with +the ability to select arcs and nodes based on an arbitrary filtering +criterium. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: graph\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +adjacent, arc, cgraph, degree, edge, graph, loop, neighbour, node, serialization, subgraph, vertex +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/graph1.n Index: embedded/man/files/modules/struct/graph1.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/graph1.n @@ -0,0 +1,620 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/graph1.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::graph_v1" n 1.2.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::graph_v1 \- Create and manipulate directed graph objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::graph ?1.2.1?\fR +.sp +\fBgraphName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIgraphName\fR \fBdestroy\fR +.sp +\fIgraphName\fR \fBarc append\fR \fIarc\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fIgraphName\fR \fBarc delete\fR \fIarc\fR ?\fIarc\fR ...? +.sp +\fIgraphName\fR \fBarc exists\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc get\fR \fIarc\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBarc getall\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc keys\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc keyexists\fR \fIarc\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBarc insert\fR \fIstart\fR \fIend\fR ?\fIchild\fR? +.sp +\fIgraphName\fR \fBarc lappend\fR \fIarc\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fIgraphName\fR \fBarc set\fR \fIarc\fR ?-key \fIkey\fR? ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBarc source\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc target\fR \fIarc\fR +.sp +\fIgraphName\fR \fBarc unset\fR \fIarc\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBarcs\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-in|-out|-adj|-inner|-embedding \fInodelist\fR? +.sp +\fIgraphName\fR \fBnode append\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fIgraphName\fR \fBnode degree\fR ?-in|-out? \fInode\fR +.sp +\fIgraphName\fR \fBnode delete\fR \fInode\fR ?\fInode\fR ...? +.sp +\fIgraphName\fR \fBnode exists\fR \fInode\fR +.sp +\fIgraphName\fR \fBnode get\fR \fInode\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBnode getall\fR \fInode\fR +.sp +\fIgraphName\fR \fBnode keys\fR \fInode\fR +.sp +\fIgraphName\fR \fBnode keyexists\fR \fInode\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBnode insert\fR ?\fIchild\fR? +.sp +\fIgraphName\fR \fBnode lappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fIgraphName\fR \fBnode opposite\fR \fInode\fR \fIarc\fR +.sp +\fIgraphName\fR \fBnode set\fR \fInode\fR ?-key \fIkey\fR? ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBnode unset\fR \fInode\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBnodes\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-in|-out|-adj|-inner|-embedding \fInodelist\fR? +.sp +\fIgraphName\fR \fBget\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBgetall\fR +.sp +\fIgraphName\fR \fBkeys\fR +.sp +\fIgraphName\fR \fBkeyexists\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBset\fR ?-key \fIkey\fR? ?\fIvalue\fR? +.sp +\fIgraphName\fR \fBswap\fR \fInode1\fR \fInode2\fR +.sp +\fIgraphName\fR \fBunset\fR ?-key \fIkey\fR? +.sp +\fIgraphName\fR \fBwalk\fR \fInode\fR ?-order \fIorder\fR? ?-type \fItype\fR? ?-dir \fIdirection\fR? -command \fIcmd\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::graph\fR command creates a new graph object with an +associated global Tcl command whose name is \fIgraphName\fR. This +command may be used to invoke various operations on the graph. It has +the following general form: +.TP +\fBgraphName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +A directed graph is a structure containing two collections of +elements, called \fInodes\fR and \fIarcs\fR respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs. +.PP +Each arc is connected to two nodes, one of which is called the +\fIsource\fR and the other the \fItarget\fR. 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 \fIloop\fR. Whenever a node is source +or target of an arc both are said to be \fIadjacent\fR. This extends +into a relation between nodes, i.e. if two nodes are connected through +at least one arc they are said to be \fIadjacent\fR too. +.PP +Each node can be the source and target for any number of arcs. The +former are called the \fIoutgoing arcs\fR of the node, the latter +the \fIincoming arcs\fR of the node. The number of edges in either +set is called the \fIin-\fR resp. the \fIout-degree\fR of the node. +.PP +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. +.PP +The following commands are possible for graph objects: +.TP +\fIgraphName\fR \fBdestroy\fR +Destroy the graph, including its storage space and associated command. +.TP +\fIgraphName\fR \fBarc append\fR \fIarc\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +\fIarc\fR. If no \fIkey\fR is specified, the key \fBdata\fR is +assumed. +.TP +\fIgraphName\fR \fBarc delete\fR \fIarc\fR ?\fIarc\fR ...? +Remove the specified arcs from the graph. +.TP +\fIgraphName\fR \fBarc exists\fR \fIarc\fR +Return true if the specified \fIarc\fR exists in the graph. +.TP +\fIgraphName\fR \fBarc get\fR \fIarc\fR ?-key \fIkey\fR? +Return the value associated with the key \fIkey\fR for the \fIarc\fR. +If no key is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBarc getall\fR \fIarc\fR +Returns a serialized list of key/value pairs (suitable for use with +[\fBarray set\fR]) for the \fIarc\fR. +.TP +\fIgraphName\fR \fBarc keys\fR \fIarc\fR +Returns a list of keys for the \fIarc\fR. +.TP +\fIgraphName\fR \fBarc keyexists\fR \fIarc\fR ?-key \fIkey\fR? +Return true if the specified \fIkey\fR exists for the \fIarc\fR. If no +\fIkey\fR is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBarc insert\fR \fIstart\fR \fIend\fR ?\fIchild\fR? +Insert an arc named \fIchild\fR into the graph beginning at the node +\fIstart\fR and ending at the node \fIend\fR. If the name of the new +arc is not specified the system will generate a unique name of the +form \fIarc\fR\fIx\fR. +.TP +\fIgraphName\fR \fBarc lappend\fR \fIarc\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fIarc\fR. If no \fIkey\fR is specified, the key +\fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBarc set\fR \fIarc\fR ?-key \fIkey\fR? ?\fIvalue\fR? +Set or get one of the keyed values associated with an arc. If no key +is specified, the key \fBdata\fR is assumed. Each arc that is +added to a graph has the empty string assigned to the key +\fBdata\fR automatically. An arc may have any number of keyed +values associated with it. If \fIvalue\fR is not specified, this +command returns the current value assigned to the key; if \fIvalue\fR +is specified, this command assigns that value to the key. +.TP +\fIgraphName\fR \fBarc source\fR \fIarc\fR +Return the node the given \fIarc\fR begins at. +.TP +\fIgraphName\fR \fBarc target\fR \fIarc\fR +Return the node the given \fIarc\fR ends at. +.TP +\fIgraphName\fR \fBarc unset\fR \fIarc\fR ?-key \fIkey\fR? +Remove a keyed value from the arc \fIarc\fR. If no key is specified, +the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBarcs\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-in|-out|-adj|-inner|-embedding \fInodelist\fR? +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. +.RS +.TP +\fB-in\fR +Return a list of all arcs whose target is one of the nodes in the +\fInodelist\fR. +.TP +\fB-out\fR +Return a list of all arcs whose source is one of the nodes in the +\fInodelist\fR. +.TP +\fB-adj\fR +Return a list of all arcs adjacent to at least one of the nodes in the +\fInodelist\fR. This is the union of the nodes returned by +\fB-in\fR and \fB-out\fR. +.TP +\fB-inner\fR +Return a list of all arcs adjacent to two of the nodes in the +\fInodelist\fR. This is the set of arcs in the subgraph spawned by the +specified nodes. +.TP +\fB-embedding\fR +Return a list of all arcs adjacent to exactly one of the nodes in the +\fInodelist\fR. This is the set of arcs connecting the subgraph +spawned by the specified nodes to the rest of the graph. +.TP +\fB-key\fR \fIkey\fR +Limit the list of arcs that are returned to those arcs that have an +associated key \fIkey\fR. +.TP +\fB-value\fR \fIvalue\fR +This restriction can only be used in combination with +\fB-key\fR. It limits the list of arcs that are returned to those +arcs whose associated key \fIkey\fR has the value \fIvalue\fR. +.RE +.sp +The restrictions imposed by either \fB-in\fR, \fB-out\fR, +\fB-adj\fR, \fB-inner\fR, or \fB-embedded\fR are applied +first. Specifying more than one of them is illegal. +At last the restrictions set via \fB-key\fR (and \fB-value\fR) +are applied. +Specifying more than one \fB-key\fR (and \fB-value\fR) is +illegal. +.TP +\fIgraphName\fR \fBnode append\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +\fInode\fR. If no \fIkey\fR is specified, the key \fBdata\fR is +assumed. +.TP +\fIgraphName\fR \fBnode degree\fR ?-in|-out? \fInode\fR +Return the number of arcs adjacent to the specified \fInode\fR. If one +of the restrictions \fB-in\fR or \fB-out\fR is given only the +incoming resp. outgoing arcs are counted. +.TP +\fIgraphName\fR \fBnode delete\fR \fInode\fR ?\fInode\fR ...? +Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs. +.TP +\fIgraphName\fR \fBnode exists\fR \fInode\fR +Return true if the specified \fInode\fR exists in the graph. +.TP +\fIgraphName\fR \fBnode get\fR \fInode\fR ?-key \fIkey\fR? +Return the value associated with the key \fIkey\fR for the \fInode\fR. +If no key is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBnode getall\fR \fInode\fR +Returns a serialized list of key/value pairs (suitable for use with +[\fBarray set\fR]) for the \fInode\fR. +.TP +\fIgraphName\fR \fBnode keys\fR \fInode\fR +Returns a list of keys for the \fInode\fR. +.TP +\fIgraphName\fR \fBnode keyexists\fR \fInode\fR ?-key \fIkey\fR? +Return true if the specified \fIkey\fR exists for the \fInode\fR. If +no \fIkey\fR is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBnode insert\fR ?\fIchild\fR? +Insert a node named \fIchild\fR 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 \fInode\fR\fIx\fR. +.TP +\fIgraphName\fR \fBnode lappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fInode\fR. If no \fIkey\fR is specified, the key +\fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBnode opposite\fR \fInode\fR \fIarc\fR +Return the node at the other end of the specified \fIarc\fR, which has +to be adjacent to the given \fInode\fR. +.TP +\fIgraphName\fR \fBnode set\fR \fInode\fR ?-key \fIkey\fR? ?\fIvalue\fR? +Set or get one of the keyed values associated with a node. If no key +is specified, the key \fBdata\fR is assumed. Each node that is +added to a graph has the empty string assigned to the key +\fBdata\fR automatically. A node may have any number of keyed +values associated with it. If \fIvalue\fR is not specified, this +command returns the current value assigned to the key; if \fIvalue\fR +is specified, this command assigns that value to the key. +.TP +\fIgraphName\fR \fBnode unset\fR \fInode\fR ?-key \fIkey\fR? +Remove a keyed value from the node \fInode\fR. If no key is +specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBnodes\fR ?-key \fIkey\fR? ?-value \fIvalue\fR? ?-in|-out|-adj|-inner|-embedding \fInodelist\fR? +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. +.sp +The possible restrictions are the same as for method +\fBarcs\fR. 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 \fBarcs\fR. +.TP +\fIgraphName\fR \fBget\fR ?-key \fIkey\fR? +Return the value associated with the key \fIkey\fR for the graph. If +no key is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBgetall\fR +Returns a serialized list of key/value pairs (suitable for use with +[\fBarray set\fR]) for the whole graph. +.TP +\fIgraphName\fR \fBkeys\fR +Returns a list of keys for the whole graph. +.TP +\fIgraphName\fR \fBkeyexists\fR ?-key \fIkey\fR? +Return true if the specified \fIkey\fR exists for the whole graph. If no +\fIkey\fR is specified, the key \fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBset\fR ?-key \fIkey\fR? ?\fIvalue\fR? +Set or get one of the keyed values associated with a graph. If no key +is specified, the key \fBdata\fR is assumed. Each graph has the +empty string assigned to the key \fBdata\fR automatically. A graph +may have any number of keyed values associated with it. If \fIvalue\fR +is not specified, this command returns the current value assigned to +the key; if \fIvalue\fR is specified, this command assigns that value +to the key. +.TP +\fIgraphName\fR \fBswap\fR \fInode1\fR \fInode2\fR +Swap the position of \fInode1\fR and \fInode2\fR in the graph. +.TP +\fIgraphName\fR \fBunset\fR ?-key \fIkey\fR? +Remove a keyed value from the graph. If no key is specified, the key +\fBdata\fR is assumed. +.TP +\fIgraphName\fR \fBwalk\fR \fInode\fR ?-order \fIorder\fR? ?-type \fItype\fR? ?-dir \fIdirection\fR? -command \fIcmd\fR +Perform a breadth-first or depth-first walk of the graph starting at +the node \fInode\fR going in either the direction of outgoing or +opposite to the incoming arcs. +.sp +The type of walk, breadth-first or depth-first, is determined by the +value of \fItype\fR; \fBbfs\fR indicates breadth-first, +\fBdfs\fR indicates depth-first. Depth-first is the default. +.sp +The order of the walk, pre-order, post-order or both-order is +determined by the value of \fIorder\fR; \fBpre\fR indicates +pre-order, \fBpost\fR indicates post-order, \fBboth\fR 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 +\fIdirection\fR, 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 \fIand\fR after any of its neighbors. The +combination of a bread-first walk with post- or both-order is illegal. +.sp +The direction of the walk is determined by the value of \fIdir\fR; +\fBbackward\fR indicates the direction opposite to the incoming +arcs, \fBforward\fR indicates the direction of the outgoing arcs. +.sp +As the walk progresses, the command \fIcmd\fR will be evaluated at +each node, with the mode of the call (\fBenter\fR or +\fBleave\fR) and values \fIgraphName\fR and the name of the current +node appended. For a pre-order walk, all nodes are \fBenter\fRed, for a +post-order all nodes are left. In a both-order walk the first visit of +a node \fBenter\fRs it, the second visit \fBleave\fRs it. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: graph\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +cgraph, graph +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/graphops.n Index: embedded/man/files/modules/struct/graphops.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/graphops.n @@ -0,0 +1,1477 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/graphops.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Alejandro Paz <vidriloco@gmail.com> +'\" Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" Copyright (c) 2009 Michal Antoniewski <antoniewski.m@gmail.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::graph::op" n 0.11.3 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::graph::op \- Operation for (un)directed graph objects +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::graph::op ?0.11.3?\fR +.sp +\fBstruct::graph::op::toAdjacencyMatrix\fR \fIg\fR +.sp +\fBstruct::graph::op::toAdjacencyList\fR \fIG\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::kruskal\fR \fIg\fR +.sp +\fBstruct::graph::op::prim\fR \fIg\fR +.sp +\fBstruct::graph::op::isBipartite?\fR \fIg\fR ?\fIbipartvar\fR? +.sp +\fBstruct::graph::op::tarjan\fR \fIg\fR +.sp +\fBstruct::graph::op::connectedComponents\fR \fIg\fR +.sp +\fBstruct::graph::op::connectedComponentOf\fR \fIg\fR \fIn\fR +.sp +\fBstruct::graph::op::isConnected?\fR \fIg\fR +.sp +\fBstruct::graph::op::isCutVertex?\fR \fIg\fR \fIn\fR +.sp +\fBstruct::graph::op::isBridge?\fR \fIg\fR \fIa\fR +.sp +\fBstruct::graph::op::isEulerian?\fR \fIg\fR ?\fItourvar\fR? +.sp +\fBstruct::graph::op::isSemiEulerian?\fR \fIg\fR ?\fIpathvar\fR? +.sp +\fBstruct::graph::op::dijkstra\fR \fIg\fR \fIstart\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::distance\fR \fIg\fR \fIorigin\fR \fIdestination\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::eccentricity\fR \fIg\fR \fIn\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::radius\fR \fIg\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::diameter\fR \fIg\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::BellmanFord\fR \fIG\fR \fIstartnode\fR +.sp +\fBstruct::graph::op::Johnsons\fR \fIG\fR ?\fIoptions\fR...? +.sp +\fBstruct::graph::op::FloydWarshall\fR \fIG\fR +.sp +\fBstruct::graph::op::MetricTravellingSalesman\fR \fIG\fR +.sp +\fBstruct::graph::op::Christofides\fR \fIG\fR +.sp +\fBstruct::graph::op::GreedyMaxMatching\fR \fIG\fR +.sp +\fBstruct::graph::op::MaxCut\fR \fIG\fR \fIU\fR \fIV\fR +.sp +\fBstruct::graph::op::UnweightedKCenter\fR \fIG\fR \fIk\fR +.sp +\fBstruct::graph::op::WeightedKCenter\fR \fIG\fR \fInodeWeights\fR \fIW\fR +.sp +\fBstruct::graph::op::GreedyMaxIndependentSet\fR \fIG\fR +.sp +\fBstruct::graph::op::GreedyWeightedMaxIndependentSet\fR \fIG\fR \fInodeWeights\fR +.sp +\fBstruct::graph::op::VerticesCover\fR \fIG\fR +.sp +\fBstruct::graph::op::EdmondsKarp\fR \fIG\fR \fIs\fR \fIt\fR +.sp +\fBstruct::graph::op::BusackerGowen\fR \fIG\fR \fIdesiredFlow\fR \fIs\fR \fIt\fR +.sp +\fBstruct::graph::op::ShortestsPathsByBFS\fR \fIG\fR \fIs\fR \fIoutputFormat\fR +.sp +\fBstruct::graph::op::BFS\fR \fIG\fR \fIs\fR ?\fIoutputFormat\fR...? +.sp +\fBstruct::graph::op::MinimumDiameterSpanningTree\fR \fIG\fR +.sp +\fBstruct::graph::op::MinimumDegreeSpanningTree\fR \fIG\fR +.sp +\fBstruct::graph::op::MaximumFlowByDinic\fR \fIG\fR \fIs\fR \fIt\fR \fIblockingFlowAlg\fR +.sp +\fBstruct::graph::op::BlockingFlowByDinic\fR \fIG\fR \fIs\fR \fIt\fR +.sp +\fBstruct::graph::op::BlockingFlowByMKM\fR \fIG\fR \fIs\fR \fIt\fR +.sp +\fBstruct::graph::op::createResidualGraph\fR \fIG\fR \fIf\fR +.sp +\fBstruct::graph::op::createAugmentingNetwork\fR \fIG\fR \fIf\fR \fIpath\fR +.sp +\fBstruct::graph::op::createLevelGraph\fR \fIGf\fR \fIs\fR +.sp +\fBstruct::graph::op::TSPLocalSearching\fR \fIG\fR \fIC\fR +.sp +\fBstruct::graph::op::TSPLocalSearching3Approx\fR \fIG\fR \fIC\fR +.sp +\fBstruct::graph::op::createSquaredGraph\fR \fIG\fR +.sp +\fBstruct::graph::op::createCompleteGraph\fR \fIG\fR \fIoriginalEdges\fR +.sp +.BE +.SH DESCRIPTION +.PP +The package described by this document, \fBstruct::graph::op\fR, +is a companion to the package \fBstruct::graph\fR. It provides a +series of common operations and algorithms applicable to (un)directed +graphs. +.PP +Despite being a companion the package is not directly dependent on +\fBstruct::graph\fR, 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 \fBstruct::graph\fR. +.SH OPERATIONS +.TP +\fBstruct::graph::op::toAdjacencyMatrix\fR \fIg\fR +This command takes the graph \fIg\fR and returns a nested list +containing the adjacency matrix of \fIg\fR. +.sp +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 "\fBn\fR+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, \fBTrue\fR if there is an arc between the 2 nodes +of the respective row and column, and \fBFalse\fR otherwise. +.sp +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 \fIg\fR. +.TP +\fBstruct::graph::op::toAdjacencyList\fR \fIG\fR ?\fIoptions\fR...? +Procedure creates for input graph \fIG\fR, it's representation as \fIAdjacency List\fR. +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. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph object \fIG\fR (input) +A graph to convert into an \fIAdjacency List\fR. +.RE +.TP +Options: +.RS +.TP +\fB-directed\fR +By default \fIG\fR is operated as if it were an \fIUndirected graph\fR. +Using this option tells the command to handle \fIG\fR as the directed graph it is. +.TP +\fB-weights\fR +By default any weight information the graph \fIG\fR 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. +.RE +.RE +.TP +\fBstruct::graph::op::kruskal\fR \fIg\fR +This command takes the graph \fIg\fR and returns a list containing the +names of the arcs in \fIg\fR 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 \fIO(E*log E)\fR or \fIO(E* log V)\fR, +where \fIV\fR is the number of vertices and \fIE\fR is the number of edges +in graph \fIg\fR. +.sp +The command will throw an error if one or more arcs in \fIg\fR have no +weight associated with them. +.sp +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. +.TP +\fBstruct::graph::op::prim\fR \fIg\fR +This command takes the graph \fIg\fR and returns a list containing the +names of the arcs in \fIg\fR 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 \fIO(E+V*log V)\fR and \fIO(V*V)\fR, +depending on the implementation (Fibonacci heap + Adjacency list versus +Adjacency Matrix). As usual \fIV\fR is the number of vertices and +\fIE\fR the number of edges in graph \fIg\fR. +.sp +The command will throw an error if one or more arcs in \fIg\fR have no +weight associated with them. +.sp +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. +.TP +\fBstruct::graph::op::isBipartite?\fR \fIg\fR ?\fIbipartvar\fR? +This command takes the graph \fIg\fR and returns a boolean value +indicating whether it is bipartite (\fBtrue\fR) or not +(\fBfalse\fR). If the variable \fIbipartvar\fR 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. +.TP +\fBstruct::graph::op::tarjan\fR \fIg\fR +This command computes the set of \fIstrongly connected\fR +components (SCCs) of the graph \fIg\fR. The result of the command is a +list of sets, each of which contains the nodes for one of the SCCs of +\fIg\fR. The union of all SCCs covers the whole graph, and no two SCCs +intersect with each other. +.sp +The graph \fIg\fR is \fIacyclic\fR if all SCCs in the result contain +only a single node. The graph \fIg\fR is \fIstrongly connected\fR +if the result contains only a single SCC containing all nodes of +\fIg\fR. +.TP +\fBstruct::graph::op::connectedComponents\fR \fIg\fR +This command computes the set of \fIconnected\fR components (CCs) of +the graph \fIg\fR. The result of the command is a list of sets, each +of which contains the nodes for one of the CCs of \fIg\fR. The union +of all CCs covers the whole graph, and no two CCs intersect with each +other. +.sp +The graph \fIg\fR is \fIconnected\fR if the result contains only a +single SCC containing all nodes of \fIg\fR. +.TP +\fBstruct::graph::op::connectedComponentOf\fR \fIg\fR \fIn\fR +This command computes the \fIconnected\fR component (CC) of the graph +\fIg\fR containing the node \fIn\fR. The result of the command is a +sets which contains the nodes for the CC of \fIn\fR in \fIg\fR. +.sp +The command will throw an error if \fIn\fR is not a node of the graph +\fIg\fR. +.TP +\fBstruct::graph::op::isConnected?\fR \fIg\fR +This is a convenience command determining whether the graph \fIg\fR is +\fIconnected\fR or not. The result is a boolean value, \fBtrue\fR +if the graph is connected, and \fBfalse\fR otherwise. +.TP +\fBstruct::graph::op::isCutVertex?\fR \fIg\fR \fIn\fR +This command determines whether the node \fIn\fR in the graph \fIg\fR +is a \fIcut vertex\fR (aka \fIarticulation point\fR). The result +is a boolean value, \fBtrue\fR if the node is a cut vertex, and +\fBfalse\fR otherwise. +.sp +The command will throw an error if \fIn\fR is not a node of the graph +\fIg\fR. +.TP +\fBstruct::graph::op::isBridge?\fR \fIg\fR \fIa\fR +This command determines whether the arc \fIa\fR in the graph \fIg\fR +is a \fIbridge\fR (aka \fIcut edge\fR, or \fIisthmus\fR). The +result is a boolean value, \fBtrue\fR if the arc is a bridge, and +\fBfalse\fR otherwise. +.sp +The command will throw an error if \fIa\fR is not an arc of the graph +\fIg\fR. +.TP +\fBstruct::graph::op::isEulerian?\fR \fIg\fR ?\fItourvar\fR? +This command determines whether the graph \fIg\fR is \fIeulerian\fR +or not. The result is a boolean value, \fBtrue\fR if the graph is +eulerian, and \fBfalse\fR otherwise. +.sp +If the graph is eulerian and \fItourvar\fR 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. +.TP +\fBstruct::graph::op::isSemiEulerian?\fR \fIg\fR ?\fIpathvar\fR? +This command determines whether the graph \fIg\fR is +\fIsemi-eulerian\fR or not. The result is a boolean value, \fBtrue\fR +if the graph is semi-eulerian, and \fBfalse\fR otherwise. +.sp +If the graph is semi-eulerian and \fIpathvar\fR 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. +.TP +\fBstruct::graph::op::dijkstra\fR \fIg\fR \fIstart\fR ?\fIoptions\fR...? +This command determines distances in the weighted \fIg\fR from the +node \fIstart\fR to all other nodes in the graph. The options specify +how to traverse graphs, and the format of the result. +.sp +Two options are recognized +.RS +.TP +\fB-arcmode\fR mode +The accepted mode values are \fBdirected\fR and \fBundirected\fR. +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. +.TP +\fB-outputformat\fR format +The accepted format values are \fBdistances\fR and \fBtree\fR. In +both cases the result is a dictionary keyed by the names of all nodes +in the graph. For \fBdistances\fR the value is the distance of the +node to \fIstart\fR, whereas for \fBtree\fR the value is the path +from the node to \fIstart\fR, excluding the node itself, but including +\fIstart\fR. Tree format is the default. +.RE +.TP +\fBstruct::graph::op::distance\fR \fIg\fR \fIorigin\fR \fIdestination\fR ?\fIoptions\fR...? +This command determines the (un)directed distance between the two +nodes \fIorigin\fR and \fIdestination\fR in the graph \fIg\fR. It +accepts the option \fB-arcmode\fR of \fBstruct::graph::op::dijkstra\fR. +.TP +\fBstruct::graph::op::eccentricity\fR \fIg\fR \fIn\fR ?\fIoptions\fR...? +This command determines the (un)directed \fIeccentricity\fR of the +node \fIn\fR in the graph \fIg\fR. It accepts the option +\fB-arcmode\fR of \fBstruct::graph::op::dijkstra\fR. +.sp +The (un)directed \fIeccentricity\fR of a node is the maximal +(un)directed distance between the node and any other node in the +graph. +.TP +\fBstruct::graph::op::radius\fR \fIg\fR ?\fIoptions\fR...? +This command determines the (un)directed \fIradius\fR of the graph +\fIg\fR. It accepts the option \fB-arcmode\fR of \fBstruct::graph::op::dijkstra\fR. +.sp +The (un)directed \fIradius\fR of a graph is the minimal (un)directed +\fIeccentricity\fR of all nodes in the graph. +.TP +\fBstruct::graph::op::diameter\fR \fIg\fR ?\fIoptions\fR...? +This command determines the (un)directed \fIdiameter\fR of the graph +\fIg\fR. It accepts the option \fB-arcmode\fR of \fBstruct::graph::op::dijkstra\fR. +.sp +The (un)directed \fIdiameter\fR of a graph is the maximal (un)directed +\fIeccentricity\fR of all nodes in the graph. +.TP +\fBstruct::graph::op::BellmanFord\fR \fIG\fR \fIstartnode\fR +Searching for \fBshortests paths\fR between chosen node and all other nodes in graph \fIG\fR. Based +on relaxation method. In comparison to \fBstruct::graph::op::dijkstra\fR it doesn't need assumption that all weights +on edges in input graph \fIG\fR have to be positive. +.sp +That generality sets the complexity of algorithm to - \fIO(V*E)\fR, where \fIV\fR is the number of vertices +and \fIE\fR is number of edges in graph \fIG\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph object \fIG\fR (input) +Directed, connected and edge weighted graph \fIG\fR, 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. +.TP +Node \fIstartnode\fR (input) +The node for which we find all shortest paths to each other node in graph \fIG\fR. +.RE +.TP +Result: +Dictionary containing for each node (key) distances to each other node in graph \fIG\fR. +.RE +.sp +\fINote:\fR If algorithm finds a negative cycle, it will return error message. +.TP +\fBstruct::graph::op::Johnsons\fR \fIG\fR ?\fIoptions\fR...? +Searching for \fBshortest paths\fR between all pairs of vertices in graph. For sparse graphs +asymptotically quicker than \fBstruct::graph::op::FloydWarshall\fR algorithm. Johnson's algorithm +uses \fBstruct::graph::op::BellmanFord\fR and \fBstruct::graph::op::dijkstra\fR as subprocedures. +.sp +Time complexity: \fIO(n**2*log(n) +n*m)\fR, where \fIn\fR is the number of nodes and \fIm\fR is +the number of edges in graph \fIG\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph object \fIG\fR (input) +Directed graph \fIG\fR, 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. +.RE +.TP +Options: +.RS +.TP +\fB-filter\fR +Returns only existing distances, cuts all \fIInf\fR values for +non-existing connections between pairs of nodes. +.RE +.TP +Result: +Dictionary containing distances between all pairs of vertices. +.RE +.TP +\fBstruct::graph::op::FloydWarshall\fR \fIG\fR +Searching for \fBshortest paths\fR between all pairs of edges in weighted graphs. +.sp +Time complexity: \fIO(V^3)\fR - where \fIV\fR is number of vertices. +.sp +Memory complexity: \fIO(V^2)\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph object \fIG\fR (input) +Directed and weighted graph \fIG\fR. +.RE +.TP +Result: +Dictionary containing shortest distances to each node from each node. +.RE +.IP +\fINote:\fR 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). +.sp +On the other hand algorithm can be used to find those cycles - if any shortest distance +found by algorithm for any nodes \fIv\fR and \fIu\fR (when \fIv\fR is the same node as \fIu\fR) is negative, +that node surely belong to at least one negative cycle. +.TP +\fBstruct::graph::op::MetricTravellingSalesman\fR \fIG\fR +Algorithm for solving a metric variation of \fBTravelling salesman problem\fR. +\fITSP problem\fR is \fINP-Complete\fR, so there is no efficient algorithm to solve it. Greedy methods +are getting extremely slow, with the increase in the set of nodes. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph object \fIG\fR (input) +Undirected, weighted graph \fIG\fR. +.RE +.TP +Result: +Approximated solution of minimum \fIHamilton Cycle\fR - closed path visiting all nodes, +each exactly one time. +.RE +.IP +\fINote:\fR \fBIt's 2-approximation algorithm.\fR +.TP +\fBstruct::graph::op::Christofides\fR \fIG\fR +Another algorithm for solving \fBmetric \fITSP problem\fR\fR. +Christofides implementation uses \fIMax Matching\fR for reaching better approximation factor. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected, weighted graph \fIG\fR. +.RE +.TP +Result: +Approximated solution of minimum \fIHamilton Cycle\fR - closed path visiting all nodes, +each exactly one time. +.RE +.sp +\fINote:\fR \fBIt's is a 3/2 approximation algorithm. \fR +.TP +\fBstruct::graph::op::GreedyMaxMatching\fR \fIG\fR +\fIGreedy Max Matching\fR procedure, which finds \fBmaximal matching\fR (not maximum) +for given graph \fIG\fR. It adds edges to solution, beginning from edges with the +lowest cost. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected graph \fIG\fR. +.RE +.TP +Result: +Set of edges - the max matching for graph \fIG\fR. +.RE +.TP +\fBstruct::graph::op::MaxCut\fR \fIG\fR \fIU\fR \fIV\fR +Algorithm solving a \fBMaximum Cut Problem\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +The graph to cut. +.TP +List \fIU\fR (output) +Variable storing first set of nodes (cut) given by solution. +.TP +List \fIV\fR (output) +Variable storing second set of nodes (cut) given by solution. +.RE +.TP +Result: +Algorithm returns number of edges between found two sets of nodes. +.RE +.IP +\fINote:\fR \fIMaxCut\fR is a \fB2-approximation algorithm.\fR +.TP +\fBstruct::graph::op::UnweightedKCenter\fR \fIG\fR \fIk\fR +Approximation algorithm that solves a \fBk-center problem\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected complete graph \fIG\fR, which satisfies triangle inequality. +.sp +.TP +Integer \fIk\fR (input) +Positive integer that sets the number of nodes that will be included in \fIk-center\fR. +.RE +.TP +Result: +Set of nodes - \fIk\fR center for graph \fIG\fR. +.RE +.IP +\fINote:\fR \fIUnweightedKCenter\fR is a \fB2-approximation algorithm.\fR +.TP +\fBstruct::graph::op::WeightedKCenter\fR \fIG\fR \fInodeWeights\fR \fIW\fR +Approximation algorithm that solves a weighted version of \fBk-center problem\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected complete graph \fIG\fR, which satisfies triangle inequality. +.TP +Integer \fIW\fR (input) +Positive integer that sets the maximum possible weight of \fIk-center\fR found by algorithm. +.TP +List \fInodeWeights\fR (input) +List of nodes and its weights in graph \fIG\fR. +.RE +.TP +Result: +Set of nodes, which is solution found by algorithm. +.RE +.IP +\fINote:\fR\fIWeightedKCenter\fR is a \fB3-approximation algorithm.\fR +.TP +\fBstruct::graph::op::GreedyMaxIndependentSet\fR \fIG\fR +A \fImaximal independent set\fR is an \fIindependent set\fR such that adding any other node +to the set forces the set to contain an edge. +.sp +Algorithm for input graph \fIG\fR returns set of nodes (list), which are contained in Max Independent +Set found by algorithm. +.TP +\fBstruct::graph::op::GreedyWeightedMaxIndependentSet\fR \fIG\fR \fInodeWeights\fR +Weighted variation of \fIMaximal Independent Set\fR. It takes as an input argument +not only graph \fIG\fR but also set of weights for all vertices in graph \fIG\fR. +.sp +\fINote:\fR +Read also \fIMaximal Independent Set\fR description for more info. +.TP +\fBstruct::graph::op::VerticesCover\fR \fIG\fR +\fIVertices cover\fR 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 +\fIvertices cover\fR, which is a classical optimization problem in computer science and +is a typical example of an \fINP-hard\fR optimization problem that has an approximation +algorithm. +For input graph \fIG\fR algorithm returns the set of edges (list), which is Vertex Cover found by algorithm. +.TP +\fBstruct::graph::op::EdmondsKarp\fR \fIG\fR \fIs\fR \fIt\fR +Improved Ford-Fulkerson's algorithm, computing the \fBmaximum flow\fR in given flow network \fIG\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Weighted and directed graph. Each edge should have set integer attribute considered as +maximum throughputs that can be carried by that link (edge). +.TP +Node \fIs\fR (input) +The node that is a source for graph \fIG\fR. +.TP +Node \fIt\fR (input) +The node that is a sink for graph \fIG\fR. +.RE +.TP +Result: +Procedure returns the dictionary containing throughputs for all edges. For +each key ( the edge between nodes \fIu\fR and \fIv\fR in the form of \fIlist u v\fR ) 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). +.RE +.sp +The general idea of algorithm is finding the shortest augumenting paths in graph \fIG\fR, 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. +.sp +\fINote:\fR Algorithm complexity : \fIO(V*E)\fR, where \fIV\fR is the number of nodes and \fIE\fR is the number +of edges in graph \fIG\fR. +.TP +\fBstruct::graph::op::BusackerGowen\fR \fIG\fR \fIdesiredFlow\fR \fIs\fR \fIt\fR +Algorithm finds solution for a \fBminimum cost flow problem\fR. So, the goal is to find a flow, +whose max value can be \fIdesiredFlow\fR, from source node \fIs\fR to sink node \fIt\fR in given flow network \fIG\fR. +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 ). +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Flow network (directed graph), each edge in graph should have two integer attributes: \fIcost\fR and \fIthroughput\fR. +.TP +Integer \fIdesiredFlow\fR (input) +Max value of the flow for that network. +.TP +Node \fIs\fR (input) +The source node for graph \fIG\fR. +.TP +Node \fIt\fR (input) +The sink node for graph \fIG\fR. +.RE +.TP +Result: +Dictionary containing values of used throughputs for each edge ( key ). +found by algorithm. +.RE +.IP +\fINote:\fR Algorithm complexity : \fIO(V**2*desiredFlow)\fR, where \fIV\fR is the number of nodes in graph \fIG\fR. +.TP +\fBstruct::graph::op::ShortestsPathsByBFS\fR \fIG\fR \fIs\fR \fIoutputFormat\fR +Shortest pathfinding algorithm using BFS method. In comparison to \fBstruct::graph::op::dijkstra\fR 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. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Input graph. +.TP +Node \fIs\fR (input) +Source node for which all distances to each other node in graph \fIG\fR are computed. +.RE +.TP +Options and result: +.RS +.TP +\fBdistances\fR +When selected \fIoutputFormat\fR is \fBdistances\fR - procedure returns dictionary containing +distances between source node \fIs\fR and each other node in graph \fIG\fR. +.TP +\fBpaths\fR +When selected \fIoutputFormat\fR is \fBpaths\fR - procedure returns dictionary containing +for each node \fIv\fR, a list of nodes, which is a path between source node \fIs\fR and node \fIv\fR. +.RE +.RE +.TP +\fBstruct::graph::op::BFS\fR \fIG\fR \fIs\fR ?\fIoutputFormat\fR...? +Breadth-First Search - algorithm creates the BFS Tree. +Memory and time complexity: \fIO(V + E)\fR, where \fIV\fR is the number of nodes and \fIE\fR +is number of edges. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Input graph. +.TP +Node \fIs\fR (input) +Source node for BFS procedure. +.RE +.TP +Options and result: +.RS +.TP +\fBgraph\fR +When selected \fBoutputFormat\fR is \fBgraph\fR - procedure returns a graph structure (\fBstruct::graph\fR), +which is equivalent to BFS tree found by algorithm. +.TP +\fBtree\fR +When selected \fBoutputFormat\fR is \fBtree\fR - procedure returns a tree structure (\fBstruct::tree\fR), +which is equivalent to BFS tree found by algorithm. +.RE +.RE +.TP +\fBstruct::graph::op::MinimumDiameterSpanningTree\fR \fIG\fR +The goal is to find for input graph \fIG\fR, the \fIspanning tree\fR that +has the minimum \fIdiameter\fR value. +.sp +General idea of algorithm is to run \fIBFS\fR over all vertices in graph +\fIG\fR. If the diameter \fId\fR of the tree is odd, then we are sure that tree +given by \fIBFS\fR is minimum (considering diameter value). When, diameter \fId\fR +is even, then optimal tree can have minimum \fIdiameter\fR equal to \fId\fR or +\fId-1\fR. +.sp +In that case, what algorithm does is rebuilding the tree given by \fIBFS\fR, 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 \fIBFS\fR +with new node as root node. If the height of the tree didn't changed, we have found +a better solution. +.sp +For input graph \fIG\fR algorithm returns the graph structure (\fBstruct::graph\fR) that is +a spanning tree with minimum diameter found by algorithm. +.TP +\fBstruct::graph::op::MinimumDegreeSpanningTree\fR \fIG\fR +Algorithm finds for input graph \fIG\fR, a spanning tree \fIT\fR with the minimum possible +degree. That problem is \fINP-hard\fR, so algorithm is an approximation algorithm. +.sp +Let \fIV\fR be the set of nodes for graph \fIG\fR and let \fIW\fR be any subset of \fIV\fR. Lets +assume also that \fIOPT\fR is optimal solution and \fIALG\fR is solution found by algorithm for input +graph \fIG\fR. +.sp +It can be proven that solution found with the algorithm must fulfil inequality: +.sp +\fI((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected simple graph. +.RE +.TP +Result: +Algorithm returns graph structure, which is equivalent to spanning tree \fIT\fR found by algorithm. +.RE +.TP +\fBstruct::graph::op::MaximumFlowByDinic\fR \fIG\fR \fIs\fR \fIt\fR \fIblockingFlowAlg\fR +Algorithm finds \fBmaximum flow\fR for the flow network represented by graph \fIG\fR. It is based on +the blocking-flow finding methods, which give us different complexities what makes a better fit for +different graphs. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Directed graph \fIG\fR representing the flow network. Each edge should have attribute +\fIthroughput\fR set with integer value. +.TP +Node \fIs\fR (input) +The source node for the flow network \fIG\fR. +.TP +Node \fIt\fR (input) +The sink node for the flow network \fIG\fR. +.RE +.TP +Options: +.RS +.TP +\fBdinic\fR +Procedure will find maximum flow for flow network \fIG\fR using Dinic's algorithm (\fBstruct::graph::op::BlockingFlowByDinic\fR) +for blocking flow computation. +.TP +\fBmkm\fR +Procedure will find maximum flow for flow network \fIG\fR using Malhotra, Kumar and Maheshwari's algorithm (\fBstruct::graph::op::BlockingFlowByMKM\fR) +for blocking flow computation. +.RE +.TP +Result: +Algorithm returns dictionary containing it's flow value for each edge (key) in network \fIG\fR. +.RE +.sp +\fINote:\fR \fBstruct::graph::op::BlockingFlowByDinic\fR gives \fIO(m*n^2)\fR complexity and +\fBstruct::graph::op::BlockingFlowByMKM\fR gives \fIO(n^3)\fR complexity, where \fIn\fR is the number of nodes +and \fIm\fR is the number of edges in flow network \fIG\fR. +.TP +\fBstruct::graph::op::BlockingFlowByDinic\fR \fIG\fR \fIs\fR \fIt\fR +Algorithm for given network \fIG\fR with source \fIs\fR and sink \fIt\fR, finds a \fBblocking +flow\fR, which can be used to obtain a \fImaximum flow\fR for that network \fIG\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Directed graph \fIG\fR representing the flow network. Each edge should have attribute +\fIthroughput\fR set with integer value. +.TP +Node \fIs\fR (input) +The source node for the flow network \fIG\fR. +.TP +Node \fIt\fR (input) +The sink node for the flow network \fIG\fR. +.RE +.TP +Result: +Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network \fIG\fR. +.RE +.IP +\fINote:\fR Algorithm's complexity is \fIO(n*m)\fR, where \fIn\fR is the number of nodes +and \fIm\fR is the number of edges in flow network \fIG\fR. +.TP +\fBstruct::graph::op::BlockingFlowByMKM\fR \fIG\fR \fIs\fR \fIt\fR +Algorithm for given network \fIG\fR with source \fIs\fR and sink \fIt\fR, finds a \fBblocking +flow\fR, which can be used to obtain a \fImaximum flow\fR for that \fInetwork\fR \fIG\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Directed graph \fIG\fR representing the flow network. Each edge should have attribute +\fIthroughput\fR set with integer value. +.TP +Node \fIs\fR (input) +The source node for the flow network \fIG\fR. +.TP +Node \fIt\fR (input) +The sink node for the flow network \fIG\fR. +.RE +.TP +Result: +Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network \fIG\fR. +.RE +.IP +\fINote:\fR Algorithm's complexity is \fIO(n^2)\fR, where \fIn\fR is the number of nodes in flow network \fIG\fR. +.TP +\fBstruct::graph::op::createResidualGraph\fR \fIG\fR \fIf\fR +Procedure creates a \fIresidual graph\fR (or \fBresidual network\fR ) for network \fIG\fR and given +flow \fIf\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Flow network (directed graph where each edge has set attribute: \fIthroughput\fR ). +.TP +dictionary \fIf\fR (input) +Current flows in flow network \fIG\fR. +.RE +.TP +Result: +Procedure returns graph structure that is a \fIresidual graph\fR created from input flow +network \fIG\fR. +.RE +.TP +\fBstruct::graph::op::createAugmentingNetwork\fR \fIG\fR \fIf\fR \fIpath\fR +Procedure creates an \fBaugmenting network\fR for a given residual network \fIG\fR +, flow \fIf\fR and augmenting path \fIpath\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Residual network (directed graph), where for every edge there are set two attributes: throughput and cost. +.TP +Dictionary \fIf\fR (input) +Dictionary which contains for every edge (key), current value of the flow on that edge. +.TP +List \fIpath\fR (input) +Augmenting path, set of edges (list) for which we create the network modification. +.RE +.TP +Result: +Algorithm returns graph structure containing the modified augmenting network. +.RE +.TP +\fBstruct::graph::op::createLevelGraph\fR \fIGf\fR \fIs\fR +For given residual graph \fIGf\fR procedure finds the \fBlevel graph\fR. +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIGf\fR (input) +Residual network, where each edge has it's attribute \fIthroughput\fR set with certain value. +.TP +Node \fIs\fR (input) +The source node for the residual network \fIGf\fR. +.RE +.TP +Result: +Procedure returns a \fIlevel graph\fR created from input \fIresidual network\fR. +.RE +.TP +\fBstruct::graph::op::TSPLocalSearching\fR \fIG\fR \fIC\fR +Algorithm is a \fIheuristic of local searching\fR for \fITravelling Salesman Problem\fR. For some +solution of \fITSP problem\fR, it checks if it's possible to find a better solution. As \fITSP\fR +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 2 approximation factor). +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected and complete graph with attributes "weight" set on each single edge. +.TP +List \fIC\fR (input) +A list of edges being \fIHamiltonian cycle\fR, which is solution of \fITSP Problem\fR for graph \fIG\fR. +.RE +.TP +Result: +Algorithm returns the best solution for \fITSP problem\fR, it was able to find. +.RE +.IP +\fINote:\fR The solution depends on the choosing of the beginning cycle \fIC\fR. 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. +.TP +\fBstruct::graph::op::TSPLocalSearching3Approx\fR \fIG\fR \fIC\fR +Algorithm is a \fIheuristic of local searching\fR for \fITravelling Salesman Problem\fR. For some +solution of \fITSP problem\fR, it checks if it's possible to find a better solution. As \fITSP\fR +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 3 approximation factor). +.sp +.RS +.TP +Arguments: +.RS +.TP +Graph Object \fIG\fR (input) +Undirected and complete graph with attributes "weight" set on each single edge. +.TP +List \fIC\fR (input) +A list of edges being \fIHamiltonian cycle\fR, which is solution of \fITSP Problem\fR for graph \fIG\fR. +.RE +.TP +Result: +Algorithm returns the best solution for \fITSP problem\fR, it was able to find. +.RE +.IP +\fINote:\fR 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. +.TP +\fBstruct::graph::op::createSquaredGraph\fR \fIG\fR +X-Squared graph is a graph with the same set of nodes as input graph \fIG\fR, but a different set of edges. X-Squared graph +has edge \fI(u,v)\fR, if and only if, the distance between \fIu\fR and \fIv\fR nodes is not greater than X and \fIu != v\fR. +.sp +Procedure for input graph \fIG\fR, returns its two-squared graph. +.sp +\fINote:\fR Distances used in choosing new set of edges are considering the number of edges, not the sum of weights at edges. +.TP +\fBstruct::graph::op::createCompleteGraph\fR \fIG\fR \fIoriginalEdges\fR +For input graph \fIG\fR procedure adds missing arcs to make it a \fIcomplete graph\fR. It also holds in +variable \fIoriginalEdges\fR the set of arcs that graph \fIG\fR possessed before that operation. +.PP +.SH "BACKGROUND THEORY AND TERMS" +.SS "SHORTEST PATH PROBLEM" +.TP +Definition (\fIsingle-pair shortest path problem\fR): +Formally, given a weighted graph (let \fIV\fR be the set of vertices, and \fIE\fR a set of edges), +and one vertice \fIv\fR of \fIV\fR, find a path \fIP\fR from \fIv\fR to a \fIv'\fR of V so that +the sum of weights on edges along the path is minimal among all paths connecting v to v'. +.TP +Generalizations: +.RS +.IP \(bu +\fIThe single-source shortest path problem\fR, in which we have to find shortest paths from a source vertex v to all other vertices in the graph. +.IP \(bu +\fIThe single-destination shortest path problem\fR, 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. +.IP \(bu +\fIThe all-pairs shortest path problem\fR, in which we have to find shortest paths between every pair of vertices v, v' in the graph. +.RE +.IP +\fINote:\fR +The result of \fIShortest Path problem\fR can be \fIShortest Path tree\fR, 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. +.PP +.SS "TRAVELLING SALESMAN PROBLEM" +.TP +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 (\fIHamiltonian cycle\fR). +.TP +Generalizations: +.RS +.IP \(bu +\fIMetric TSP\fR - A very natural restriction of the \fITSP\fR is to require that the distances between cities form a \fImetric\fR, i.e., +they satisfy \fIthe triangle inequality\fR. That is, for any 3 cities \fIA\fR, \fIB\fR and \fIC\fR, the distance between \fIA\fR and \fIC\fR +must be at most the distance from \fIA\fR to \fIB\fR plus the distance from \fIB\fR to \fIC\fR. Most natural instances of \fITSP\fR +satisfy this constraint. +.IP \(bu +\fIEuclidean TSP\fR - Euclidean TSP, or \fIplanar TSP\fR, is the \fITSP\fR with the distance being the ordinary \fIEuclidean distance\fR. +\fIEuclidean TSP\fR is a particular case of \fITSP\fR with \fItriangle inequality\fR, since distances in plane obey triangle inequality. However, +it seems to be easier than general \fITSP\fR with \fItriangle inequality\fR. For example, \fIthe minimum spanning tree\fR of the graph associated +with an instance of \fIEuclidean TSP\fR is a \fIEuclidean minimum spanning tree\fR, and so can be computed in expected \fIO(n log n)\fR time for +\fIn\fR points (considerably less than the number of edges). This enables the simple \fI2-approximation algorithm\fR for TSP with triangle +inequality above to operate more quickly. +.IP \(bu +\fIAsymmetric TSP\fR - In most cases, the distance between two nodes in the \fITSP\fR network is the same in both directions. +The case where the distance from \fIA\fR to \fIB\fR is not equal to the distance from \fIB\fR to \fIA\fR is called \fIasymmetric TSP\fR. +A practical application of an \fIasymmetric TSP\fR is route optimisation using street-level routing (asymmetric due to one-way streets, +slip-roads and motorways). +.RE +.PP +.SS "MATCHING PROBLEM" +.TP +Definition: +Given a graph \fIG = (V,E)\fR, a matching or \fIedge-independent set\fR \fIM\fR in \fIG\fR is a set of pairwise non-adjacent edges, +that is, no two edges share a common vertex. A vertex is \fImatched\fR if it is incident to an edge in the \fImatching M\fR. +Otherwise the vertex is \fIunmatched\fR. +.TP +Generalizations: +.RS +.IP \(bu +\fIMaximal matching\fR - a matching \fIM\fR of a graph G with the property that if any edge not in \fIM\fR is added to \fIM\fR, +it is no longer a \fImatching\fR, that is, \fIM\fR is maximal if it is not a proper subset of any other \fImatching\fR in graph G. +In other words, a \fImatching M\fR of a graph G is maximal if every edge in G has a non-empty intersection with at least one edge in \fIM\fR. +.IP \(bu +\fIMaximum matching\fR - a matching that contains the largest possible number of edges. There may be many \fImaximum matchings\fR. +The \fImatching number\fR of a graph G is the size of a \fImaximum matching\fR. Note that every \fImaximum matching\fR is \fImaximal\fR, +but not every \fImaximal matching\fR is a \fImaximum matching\fR. +.IP \(bu +\fIPerfect matching\fR - 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 \fIperfect matching\fR is \fImaximum\fR and hence \fImaximal\fR. In some literature, the term \fIcomplete matching\fR +is used. A \fIperfect matching\fR is also a \fIminimum-size edge cover\fR. Moreover, the size of a \fImaximum matching\fR is no larger than the +size of a \fIminimum edge cover\fR. +.IP \(bu +\fINear-perfect matching\fR - 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 \fImatching\fR must be \fImaximum\fR. If, for every vertex in a graph, there is a near-perfect matching that omits only that vertex, the graph +is also called \fIfactor-critical\fR. +.RE +.TP +Related terms: +.RS +.IP \(bu +\fIAlternating path\fR - given a matching \fIM\fR, an \fIalternating path\fR is a path in which the edges belong alternatively +to the matching and not to the matching. +.IP \(bu +\fIAugmenting path\fR - given a matching \fIM\fR, an \fIaugmenting path\fR is an \fIalternating path\fR that starts from +and ends on free (unmatched) vertices. +.RE +.PP +.SS "CUT PROBLEMS" +.TP +Definition: +A \fIcut\fR is a partition of the vertices of a graph into two \fIdisjoint subsets\fR. The \fIcut-set\fR of the \fIcut\fR 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 \fIcut-set\fR. +.sp +Formally: +.RS +.IP \(bu +a \fIcut\fR \fIC = (S,T)\fR is a partition of \fIV\fR of a graph \fIG = (V, E)\fR. +.IP \(bu +an \fIs-t cut\fR \fIC = (S,T)\fR of a \fIflow network\fR \fIN = (V, E)\fR is a cut of \fIN\fR such that \fIs\fR is included in \fIS\fR +and \fIt\fR is included in \fIT\fR, where \fIs\fR and \fIt\fR are the \fIsource\fR and the \fIsink\fR of \fIN\fR respectively. +.IP \(bu +The \fIcut-set\fR of a \fIcut C = (S,T)\fR is such set of edges from graph \fIG = (V, E)\fR that each edge \fI(u, v)\fR satisfies +condition that \fIu\fR is included in \fIS\fR and \fIv\fR is included in \fIT\fR. +.RE +.sp +In an \fIunweighted undirected\fR graph, the size or weight of a cut is the number of edges crossing the cut. In a \fIweighted graph\fR, +the same term is defined by the sum of the weights of the edges crossing the cut. +.sp +In a \fIflow network\fR, an \fIs-t cut\fR is a cut that requires the \fIsource\fR and the \fIsink\fR to be in different subsets, +and its \fIcut-set\fR only consists of edges going from the \fIsource's\fR side to the \fIsink's\fR side. The capacity of an \fIs-t cut\fR +is defined by the sum of capacity of each edge in the \fIcut-set\fR. +.sp +The \fIcut\fR of a graph can sometimes refer to its \fIcut-set\fR instead of the partition. +.TP +Generalizations: +.RS +.IP \(bu +\fIMinimum cut\fR - A cut is minimum if the size of the cut is not larger than the size of any other cut. +.IP \(bu +\fIMaximum cut\fR - A cut is maximum if the size of the cut is not smaller than the size of any other cut. +.IP \(bu +\fISparsest cut\fR - The \fISparsest cut problem\fR 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. +.RE +.PP +.SS "K-CENTER PROBLEM" +.TP +Definitions: +.RS +.TP +\fIUnweighted K-Center\fR +For any set \fIS\fR ( which is subset of \fIV\fR ) and node \fIv\fR, let the \fIconnect(v,S)\fR be the +cost of cheapest edge connecting \fIv\fR with any node in \fIS\fR. The goal is to find +such \fIS\fR, that \fI|S| = k\fR and \fImax_v{connect(v,S)}\fR is possibly small. +.sp +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. +.sp +.TP +\fIWeighted K-Center\fR +The variation of \fIunweighted k-center problem\fR. Besides the fact graph is edge-weighted, +there are also weights on vertices of input graph \fIG\fR. We've got also restriction +\fIW\fR. The goal is to choose such set of nodes \fIS\fR ( which is a subset of \fIV\fR ), that it's +total weight is not greater than \fIW\fR and also function: \fImax_v { min_u { cost(u,v) }}\fR +has the smallest possible worth ( \fIv\fR is a node in \fIV\fR and \fIu\fR is a node in \fIS\fR ). +.RE +.PP +.SS "FLOW PROBLEMS" +.TP +Definitions: +.RS +.IP \(bu +\fIthe maximum flow problem\fR - the goal is to find a feasible flow through a single-source, single-sink flow network that is maximum. +The \fImaximum flow problem\fR can be seen as a special case of more complex network flow problems, such as the \fIcirculation problem\fR. +The maximum value of an \fIs-t flow\fR is equal to the minimum capacity of an \fIs-t cut\fR in the network, as stated in the +\fImax-flow min-cut theorem\fR. +.sp +More formally for flow network \fIG = (V,E)\fR, where for each edge \fI(u, v)\fR we have its throuhgput \fIc(u,v)\fR defined. As \fIflow\fR +\fIF\fR we define set of non-negative integer attributes \fIf(u,v)\fR assigned to edges, satisfying such conditions: +.RS +.IP [1] +for each edge \fI(u, v)\fR in \fIG\fR such condition should be satisfied: 0 <= f(u,v) <= c(u,v) +.IP [2] +Network \fIG\fR has source node \fIs\fR such that the flow \fIF\fR is equal to the sum of outcoming flow decreased by the sum of incoming flow from that source node \fIs\fR. +.IP [3] +Network \fIG\fR has sink node \fIt\fR such that the the \fI-F\fR value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node \fIt\fR. +.IP [4] +For each node that is not a \fIsource\fR or \fIsink\fR the sum of incoming flow and sum of outcoming flow should be equal. +.RE +.IP \(bu +\fIthe minimum cost flow problem\fR - the goal is finding the cheapest possible way of sending a certain amount of flow through a \fIflow network\fR. +.IP \(bu +\fIblocking flow\fR - a \fIblocking flow\fR for a \fIresidual network\fR \fIGf\fR we name such flow \fIb\fR in \fIGf\fR that: +.RS +.IP [1] +Each path from \fIsink\fR to \fIsource\fR is the shortest path in \fIGf\fR. +.IP [2] +Each shortest path in \fIGf\fR contains an edge with fully used throughput in \fIGf+b\fR. +.RE +.IP \(bu +\fIresidual network\fR - for a flow network \fIG\fR and flow \fIf\fR \fIresidual network\fR is built with those edges, which can +send larger flow. It contains only those edges, which can send flow larger than 0. +.IP \(bu +\fIlevel network\fR - it has the same set of nodes as \fIresidual graph\fR, but has only those edges \fI(u,v)\fR from \fIGf\fR +for which such equality is satisfied: \fIdistance(s,u)+1 = distance(s,v)\fR. +.IP \(bu +\fIaugmenting network\fR - it is a modification of \fIresidual network\fR considering the new +flow values. Structure stays unchanged but values of throughputs and costs at edges +are different. +.RE +.PP +.SS "APPROXIMATION ALGORITHM" +.TP +k-approximation algorithm: +Algorithm is a k-approximation, when for \fIALG\fR (solution returned by algorithm) and +\fIOPT\fR (optimal solution), such inequality is true: +.RS +.IP \(bu +for minimalization problems: \fIALG/OPT <= k\fR +.IP \(bu +for maximalization problems: \fIOPT/ALG <= k\fR +.RE +.PP +.SH REFERENCES +.IP [1] +\fIAdjacency matrix\fR [http://en.wikipedia.org/wiki/Adjacency_matrix] +.IP [2] +\fIAdjacency list\fR [http://en.wikipedia.org/wiki/Adjacency_list] +.IP [3] +\fIKruskal's algorithm\fR [http://en.wikipedia.org/wiki/Kruskal%27s_algorithm] +.IP [4] +\fIPrim's algorithm\fR [http://en.wikipedia.org/wiki/Prim%27s_algorithm] +.IP [5] +\fIBipartite graph\fR [http://en.wikipedia.org/wiki/Bipartite_graph] +.IP [6] +\fIStrongly connected components\fR [http://en.wikipedia.org/wiki/Strongly_connected_components] +.IP [7] +\fITarjan's strongly connected components algorithm\fR [http://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm] +.IP [8] +\fICut vertex\fR [http://en.wikipedia.org/wiki/Cut_vertex] +.IP [9] +\fIBridge\fR [http://en.wikipedia.org/wiki/Bridge_(graph_theory)] +.IP [10] +\fIBellman-Ford's algorithm\fR [http://en.wikipedia.org/wiki/Bellman-Ford_algorithm] +.IP [11] +\fIJohnson's algorithm\fR [http://en.wikipedia.org/wiki/Johnson_algorithm] +.IP [12] +\fIFloyd-Warshall's algorithm\fR [http://en.wikipedia.org/wiki/Floyd-Warshall_algorithm] +.IP [13] +\fITravelling Salesman Problem\fR [http://en.wikipedia.org/wiki/Travelling_salesman_problem] +.IP [14] +\fIChristofides Algorithm\fR [http://en.wikipedia.org/wiki/Christofides_algorithm] +.IP [15] +\fIMax Cut\fR [http://en.wikipedia.org/wiki/Maxcut] +.IP [16] +\fIMatching\fR [http://en.wikipedia.org/wiki/Matching] +.IP [17] +\fIMax Independent Set\fR [http://en.wikipedia.org/wiki/Maximal_independent_set] +.IP [18] +\fIVertex Cover\fR [http://en.wikipedia.org/wiki/Vertex_cover_problem] +.IP [19] +\fIFord-Fulkerson's algorithm\fR [http://en.wikipedia.org/wiki/Ford-Fulkerson_algorithm] +.IP [20] +\fIMaximum Flow problem\fR [http://en.wikipedia.org/wiki/Maximum_flow_problem] +.IP [21] +\fIBusacker-Gowen's algorithm\fR [http://en.wikipedia.org/wiki/Minimum_cost_flow_problem] +.IP [22] +\fIDinic's algorithm\fR [http://en.wikipedia.org/wiki/Dinic's_algorithm] +.IP [23] +\fIK-Center problem\fR [http://www.csc.kth.se/~viggo/wwwcompendium/node128.html] +.IP [24] +\fIBFS\fR [http://en.wikipedia.org/wiki/Breadth-first_search] +.IP [25] +\fIMinimum Degree Spanning Tree\fR [http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree] +.IP [26] +\fIApproximation algorithm\fR [http://en.wikipedia.org/wiki/Approximation_algorithm] +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: graph\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +adjacency list, adjacency matrix, adjacent, approximation algorithm, arc, articulation point, augmenting network, augmenting path, bfs, bipartite, blocking flow, bridge, complete graph, connected component, cut edge, cut vertex, degree, degree constrained spanning tree, diameter, dijkstra, distance, eccentricity, edge, flow network, graph, heuristic, independent set, isthmus, level graph, local searching, loop, matching, max cut, maximum flow, minimal spanning tree, minimum cost flow, minimum degree spanning tree, minimum diameter spanning tree, neighbour, node, radius, residual graph, shortest path, squared graph, strongly connected component, subgraph, travelling salesman, vertex, vertex cover +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2008 Alejandro Paz <vidriloco@gmail.com> +Copyright (c) 2008 (docs) Andreas Kupries <andreas_kupries@users.sourceforge.net> +Copyright (c) 2009 Michal Antoniewski <antoniewski.m@gmail.com> + +.fi ADDED embedded/man/files/modules/struct/matrix.n Index: embedded/man/files/modules/struct/matrix.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/matrix.n @@ -0,0 +1,812 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/matrix.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::matrix" n 2.0.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::matrix \- Create and manipulate matrix objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::matrix ?2.0.1?\fR +.sp +\fB::struct::matrix\fR ?\fImatrixName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +.sp +\fBmatrixName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fImatrixName\fR \fB=\fR \fIsourcematrix\fR +.sp +\fImatrixName\fR \fB-->\fR \fIdestmatrix\fR +.sp +\fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBadd row\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBadd columns\fR \fIn\fR +.sp +\fImatrixName\fR \fBadd rows\fR \fIn\fR +.sp +\fImatrixName\fR \fBcells\fR +.sp +\fImatrixName\fR \fBcellsize\fR \fIcolumn row\fR +.sp +\fImatrixName\fR \fBcolumns\fR +.sp +\fImatrixName\fR \fBcolumnwidth\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBdelete column\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBdelete columns\fR \fIn\fR +.sp +\fImatrixName\fR \fBdelete row\fR \fIrow\fR +.sp +\fImatrixName\fR \fBdelete rows\fR \fIn\fR +.sp +\fImatrixName\fR \fBdeserialize\fR \fIserialization\fR +.sp +\fImatrixName\fR \fBdestroy\fR +.sp +\fImatrixName\fR \fBformat 2string\fR ?\fIreport\fR? +.sp +\fImatrixName\fR \fBformat 2chan\fR ??\fIreport\fR? \fIchannel\fR? +.sp +\fImatrixName\fR \fBget cell\fR \fIcolumn row\fR +.sp +\fImatrixName\fR \fBget column\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBget rect\fR \fIcolumn_tl row_tl column_br row_br\fR +.sp +\fImatrixName\fR \fBget row\fR \fIrow\fR +.sp +\fImatrixName\fR \fBinsert column\fR \fIcolumn\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBinsert row\fR \fIrow\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBlink\fR ?-transpose? \fIarrayvar\fR +.sp +\fImatrixName\fR \fBlinks\fR +.sp +\fImatrixName\fR \fBrowheight\fR \fIrow\fR +.sp +\fImatrixName\fR \fBrows\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBall\fR \fIpattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBcolumn\fR \fIcolumn pattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrow\fR \fIrow pattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrect\fR \fIcolumn_tl row_tl column_br row_br pattern\fR +.sp +\fImatrixName\fR \fBserialize\fR ?\fIcolumn_tl row_tl column_br row_br\fR? +.sp +\fImatrixName\fR \fBset cell\fR \fIcolumn row value\fR +.sp +\fImatrixName\fR \fBset column\fR \fIcolumn values\fR +.sp +\fImatrixName\fR \fBset rect\fR \fIcolumn row values\fR +.sp +\fImatrixName\fR \fBset row\fR \fIrow values\fR +.sp +\fImatrixName\fR \fBsort columns\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIrow\fR +.sp +\fImatrixName\fR \fBsort rows\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIcolumn\fR +.sp +\fImatrixName\fR \fBswap columns\fR \fIcolumn_a column_b\fR +.sp +\fImatrixName\fR \fBswap rows\fR \fIrow_a row_b\fR +.sp +\fImatrixName\fR \fBtranspose\fR +.sp +\fImatrixName\fR \fBunlink\fR \fIarrayvar\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBend\fR refers to the last row or column in the matrix, +depending on the context. Indices of the form +\fBend\fR-\fBnumber\fR 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. +.PP +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. +.PP +The main command of the package is: +.TP +\fB::struct::matrix\fR ?\fImatrixName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +The command creates a new matrix object with an associated global Tcl +command whose name is \fImatrixName\fR. This command may be used to +invoke various operations on the matrix. It has the following general +form: +.RS +.TP +\fBmatrixName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.sp +If \fImatrixName\fR is not specified a unique name will be generated +by the package itself. If a \fIsource\fR is specified the new matrix +will be initialized to it. For the operators \fB=\fR, \fB:=\fR, +and \fBas\fR the argument \fIsource\fR is interpreted as the name of +another matrix object, and the assignment operator \fB=\fR will be +executed. For \fBdeserialize\fR the \fIsource\fR is a serialized +matrix object and \fBdeserialize\fR will be executed. +.sp +In other words +.sp +.CS + + + ::struct::matrix mymatrix = b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::matrix mymatrix + mymatrix = b + +.CE +.sp +and +.sp +.CS + + + ::struct::matrix mymatrix deserialize $b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::matrix mymatrix + mymatrix deserialize $b + +.CE +.PP +.PP +The following commands are possible for matrix objects: +.TP +\fImatrixName\fR \fB=\fR \fIsourcematrix\fR +This is the assignment operator for matrix objects. It copies the matrix +contained in the matrix object \fIsourcematrix\fR over the matrix data in +\fImatrixName\fR. The old contents of \fImatrixName\fR are deleted by +this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fImatrixName\fR \fBdeserialize\fR [\fIsourcematrix\fR \fBserialize\fR] + +.CE +.TP +\fImatrixName\fR \fB-->\fR \fIdestmatrix\fR +This is the reverse assignment operator for matrix objects. It copies +the matrix contained in the matrix object \fImatrixName\fR over the matrix +data in the object \fIdestmatrix\fR. +The old contents of \fIdestmatrix\fR are deleted by this operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdestmatrix\fR \fBdeserialize\fR [\fImatrixName\fR \fBserialize\fR] + +.CE +.TP +\fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? +Extends the matrix by one column and then acts like \fBset column\fR +(see below) on this new column if there were \fIvalues\fR +supplied. Without \fIvalues\fR the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column. +.TP +\fImatrixName\fR \fBadd row\fR ?\fIvalues\fR? +Extends the matrix by one row and then acts like \fBset row\fR (see +below) on this new row if there were \fIvalues\fR supplied. Without +\fIvalues\fR the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row. +.TP +\fImatrixName\fR \fBadd columns\fR \fIn\fR +Extends the matrix by \fIn\fR 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 \fIn\fR equal to or smaller than 0 is +not allowed. +.TP +\fImatrixName\fR \fBadd rows\fR \fIn\fR +Extends the matrix by \fIn\fR 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 \fIn\fR equal to or smaller than 0 is not +allowed. +.TP +\fImatrixName\fR \fBcells\fR +Returns the number of cells currently managed by the matrix. This is +the product of \fBrows\fR and \fBcolumns\fR. +.TP +\fImatrixName\fR \fBcellsize\fR \fIcolumn row\fR +Returns the length of the string representation of the value currently +contained in the addressed cell. +.TP +\fImatrixName\fR \fBcolumns\fR +Returns the number of columns currently managed by the matrix. +.TP +\fImatrixName\fR \fBcolumnwidth\fR \fIcolumn\fR +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. +.TP +\fImatrixName\fR \fBdelete column\fR \fIcolumn\fR +Deletes the specified column from the matrix and shifts all columns +with higher indices one index down. +.TP +\fImatrixName\fR \fBdelete columns\fR \fIn\fR +Deletes \fIn\fR columns from the right of the matrix. The value of +\fIn\fR has to satisfy the constraint +"0 < \fIn\fR < [\fBmatrixName\fR \fBcolumns\fR]" +.TP +\fImatrixName\fR \fBdelete row\fR \fIrow\fR +Deletes the specified row from the matrix and shifts all row with +higher indices one index down. +.TP +\fImatrixName\fR \fBdelete rows\fR \fIn\fR +Deletes \fIn\fR rows from the bottom of the matrix. The value of +\fIn\fR has to satisfy the constraint +"0 < \fIn\fR < [\fBmatrixName\fR \fBrows\fR]" +.TP +\fImatrixName\fR \fBdeserialize\fR \fIserialization\fR +This is the complement to \fBserialize\fR. It replaces matrix data +in \fImatrixName\fR with the matrix described by the \fIserialization\fR +value. The old contents of \fImatrixName\fR are deleted by this +operation. +.TP +\fImatrixName\fR \fBdestroy\fR +Destroys the matrix, including its storage space and associated +command. +.TP +\fImatrixName\fR \fBformat 2string\fR ?\fIreport\fR? +Formats the matrix using the specified report object and returns the +string containing the result of this operation. The report has to +support the \fBprintmatrix\fR method. If no \fIreport\fR is +specified the system will use an internal report definition to format +the matrix. +.TP +\fImatrixName\fR \fBformat 2chan\fR ??\fIreport\fR? \fIchannel\fR? +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 \fBprintmatrix2channel\fR method. If no +\fIreport\fR is specified the system will use an internal report +definition to format the matrix. If no \fIchannel\fR is specified the +system will use \fBstdout\fR. +.TP +\fImatrixName\fR \fBget cell\fR \fIcolumn row\fR +Returns the value currently contained in the cell identified by row +and column index. +.TP +\fImatrixName\fR \fBget column\fR \fIcolumn\fR +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. +.TP +\fImatrixName\fR \fBget rect\fR \fIcolumn_tl row_tl column_br row_br\fR +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 \fIcolumn_tl, row_tl\fR and +\fIcolumn_br, row_br\fR resp. Note that the following equations have +to be true: "\fIcolumn_tl\fR <= \fIcolumn_br\fR" and "\fIrow_tl\fR <= +\fIrow_br\fR". 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. +.TP +\fImatrixName\fR \fBget row\fR \fIrow\fR +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. +.TP +\fImatrixName\fR \fBinsert column\fR \fIcolumn\fR ?\fIvalues\fR? +Extends the matrix by one column and then acts like \fBset column\fR +(see below) on this new column if there were \fIvalues\fR +supplied. Without \fIvalues\fR 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 \fIcolumn\fR is less than or equal to +zero, then the new column is inserted at the beginning of the matrix, +before the first column. If \fIcolumn\fR has the value \fBend\fR, +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. +.TP +\fImatrixName\fR \fBinsert row\fR \fIrow\fR ?\fIvalues\fR? +Extends the matrix by one row and then acts like \fBset row\fR (see +below) on this new row if there were \fIvalues\fR supplied. Without +\fIvalues\fR 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 \fIrow\fR is less than or equal to zero, then the new row is +inserted at the beginning of the matrix, before the first row. If +\fIrow\fR has the value \fBend\fR, 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. +.TP +\fImatrixName\fR \fBlink\fR ?-transpose? \fIarrayvar\fR +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 \fI(column,row)\fR is stored in the array using the key +\fIcolumn,row\fR. If the option \fB-transpose\fR is specified the +key \fIrow,column\fR 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. +.TP +\fImatrixName\fR \fBlinks\fR +Returns a list containing the names of all array variables the matrix +was linked to through a call to method \fBlink\fR. +.TP +\fImatrixName\fR \fBrowheight\fR \fIrow\fR +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. +.TP +\fImatrixName\fR \fBrows\fR +Returns the number of rows currently managed by the matrix. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBall\fR \fIpattern\fR +Searches the whole matrix for cells matching the \fIpattern\fR 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. +.sp +The type of the pattern (string, glob, regular expression) is +determined by the option after the \fBsearch\fR keyword. If no +option is given it defaults to \fB-exact\fR. +.sp +If the option \fB-nocase\fR is specified the search will be +case-insensitive. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBcolumn\fR \fIcolumn pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified column. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrow\fR \fIrow pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified row. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrect\fR \fIcolumn_tl row_tl column_br row_br pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified rectangular area of the matrix. +.TP +\fImatrixName\fR \fBserialize\fR ?\fIcolumn_tl row_tl column_br row_br\fR? +This method serializes the sub-matrix spanned up by the rectangle +specification. In other words it returns a tcl \fIvalue\fR 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. +.sp +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. +.sp +The result is a list containing exactly three items. +.sp +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. +.sp +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 +\fBget rect\fR. 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. +.CS + + + # A possible serialization for the matrix structure + # + # | a b d g | + # | c e | + # | f | + # + # is + # + # 3 4 {{a b d g} {c e} {f}} + +.CE +.sp +.TP +\fImatrixName\fR \fBset cell\fR \fIcolumn row value\fR +Sets the value in the cell identified by row and column index to the +data in the third argument. +.TP +\fImatrixName\fR \fBset column\fR \fIcolumn values\fR +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. +.TP +\fImatrixName\fR \fBset rect\fR \fIcolumn row values\fR +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 \fIvalues\fR 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 \fBgetrect\fR. +.TP +\fImatrixName\fR \fBset row\fR \fIrow values\fR +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. +.TP +\fImatrixName\fR \fBsort columns\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIrow\fR +Sorts the columns in the matrix using the data in the specified +\fIrow\fR as the key to sort by. The options \fB-increasing\fR +and \fB-decreasing\fR have the same meaning as for \fBlsort\fR. +If no option is specified \fB-increasing\fR is assumed. +.TP +\fImatrixName\fR \fBsort rows\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIcolumn\fR +Sorts the rows in the matrix using the data in the specified +\fIcolumn\fR as the key to sort by. The options \fB-increasing\fR +and \fB-decreasing\fR have the same meaning as for \fBlsort\fR. +If no option is specified \fB-increasing\fR is assumed. +.TP +\fImatrixName\fR \fBswap columns\fR \fIcolumn_a column_b\fR +Swaps the contents of the two specified columns. +.TP +\fImatrixName\fR \fBswap rows\fR \fIrow_a row_b\fR +Swaps the contents of the two specified rows. +.TP +\fImatrixName\fR \fBtranspose\fR +Transposes the contents of the matrix, i.e. swaps rows for columns and +vice versa. +.TP +\fImatrixName\fR \fBunlink\fR \fIarrayvar\fR +Removes the link between the matrix and the specified arrayvariable, +if there is one. +.PP +.SH EXAMPLES +.PP +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. +.PP +.CS + + + % 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}} + +.CE +.PP +.CS + + + % 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}} + +.CE +.PP +Assuming that the style definitions in the example section of the +manpage for the package \fBreport\fR 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. +.PP +.CS + + + % ::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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: matrix\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +matrix +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/matrix1.n Index: embedded/man/files/modules/struct/matrix1.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/matrix1.n @@ -0,0 +1,652 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/matrix1.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::matrix_v1" n 1.2.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::matrix_v1 \- Create and manipulate matrix objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::matrix ?1.2.1?\fR +.sp +\fBmatrixName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBadd row\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBadd columns\fR \fIn\fR +.sp +\fImatrixName\fR \fBadd rows\fR \fIn\fR +.sp +\fImatrixName\fR \fBcells\fR +.sp +\fImatrixName\fR \fBcellsize\fR \fIcolumn row\fR +.sp +\fImatrixName\fR \fBcolumns\fR +.sp +\fImatrixName\fR \fBcolumnwidth\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBdelete column\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBdelete row\fR \fIrow\fR +.sp +\fImatrixName\fR \fBdestroy\fR +.sp +\fImatrixName\fR \fBformat 2string\fR ?\fIreport\fR? +.sp +\fImatrixName\fR \fBformat 2chan\fR ??\fIreport\fR? \fIchannel\fR? +.sp +\fImatrixName\fR \fBget cell\fR \fIcolumn row\fR +.sp +\fImatrixName\fR \fBget column\fR \fIcolumn\fR +.sp +\fImatrixName\fR \fBget rect\fR \fIcolumn_tl row_tl column_br row_br\fR +.sp +\fImatrixName\fR \fBget row\fR \fIrow\fR +.sp +\fImatrixName\fR \fBinsert column\fR \fIcolumn\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBinsert row\fR \fIrow\fR ?\fIvalues\fR? +.sp +\fImatrixName\fR \fBlink\fR ?-transpose? \fIarrayvar\fR +.sp +\fImatrixName\fR \fBlinks\fR +.sp +\fImatrixName\fR \fBrowheight\fR \fIrow\fR +.sp +\fImatrixName\fR \fBrows\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBall\fR \fIpattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBcolumn\fR \fIcolumn pattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrow\fR \fIrow pattern\fR +.sp +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrect\fR \fIcolumn_tl row_tl column_br row_br pattern\fR +.sp +\fImatrixName\fR \fBset cell\fR \fIcolumn row value\fR +.sp +\fImatrixName\fR \fBset column\fR \fIcolumn values\fR +.sp +\fImatrixName\fR \fBset rect\fR \fIcolumn row values\fR +.sp +\fImatrixName\fR \fBset row\fR \fIrow values\fR +.sp +\fImatrixName\fR \fBsort columns\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIrow\fR +.sp +\fImatrixName\fR \fBsort rows\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIcolumn\fR +.sp +\fImatrixName\fR \fBswap columns\fR \fIcolumn_a column_b\fR +.sp +\fImatrixName\fR \fBswap rows\fR \fIrow_a row_b\fR +.sp +\fImatrixName\fR \fBunlink\fR \fIarrayvar\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::matrix\fR command creates a new matrix object with an +associated global Tcl command whose name is \fImatrixName\fR. This +command may be used to invoke various operations on the matrix. It has +the following general form: +.TP +\fBmatrixName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +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 \fBend\fR refers to the last row or column in the matrix, +depending on the context. Indices of the form +\fBend\fR-\fBnumber\fR 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. +.PP +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. +.PP +The following commands are possible for matrix objects: +.TP +\fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? +Extends the matrix by one column and then acts like \fBsetcolumn\fR +(see below) on this new column if there were \fIvalues\fR +supplied. Without \fIvalues\fR the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column. +.TP +\fImatrixName\fR \fBadd row\fR ?\fIvalues\fR? +Extends the matrix by one row and then acts like \fBsetrow\fR (see +below) on this new row if there were \fIvalues\fR supplied. Without +\fIvalues\fR the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row. +.TP +\fImatrixName\fR \fBadd columns\fR \fIn\fR +Extends the matrix by \fIn\fR 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 \fIn\fR equal to or smaller than 0 is +not allowed. +.TP +\fImatrixName\fR \fBadd rows\fR \fIn\fR +Extends the matrix by \fIn\fR 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 \fIn\fR equal to or smaller than 0 is not +allowed. +.TP +\fImatrixName\fR \fBcells\fR +Returns the number of cells currently managed by the matrix. This is +the product of \fBrows\fR and \fBcolumns\fR. +.TP +\fImatrixName\fR \fBcellsize\fR \fIcolumn row\fR +Returns the length of the string representation of the value currently +contained in the addressed cell. +.TP +\fImatrixName\fR \fBcolumns\fR +Returns the number of columns currently managed by the matrix. +.TP +\fImatrixName\fR \fBcolumnwidth\fR \fIcolumn\fR +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. +.TP +\fImatrixName\fR \fBdelete column\fR \fIcolumn\fR +Deletes the specified column from the matrix and shifts all columns +with higher indices one index down. +.TP +\fImatrixName\fR \fBdelete row\fR \fIrow\fR +Deletes the specified row from the matrix and shifts all row with +higher indices one index down. +.TP +\fImatrixName\fR \fBdestroy\fR +Destroys the matrix, including its storage space and associated +command. +.TP +\fImatrixName\fR \fBformat 2string\fR ?\fIreport\fR? +Formats the matrix using the specified report object and returns the +string containing the result of this operation. The report has to +support the \fBprintmatrix\fR method. If no \fIreport\fR is +specified the system will use an internal report definition to format +the matrix. +.TP +\fImatrixName\fR \fBformat 2chan\fR ??\fIreport\fR? \fIchannel\fR? +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 \fBprintmatrix2channel\fR method. If no +\fIreport\fR is specified the system will use an internal report +definition to format the matrix. If no \fIchannel\fR is specified the +system will use \fBstdout\fR. +.TP +\fImatrixName\fR \fBget cell\fR \fIcolumn row\fR +Returns the value currently contained in the cell identified by row +and column index. +.TP +\fImatrixName\fR \fBget column\fR \fIcolumn\fR +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. +.TP +\fImatrixName\fR \fBget rect\fR \fIcolumn_tl row_tl column_br row_br\fR +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 \fIcolumn_tl, row_tl\fR and +\fIcolumn_br, row_br\fR resp. Note that the following equations have +to be true: "\fIcolumn_tl\fR <= \fIcolumn_br\fR" and "\fIrow_tl\fR <= +\fIrow_br\fR". 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. +.TP +\fImatrixName\fR \fBget row\fR \fIrow\fR +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. +.TP +\fImatrixName\fR \fBinsert column\fR \fIcolumn\fR ?\fIvalues\fR? +Extends the matrix by one column and then acts like \fBsetcolumn\fR +(see below) on this new column if there were \fIvalues\fR +supplied. Without \fIvalues\fR 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 \fIcolumn\fR is less than or equal to +zero, then the new column is inserted at the beginning of the matrix, +before the first column. If \fIcolumn\fR has the value \fBend\fR, +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. +.TP +\fImatrixName\fR \fBinsert row\fR \fIrow\fR ?\fIvalues\fR? +Extends the matrix by one row and then acts like \fBsetrow\fR (see +below) on this new row if there were \fIvalues\fR supplied. Without +\fIvalues\fR 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 \fIrow\fR is less than or equal to zero, then the new row is +inserted at the beginning of the matrix, before the first row. If +\fIrow\fR has the value \fBend\fR, 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. +.TP +\fImatrixName\fR \fBlink\fR ?-transpose? \fIarrayvar\fR +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 \fI(column,row)\fR is stored in the array using the key +\fIcolumn,row\fR. If the option \fB-transpose\fR is specified the +key \fIrow,column\fR 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. +.TP +\fImatrixName\fR \fBlinks\fR +Returns a list containing the names of all array variables the matrix +was linked to through a call to method \fBlink\fR. +.TP +\fImatrixName\fR \fBrowheight\fR \fIrow\fR +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. +.TP +\fImatrixName\fR \fBrows\fR +Returns the number of rows currently managed by the matrix. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBall\fR \fIpattern\fR +Searches the whole matrix for cells matching the \fIpattern\fR 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. +.sp +The type of the pattern (string, glob, regular expression) is +determined by the option after the \fBsearch\fR keyword. If no +option is given it defaults to \fB-exact\fR. +.sp +If the option \fB-nocase\fR is specified the search will be +case-insensitive. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBcolumn\fR \fIcolumn pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified column. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrow\fR \fIrow pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified row. +.TP +\fImatrixName\fR \fBsearch\fR ?-nocase? ?-exact|-glob|-regexp? \fBrect\fR \fIcolumn_tl row_tl column_br row_br pattern\fR +Like \fBsearch all\fR, but the search is restricted to the +specified rectangular area of the matrix. +.TP +\fImatrixName\fR \fBset cell\fR \fIcolumn row value\fR +Sets the value in the cell identified by row and column index to the +data in the third argument. +.TP +\fImatrixName\fR \fBset column\fR \fIcolumn values\fR +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. +.TP +\fImatrixName\fR \fBset rect\fR \fIcolumn row values\fR +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 \fIvalues\fR 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 \fBgetrect\fR. +.TP +\fImatrixName\fR \fBset row\fR \fIrow values\fR +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. +.TP +\fImatrixName\fR \fBsort columns\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIrow\fR +Sorts the columns in the matrix using the data in the specified +\fIrow\fR as the key to sort by. The options \fB-increasing\fR +and \fB-decreasing\fR have the same meaning as for \fBlsort\fR. +If no option is specified \fB-increasing\fR is assumed. +.TP +\fImatrixName\fR \fBsort rows\fR ?\fB-increasing\fR|\fB-decreasing\fR? \fIcolumn\fR +Sorts the rows in the matrix using the data in the specified +\fIcolumn\fR as the key to sort by. The options \fB-increasing\fR +and \fB-decreasing\fR have the same meaning as for \fBlsort\fR. +If no option is specified \fB-increasing\fR is assumed. +.TP +\fImatrixName\fR \fBswap columns\fR \fIcolumn_a column_b\fR +Swaps the contents of the two specified columns. +.TP +\fImatrixName\fR \fBswap rows\fR \fIrow_a row_b\fR +Swaps the contents of the two specified rows. +.TP +\fImatrixName\fR \fBunlink\fR \fIarrayvar\fR +Removes the link between the matrix and the specified arrayvariable, +if there is one. +.PP +.SH EXAMPLES +.PP +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. +.PP +.CS + + + % 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}} + +.CE +.PP +.CS + + + % 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}} + +.CE +.PP +Assuming that the style definitions in the example section of the +manpage for the package \fBreport\fR 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. +.PP +.CS + + + % ::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 + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: matrix\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +matrix +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/pool.n Index: embedded/man/files/modules/struct/pool.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/pool.n @@ -0,0 +1,641 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/pool.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Erik Leunissen <e.leunissen@hccnet.nl> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::pool" n 1.2.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::pool \- Create and manipulate pool objects (of discrete items) +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::pool ?1.2.1?\fR +.sp +\fB::struct::pool\fR ?\fIpoolName\fR? ?\fImaxsize\fR? +.sp +\fBpoolName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIpoolName\fR \fBadd\fR \fIitemName1\fR ?\fIitemName2 itemName3 ...\fR? +.sp +\fIpoolName\fR \fBclear\fR ?\fB-force\fR? +.sp +\fIpoolName\fR \fBdestroy\fR ?\fB-force\fR? +.sp +\fIpoolName\fR \fBinfo\fR \fItype\fR ?\fIarg\fR? +.sp +\fIpoolName\fR \fBmaxsize\fR ?\fImaxsize\fR? +.sp +\fIpoolName\fR \fBrelease\fR \fIitemName\fR +.sp +\fIpoolName\fR \fBremove\fR \fIitemName\fR ?\fB-force\fR? +.sp +\fIpoolName\fR \fBrequest\fR itemVar ?options? +.sp +.BE +.SH DESCRIPTION +.PP +This package provides pool objects which can be used to manage +finite collections of discrete items. +.TP +\fB::struct::pool\fR ?\fIpoolName\fR? ?\fImaxsize\fR? +Creates a new pool object. If no \fIpoolName\fR is supplied, then the +new pool will be named pool\fBX\fR, where X is a positive integer. +The optional second argument \fImaxsize\fR 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 +\fB10\fR. +.sp +The pool object has an associated global Tcl command whose name is +\fIpoolName\fR. This command may be used to invoke various +configuration operations on the report. It has the following general +form: +.RS +.TP +\fBpoolName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. See section \fBPOOL OBJECT COMMAND\fR for a detailed +list of options and their behaviour. +.RE +.PP +.PP +.SH "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: +.IP \(bu +the seats in a cinema, theatre, train etc.. for which visitors/travelers can make a reservation; +.IP \(bu +the dynamic IP-addresses that an ISP can dole out to subscribers; +.IP \(bu +a car rental's collection of cars, which can be rented by customers; +.IP \(bu +the class rooms in a school building, which need to be scheduled; +.IP \(bu +the database connections available to client-threads in a web-server application; +.IP \(bu +the books in a library that customers can borrow; +.IP \(bu +etc ... +.PP +.PP +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. +.PP +Keeping track of which items are allocated, and by whom, is the +purpose of the pool command and its subordinates. +.PP +\fIPool parlance\fR: If we say that an item is +\fIallocated\fR, it means that the item is \fIbusy\fR, +\fIowned\fR or \fIoccupied\fR; it is not available anymore. If +an item is \fIfree\fR, it is \fIavailable\fR. 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. +.SH ITEMS +\fIDiscrete items\fR +.PP +The \fBpool\fR command is designed for +\fIdiscrete items only\fR. 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. +.PP +\fIUnique item names\fR +.PP +A pool cannot manage duplicate item names. Therefore, items in a pool +must have unique names. +.PP +\fIItem equivalence\fR +.PP +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. +.PP +\fIPreferences\fR +.PP +A future owner may have a preference for a particular item. Preference +based allocation is supported (see the \fB-prefer\fR 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. +.SH "POOL OBJECT COMMAND" +The following subcommands and corresponding arguments are available to +any pool object command. +.TP +\fIpoolName\fR \fBadd\fR \fIitemName1\fR ?\fIitemName2 itemName3 ...\fR? +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. +.TP +\fIpoolName\fR \fBclear\fR ?\fB-force\fR? +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 \fB-force\fR argument. If it +is supplied on the command line, the pool will be cleared regardless +the allocation state of its items. +.TP +\fIpoolName\fR \fBdestroy\fR ?\fB-force\fR? +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 +\fB-force\fR. If it is supplied on the command line, the pool data +structure will be destroyed regardless allocation state of its items. +.TP +\fIpoolName\fR \fBinfo\fR \fItype\fR ?\fIarg\fR? +Returns various information about the pool for further programmatic +use. The \fItype\fR argument indicates the type of information +requested. Only the type \fBallocID\fR uses an additional argument. +.RS +.TP +\fBallocID\fR \fIitemName\fR +returns the allocID of the item whose name is \fIitemName\fR. Free +items have an allocation id of \fB-1\fR. +.TP +\fBallitems\fR +returns a list of all items in the pool. +.TP +\fBallocstate\fR +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 \fB-1\fR. +.TP +\fBcursize\fR +returns the current pool size, i.e. the number of items in the pool. +.TP +\fBfreeitems\fR +returns a list of items that currently are not allocated. +.TP +\fBmaxsize\fR +returns the maximum size of the pool. +.RE +.sp +.TP +\fIpoolName\fR \fBmaxsize\fR ?\fImaxsize\fR? +Sets or queries the maximum size of the pool, depending on whether the +\fImaxsize\fR argument is supplied or not. If \fImaxsize\fR 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: +.sp +\fBpoolName info maxsize\fR. +.sp +The \fImaxsize\fR argument has to be a positive integer. +.TP +\fIpoolName\fR \fBrelease\fR \fIitemName\fR +Releases the item whose name is \fIitemName\fR that was allocated +previously. An error is raised if the item was not allocated at the +time when the command was issued. +.TP +\fIpoolName\fR \fBremove\fR \fIitemName\fR ?\fB-force\fR? +Removes the item whose name is \fIitemName\fR 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 \fB-force\fR. If it is supplied on the command line, the +item will be removed regardless its allocation state. +.TP +\fIpoolName\fR \fBrequest\fR 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: +.RS +.IP [1] +The request is honoured, an item is allocated and the variable whose +name is passed with the argument \fIitemVar\fR will be set to the name +of the item that was allocated. The command returns 1. +.IP [2] +The request is denied. No item is allocated. The variable whose name +is itemVar is not set. Attempts to read \fIitemVar\fR may raise an +error if the variable was not defined before issuing the request. The +command returns 0. +.RE +.sp +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 \fB-prefer\fR (see below), then +all requests are honoured as long as items are available. +.sp +The following options are supported: +.RS +.TP +\fB-allocID\fR \fIallocID\fR +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 +\fB-allocID\fR is not supplied, the item will be given to and owned +by \fBdummyID\fR. Allocation id's may be anything except the value +-1, which is reserved for free items. +.TP +\fB-prefer\fR \fIpreferredItem\fR +This option modifies the allocation strategy as follows: If the item +whose name is \fIpreferredItem\fR 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). +.RE +.PP +.SH 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. +.PP +\fIExample 1\fR +.PP +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. +.PP +\fINote aside:\fR +.PP +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. +.PP +.CS + + + 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 + +.CE +.PP +Suspend the interactive session temporarily, and show the programmatic +use of the request subcommand: +.PP +.CS + + + # 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." + } + +.CE +.PP +Note how the \fBif\fR command uses the value returned by the +\fBrequest\fR subcommand. +.PP +.CS + + + # 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." + } + +.CE +.PP +Resume the interactive session: +.PP +.CS + + + 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 + +.CE +.PP +\fIExample 2\fR +.PP +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. +.PP +.CS + + + # 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. + } + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: pool\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +discrete items, finite, pool, struct +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002, Erik Leunissen <e.leunissen@hccnet.nl> + +.fi ADDED embedded/man/files/modules/struct/prioqueue.n Index: embedded/man/files/modules/struct/prioqueue.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/prioqueue.n @@ -0,0 +1,359 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/prioqueue.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003 Michael Schlenker <mic42@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::prioqueue" n 1.4 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::prioqueue \- Create and manipulate prioqueue objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::prioqueue ?1.4?\fR +.sp +\fB::struct::prioqueue\fR ?\fB-ascii|-dictionary|-integer|-real\fR? ?\fIprioqueueName\fR? +.sp +\fIprioqueueName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fIprioqueueName\fR \fBclear\fR +.sp +\fIprioqueueName\fR \fBremove\fR \fIitem\fR +.sp +\fIprioqueueName\fR \fBdestroy\fR +.sp +\fIprioqueueName\fR \fBget\fR ?\fIcount\fR? +.sp +\fIprioqueueName\fR \fBpeek\fR ?\fIcount\fR? +.sp +\fIprioqueueName\fR \fBpeekpriority\fR ?\fIcount\fR? +.sp +\fIprioqueueName\fR \fBput\fR \fIitem prio\fR ?\fIitem prio ...\fR? +.sp +\fIprioqueueName\fR \fBsize\fR +.sp +.BE +.SH DESCRIPTION +This package implements a simple priority queue using nested tcl lists. +.PP +The command \fB::struct::prioqueue\fR creates a new priority queue +with default priority key type \fI-integer\fR. This means that keys +given to the \fBput\fR subcommand must have this type. +.PP +This also sets the priority ordering. For key types \fI-ascii\fR and +\fI-dictionary\fR the data is sorted in ascending order (as with +\fBlsort\fR \fI-increasing\fR), thereas for \fI-integer\fR and +\fI-real\fR the data is sorted in descending order (as with +\fBlsort\fR \fI-decreasing\fR). +.PP +Prioqueue names are unrestricted, but may be recognized as options if +no priority type is given. +.TP +\fB::struct::prioqueue\fR ?\fB-ascii|-dictionary|-integer|-real\fR? ?\fIprioqueueName\fR? +The \fB::struct::prioqueue\fR command creates a new prioqueue object +with an associated global Tcl command whose name is +\fIprioqueueName\fR. This command may be used to invoke various +operations on the prioqueue. It has the following general form: +.TP +\fIprioqueueName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fBoption\fR and the \fIarg\fRs determine the exact behavior of the +command. The following commands are possible for prioqueue objects: +.TP +\fIprioqueueName\fR \fBclear\fR +Remove all items from the prioqueue. +.TP +\fIprioqueueName\fR \fBremove\fR \fIitem\fR +Remove the selected item from this priority queue. +.TP +\fIprioqueueName\fR \fBdestroy\fR +Destroy the prioqueue, including its storage space and associated +command. +.TP +\fIprioqueueName\fR \fBget\fR ?\fIcount\fR? +Return the front \fIcount\fR items of the prioqueue (but not their +priorities) and remove them from the prioqueue. +If \fIcount\fR is not specified, it defaults to 1. If \fIcount\fR is +1, the result is a simple string; otherwise, it is a list. If +specified, \fIcount\fR 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. +.TP +\fIprioqueueName\fR \fBpeek\fR ?\fIcount\fR? +Return the front \fIcount\fR items of the prioqueue (but not their +priorities), without removing them from the prioqueue. +If \fIcount\fR is not specified, it defaults to 1. If \fIcount\fR is +1, the result is a simple string; otherwise, it is a list. If +specified, \fIcount\fR 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. +.TP +\fIprioqueueName\fR \fBpeekpriority\fR ?\fIcount\fR? +Return the front \fIcount\fR items priority keys, without removing +them from the prioqueue. +If \fIcount\fR is not specified, it defaults to 1. If \fIcount\fR is +1, the result is a simple string; otherwise, it is a list. If +specified, \fIcount\fR 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. +.TP +\fIprioqueueName\fR \fBput\fR \fIitem prio\fR ?\fIitem prio ...\fR? +Put the \fIitem\fR or items specified into the prioqueue. \fIprio\fR +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. +.TP +\fIprioqueueName\fR \fBsize\fR +Return the number of items in the prioqueue. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: prioqueue\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ordered list, prioqueue, priority queue +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2003 Michael Schlenker <mic42@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/queue.n Index: embedded/man/files/modules/struct/queue.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/queue.n @@ -0,0 +1,331 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/queue.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::queue" n 1.4.4 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::queue \- Create and manipulate queue objects +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::queue ?1.4.4?\fR +.sp +\fIqueueName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fIqueueName\fR \fBclear\fR +.sp +\fIqueueName\fR \fBdestroy\fR +.sp +\fIqueueName\fR \fBget\fR ?\fIcount\fR? +.sp +\fIqueueName\fR \fBpeek\fR ?\fIcount\fR? +.sp +\fIqueueName\fR \fBput\fR \fIitem\fR ?\fIitem ...\fR? +.sp +\fIqueueName\fR \fBunget\fR \fIitem\fR +.sp +\fIqueueName\fR \fBsize\fR +.sp +.BE +.SH DESCRIPTION +The \fB::struct\fR namespace contains a commands for processing +finite queues. +.PP +It exports a single command, \fB::struct::queue\fR. All functionality +provided here can be reached through a subcommand of this command. +.PP +\fINote:\fR 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. +.PP +The \fB::struct::queue\fR command creates a new queue object with an +associated global Tcl command whose name is \fIqueueName\fR. This +command may be used to invoke various operations on the queue. It has +the following general form: +.TP +\fIqueueName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. The following commands are possible for queue objects: +.TP +\fIqueueName\fR \fBclear\fR +Remove all items from the queue. +.TP +\fIqueueName\fR \fBdestroy\fR +Destroy the queue, including its storage space and associated command. +.TP +\fIqueueName\fR \fBget\fR ?\fIcount\fR? +Return the front \fIcount\fR items of the queue and remove them from +the queue. If \fIcount\fR is not specified, it defaults to 1. If +\fIcount\fR is 1, the result is a simple string; otherwise, it is a +list. If specified, \fIcount\fR 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. +.TP +\fIqueueName\fR \fBpeek\fR ?\fIcount\fR? +Return the front \fIcount\fR items of the queue, without removing them +from the queue. If \fIcount\fR is not specified, it defaults to 1. +If \fIcount\fR is 1, the result is a simple string; otherwise, it is a +list. If specified, \fIcount\fR 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. +.TP +\fIqueueName\fR \fBput\fR \fIitem\fR ?\fIitem ...\fR? +Put the \fIitem\fR or items specified into the queue. If more than +one \fIitem\fR is given, they will be added in the order they are +listed. +.TP +\fIqueueName\fR \fBunget\fR \fIitem\fR +Put the \fIitem\fR 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 \fBget\fR. +.TP +\fIqueueName\fR \fBsize\fR +Return the number of items in the queue. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: queue\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +graph, list, matrix, pool, prioqueue, record, set, skiplist, stack, tree +.SH CATEGORY +Data structures ADDED embedded/man/files/modules/struct/record.n Index: embedded/man/files/modules/struct/record.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/record.n @@ -0,0 +1,619 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/record.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::record" n 1.2.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::record \- Define and create records (similar to 'C' structures) +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::record ?1.2.1?\fR +.sp +\fBrecord define\fR \fIrecordName\fR \fIrecordMembers\fR ?\fIinstanceName1 instanceName2 ...\fR? +.sp +\fBrecord show\fR \fIrecord\fR +.sp +\fBrecord show\fR \fIinstances\fR \fIrecordName\fR +.sp +\fBrecord show\fR \fImembers\fR \fIrecordName\fR +.sp +\fBrecord show\fR \fIvalues\fR \fIinstanceName\fR +.sp +\fBrecord exists\fR \fIrecord\fR \fIrecordName\fR +.sp +\fBrecord exists\fR \fIinstance\fR \fIinstanceName\fR +.sp +\fBrecord delete\fR \fIrecord\fR \fIrecordName\fR +.sp +\fBrecord delete\fR \fIinstance\fR \fIinstanceName\fR +.sp +\fIrecordName\fR \fB\fIinstanceName|#auto\fR\fR ?\fI-member1 value1 -member2 value2 ...\fR? +.sp +\fIinstanceName\fR \fBcget\fR ?\fI-member1 -member2 ...\fR? +.sp +\fIinstanceName\fR \fBconfigure\fR ?\fI-member1 value1 -member2 value2 ...\fR? +.sp +.BE +.SH DESCRIPTION +The \fB::struct::record\fR package provides a mechanism to group variables together +as one data structure, similar to a 'C' structure. The members of a +record can be variables or other records. However, a record can not contain circular +record, i.e. records that contain the same record as a +member. +.PP +This package was structured so that it is very similar to how Tk objects work. Each record +definition creates a record object that encompasses that definition. Subsequently, that +record object can create instances of that record. These instances can then +be manipulated with the \fBcget\fR and \fBconfigure\fR methods. +.PP +The package only contains one top level command, but several sub commands (see below). It also obeys the namespace in which the record was define, hence the objects returned are fully qualified. +.TP +\fBrecord define\fR \fIrecordName\fR \fIrecordMembers\fR ?\fIinstanceName1 instanceName2 ...\fR? +Defines a record. \fIrecordName\fR is the name of the record, and is also +used as an object command. This object command is used to create instances of the +record definition. \fIrecordMembers\fR are the members of +the record that make up the record definition. These are variables +and other record. If optional \fIinstanceName\fR args are given, then an instance +is generated after the definition is created for each \fIinstanceName\fR. +.TP +\fBrecord show\fR \fIrecord\fR +Returns a list of records that have been defined. +.TP +\fBrecord show\fR \fIinstances\fR \fIrecordName\fR +Returns the instances that have been instantiated by +\fIrecordName\fR. +.TP +\fBrecord show\fR \fImembers\fR \fIrecordName\fR +Returns the members that are defined for +record \fIrecordName\fR. It returns the same format as how the +records were defined. +.TP +\fBrecord show\fR \fIvalues\fR \fIinstanceName\fR +Returns a list of values that are set for the instance +\fIinstanceName\fR. The output is a list of key/value pairs. If there +are nested records, then the values of the nested records will +itself be a list. +.TP +\fBrecord exists\fR \fIrecord\fR \fIrecordName\fR +Tests for the existence of a \fIrecord\fR with the +name \fIrecordName\fR. +.TP +\fBrecord exists\fR \fIinstance\fR \fIinstanceName\fR +Tests for the existence of a \fIinstance\fR with the +name \fIinstanceName\fR. +.TP +\fBrecord delete\fR \fIrecord\fR \fIrecordName\fR +Deletes \fIrecordName\fR, and all instances of \fIrecordName\fR. It will return +an error if the record does not exist. +.TP +\fBrecord delete\fR \fIinstance\fR \fIinstanceName\fR +Deletes \fIinstance\fR with the name of \fIinstanceName\fR. It +will return an error if the instance does not exist. +.PP +.PP +.SH "RECORD MEMBERS" +Record members can either be variables, or other records, However, the +same record can not be nested witin itself (circular). To define a +nested record, you need to specify the \fBrecord\fR keyword, along +the with name of the record, and the name of the instance of that +nested record. For example, it would look like this: +.PP +.CS + + +# this is the nested record +record define mynestedrecord { + nest1 + nest2 +} + +# This is the main record +record define myrecord { + mem1 + mem2 + {record mynestedrecord mem3} +} + + +.CE +You can also assign default or initial values to the members of a record, +by enclosing the member entry in braces: +.PP +.CS + + + +record define myrecord { + mem1 + {mem2 5} +} + + +.CE +All instances created from this record definition, will initially have 5 as +the value for \fImem2\fR. If no default is given, then the value will be the empty string. +.PP +\fIGetting Values\fR +.PP +To get a value of a member, there are several ways to do this. +.IP [1] +To get a member value, then use the instance built-in \fBcget\fR method: +.sp +\fIinstanceName\fR \fBcget\fR -mem1 +.IP [2] +To get multiple member values, you can specify them all in one command: +.sp +\fIinstanceName\fR \fBcget\fR -mem1 -mem2 +.IP [3] +To get a list of the key/value of all of the members, there are 3 ways: +.sp +- \fIinstanceName\fR \fBcget\fR +.sp +- \fIinstanceName\fR \fBconfigure\fR +.sp +- \fIinstanceName\fR +.IP [4] +To get a value of a nested member, then use the dot notation: +.sp +\fIinstanceName\fR \fBcget\fR -mem3.nest1 +.PP +.PP +\fISetting Values\fR +.PP +To set a value of a member, there are several ways to do this. +.IP [1] +To set a member value, then use the instance built-in \fBconfigure\fR method: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem1 val1 +.IP [2] +To set multiple member values, you can specify them all in one command: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem1 va1 -mem2 val2 +.IP [3] +To set a value of a nested member, then use the dot notation: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem3.nest1 value +.PP +.PP +\fIAlias access\fR +.PP +In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However, +there was a concensus to make the interface more Tcl like, which made sense. However, the original alias access still +exists. It might prove to be helpful to some. +.PP +Basically, for every member of every instance, an alias is created. This alias is used to get and set values for that +member. An example will illustrate the point, using the above defined records: +.PP +.CS + + +# Create an instance first +% myrecord inst1 +::inst1 +% # To get a member of an instance, just use the +% # alias (it behaves like a Tcl command): +% inst1.mem1 +% +% # To set a member via the alias, just include +% # a value (optionally the equal sign - syntactic sugar) +% inst1.mem1 = 5 +5 +% inst1.mem1 +5 +% # For nested records, just continue with the +% # dot notation (note no equal sign) +% inst1.mem3.nest1 10 +10 +% inst1.mem3.nest1 +10 +% # just the instance by itself gives all +% # member/values pairs for that instance +% inst1 +-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} +% # and to get all members within the nested record +% inst1.mem3 +-nest1 10 -nest2 {} +% + + +.CE +.SH "RECORD COMMAND" +The following subcommands and corresponding arguments are available to any +record command: +.TP +\fIrecordName\fR \fB\fIinstanceName|#auto\fR\fR ?\fI-member1 value1 -member2 value2 ...\fR? +Using the \fIrecordName\fR object command that was created from the record definition, +instances of the record definition can be created. Once a instance is +created, then it inherits the members of the record definition, very +similar to how objects work. During instance generation, an object command for the instance +is created as well, using \fIinstanceName\fR. This object command is used +to access the data members of the instance. During the instantiation, values for +that instance can be given, \fIbut\fR all values must be given, and be given +in key/value pairs. Nested records, need to be in list format. +.sp +Optionally, \fI#auto\fR can be used in place of \fIinstanceName\fR. When #auto is used, +then a instance name will automatically be generated, of the form recordName<integer>, where +<integer> is a unique integer (starting at 0) that is generated. +.PP +.PP +.SH "INSTANCE COMMAND" +The following subcommands and corresponding arguments are available to +any record instance command: +.TP +\fIinstanceName\fR \fBcget\fR ?\fI-member1 -member2 ...\fR? +Each instance has the sub command \fBcget\fR associated with it. This +is very similar to how Tk widget's cget command works. It queries +the values of the member for that particular instance. If +no arguments are given, then a key/value list is returned. +.TP +\fIinstanceName\fR \fBconfigure\fR ?\fI-member1 value1 -member2 value2 ...\fR? +Each instance has the sub command \fBconfigure\fR associated with it. This +is very similar to how Tk widget's configure command works. It sets +the values of the particular member for that particular instance. If +no arguments are given, then a key/value list is returned. +.PP +.SH EXAMPLES +Two examples are provided to give an good illustration on how to use +this package. +.PP +\fIExample 1\fR +.PP +Probably the most obvious example would be to hold contact information, +such as addresses, phone numbers, comments, etc. Since a person can have +multiple phone numbers, multiple email addresses, etc, we will use nested +records to define these. So, the first thing we do is define the nested +records: +.PP +.CS + + + +## +## 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} +% + +.CE +.PP +\fIExample 1\fR +.PP +This next example just illustrates a simple linked list +.PP +.CS + + + +% # define a very simple record for linked list +% record define 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 +% + + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: record\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +data structures, record, struct +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com> + +.fi ADDED embedded/man/files/modules/struct/skiplist.n Index: embedded/man/files/modules/struct/skiplist.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/skiplist.n @@ -0,0 +1,330 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/skiplist.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2000 Keith Vetter +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::skiplist" n 1.3 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::skiplist \- Create and manipulate skiplists +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::skiplist ?1.3?\fR +.sp +\fBskiplistName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fIskiplistName\fR \fBdelete\fR \fInode\fR ?\fInode\fR...? +.sp +\fIskiplistName\fR \fBdestroy\fR +.sp +\fIskiplistName\fR \fBinsert\fR \fIkey value\fR +.sp +\fIskiplistName\fR \fBsearch\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +.sp +\fIskiplistName\fR \fBsize\fR +.sp +\fIskiplistName\fR \fBwalk\fR \fIcmd\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::skiplist\fR command creates a new skiplist object +with an associated global Tcl command whose name is +\fIskiplistName\fR. This command may be used to invoke various +operations on the skiplist. It has the following general form: +.TP +\fBskiplistName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +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. +.PP +To read more about skip lists see Pugh, William. +\fISkip lists: a probabilistic alternative to balanced trees\fR +In: Communications of the ACM, June 1990, 33(6) 668-676. +.PP +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: +.TP +\fIskiplistName\fR \fBdelete\fR \fInode\fR ?\fInode\fR...? +Remove the specified nodes from the skiplist. +.TP +\fIskiplistName\fR \fBdestroy\fR +Destroy the skiplist, including its storage space and associated command. +.TP +\fIskiplistName\fR \fBinsert\fR \fIkey value\fR +Insert a node with the given \fIkey\fR and \fIvalue\fR 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. +.TP +\fIskiplistName\fR \fBsearch\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +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. +.TP +\fIskiplistName\fR \fBsize\fR +Return a count of the number of nodes in the skiplist. +.TP +\fIskiplistName\fR \fBwalk\fR \fIcmd\fR +Walk the skiplist from the first node to the last. At each node, the +command \fIcmd\fR will be evaluated with the key and value of the +current node appended. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: skiplist\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +skiplist +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2000 Keith Vetter + +.fi ADDED embedded/man/files/modules/struct/stack.n Index: embedded/man/files/modules/struct/stack.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/stack.n @@ -0,0 +1,354 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/stack.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::stack" n 1.5.3 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::stack \- Create and manipulate stack objects +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::stack ?1.5.3?\fR +.sp +\fIstackName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fIstackName\fR \fBclear\fR +.sp +\fIstackName\fR \fBdestroy\fR +.sp +\fIstackName\fR \fBget\fR +.sp +\fIstackName\fR \fBgetr\fR +.sp +\fIstackName\fR \fBpeek\fR ?\fIcount\fR? +.sp +\fIstackName\fR \fBpeekr\fR ?\fIcount\fR? +.sp +\fIstackName\fR \fBtrim\fR ?\fInewsize\fR? +.sp +\fIstackName\fR \fBtrim*\fR ?\fInewsize\fR? +.sp +\fIstackName\fR \fBpop\fR ?\fIcount\fR? +.sp +\fIstackName\fR \fBpush\fR \fIitem\fR ?\fIitem...\fR? +.sp +\fIstackName\fR \fBsize\fR +.sp +.BE +.SH DESCRIPTION +The \fB::struct\fR namespace contains a commands for processing +finite stacks. +.PP +It exports a single command, \fB::struct::stack\fR. All functionality +provided here can be reached through a subcommand of this command. +.PP +\fINote:\fR 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. +.PP +The \fB::struct::stack\fR command creates a new stack object with an +associated global Tcl command whose name is \fIstackName\fR. This +command may be used to invoke various operations on the stack. It has +the following general form: +.TP +\fIstackName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. The following commands are possible for stack objects: +.TP +\fIstackName\fR \fBclear\fR +Remove all items from the stack. +.TP +\fIstackName\fR \fBdestroy\fR +Destroy the stack, including its storage space and associated command. +.TP +\fIstackName\fR \fBget\fR +Returns the whole contents of the stack as a list, without removing +them from the stack. +.TP +\fIstackName\fR \fBgetr\fR +A variant of \fBget\fR, which returns the contents in reversed order. +.TP +\fIstackName\fR \fBpeek\fR ?\fIcount\fR? +Return the top \fIcount\fR items of the stack, without removing them from +the stack. If \fIcount\fR is not specified, it defaults to 1. If +\fIcount\fR is 1, the result is a simple string; otherwise, it is a +list. If specified, \fIcount\fR 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. +.TP +\fIstackName\fR \fBpeekr\fR ?\fIcount\fR? +A variant of \fBpeek\fR, which returns the items in reversed order. +.TP +\fIstackName\fR \fBtrim\fR ?\fInewsize\fR? +Shrinks the stack to contain at most \fInewsize\fR 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. +.TP +\fIstackName\fR \fBtrim*\fR ?\fInewsize\fR? +A variant of \fBtrim\fR which performs the shrinking, but does not +return the removed elements. +.TP +\fIstackName\fR \fBpop\fR ?\fIcount\fR? +Return the top \fIcount\fR items of the stack, and remove them +from the stack. If \fIcount\fR is not specified, it defaults to 1. +If \fIcount\fR is 1, the result is a simple string; otherwise, it is a +list. If specified, \fIcount\fR 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. +.TP +\fIstackName\fR \fBpush\fR \fIitem\fR ?\fIitem...\fR? +Push the \fIitem\fR or items specified onto the stack. If more than +one \fIitem\fR is given, they will be pushed in the order they are +listed. +.TP +\fIstackName\fR \fBsize\fR +Return the number of items on the stack. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: stack\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +graph, matrix, queue, tree +.SH CATEGORY +Data structures ADDED embedded/man/files/modules/struct/struct_list.n Index: embedded/man/files/modules/struct/struct_list.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/struct_list.n @@ -0,0 +1,971 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/struct_list.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2003-2005 by Kevin B. Kenny. All rights reserved +'\" Copyright (c) 2003-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::list" n 1.8.2 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::list \- Procedures for manipulating lists +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBstruct::list ?1.8.2?\fR +.sp +\fB::struct::list\fR \fBlongestCommonSubsequence\fR \fIsequence1\fR \fIsequence2\fR ?\fImaxOccurs\fR? +.sp +\fB::struct::list\fR \fBlongestCommonSubsequence2\fR \fIsequence1 sequence2\fR ?\fImaxOccurs\fR? +.sp +\fB::struct::list\fR \fBlcsInvert\fR \fIlcsData\fR \fIlen1\fR \fIlen2\fR +.sp +\fB::struct::list\fR \fBlcsInvert2\fR \fIlcs1\fR \fIlcs2\fR \fIlen1\fR \fIlen2\fR +.sp +\fB::struct::list\fR \fBlcsInvertMerge\fR \fIlcsData\fR \fIlen1\fR \fIlen2\fR +.sp +\fB::struct::list\fR \fBlcsInvertMerge2\fR \fIlcs1\fR \fIlcs2\fR \fIlen1\fR \fIlen2\fR +.sp +\fB::struct::list\fR \fBreverse\fR \fIsequence\fR +.sp +\fB::struct::list\fR \fBshuffle\fR \fIlist\fR +.sp +\fB::struct::list\fR \fBassign\fR \fIsequence\fR \fIvarname\fR ?\fIvarname\fR?... +.sp +\fB::struct::list\fR \fBflatten\fR ?\fB-full\fR? ?\fB--\fR? \fIsequence\fR +.sp +\fB::struct::list\fR \fBmap\fR \fIsequence\fR \fIcmdprefix\fR +.sp +\fB::struct::list\fR \fBmapfor\fR \fIvar\fR \fIsequence\fR \fIscript\fR +.sp +\fB::struct::list\fR \fBfilter\fR \fIsequence\fR \fIcmdprefix\fR +.sp +\fB::struct::list\fR \fBfilterfor\fR \fIvar\fR \fIsequence\fR \fIexpr\fR +.sp +\fB::struct::list\fR \fBsplit\fR \fIsequence\fR \fIcmdprefix\fR ?\fIpassVar\fR \fIfailVar\fR? +.sp +\fB::struct::list\fR \fBfold\fR \fIsequence\fR \fIinitialvalue\fR \fIcmdprefix\fR +.sp +\fB::struct::list\fR \fBshift\fR \fIlistvar\fR +.sp +\fB::struct::list\fR \fBiota\fR \fIn\fR +.sp +\fB::struct::list\fR \fBequal\fR \fIa\fR \fIb\fR +.sp +\fB::struct::list\fR \fBrepeat\fR \fIsize\fR \fIelement1\fR ?\fIelement2\fR \fIelement3\fR...? +.sp +\fB::struct::list\fR \fBrepeatn\fR \fIvalue\fR \fIsize\fR... +.sp +\fB::struct::list\fR \fBdbJoin\fR ?\fB-inner\fR|\fB-left\fR|\fB-right\fR|\fB-full\fR? ?\fB-keys\fR \fIvarname\fR? {\fIkeycol\fR \fItable\fR}... +.sp +\fB::struct::list\fR \fBdbJoinKeyed\fR ?\fB-inner\fR|\fB-left\fR|\fB-right\fR|\fB-full\fR? ?\fB-keys\fR \fIvarname\fR? \fItable\fR... +.sp +\fB::struct::list\fR \fBswap\fR \fIlistvar\fR \fIi\fR \fIj\fR +.sp +\fB::struct::list\fR \fBfirstperm\fR \fIlist\fR +.sp +\fB::struct::list\fR \fBnextperm\fR \fIperm\fR +.sp +\fB::struct::list\fR \fBpermutations\fR \fIlist\fR +.sp +\fB::struct::list\fR \fBforeachperm\fR \fIvar\fR \fIlist\fR \fIbody\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::list\fR 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. +.PP +It exports only a single command, \fBstruct::list\fR. All +functionality provided here can be reached through a subcommand of +this command. +.SH COMMANDS +.TP +\fB::struct::list\fR \fBlongestCommonSubsequence\fR \fIsequence1\fR \fIsequence2\fR ?\fImaxOccurs\fR? +Returns the longest common subsequence of elements in the two lists +\fIsequence1\fR and \fIsequence2\fR. If the \fImaxOccurs\fR parameter +is provided, the common subsequence is restricted to elements that +occur no more than \fImaxOccurs\fR times in \fIsequence2\fR. +.sp +The return value is a list of two lists of equal length. The first +sublist is of indices into \fIsequence1\fR, and the second sublist is +of indices into \fIsequence2\fR. Each corresponding pair of indices +corresponds to equal elements in the sequences; the sequence returned +is the longest possible. +.TP +\fB::struct::list\fR \fBlongestCommonSubsequence2\fR \fIsequence1 sequence2\fR ?\fImaxOccurs\fR? +Returns an approximation to the longest common sequence of elements in +the two lists \fIsequence1\fR and \fIsequence2\fR. +If the \fImaxOccurs\fR 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 +\fImaxOccurs\fR times in \fIsequence2\fR, and then using that result +to align the two lists, determining the longest common subsequences of +the sublists between the two elements. +.sp +As with \fBlongestCommonSubsequence\fR, the return value is a list +of two lists of equal length. The first sublist is of indices into +\fIsequence1\fR, and the second sublist is of indices into +\fIsequence2\fR. Each corresponding pair of indices corresponds to +equal elements in the sequences. The sequence approximates the +longest common subsequence. +.TP +\fB::struct::list\fR \fBlcsInvert\fR \fIlcsData\fR \fIlen1\fR \fIlen2\fR +This command takes a description of a longest common subsequence +(\fIlcsData\fR), 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. +.sp +To be fully defined the lengths of the two sequences have to be known +and are specified through \fIlen1\fR and \fIlen2\fR. +.sp +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 +\fIsequence1\fR and \fIsequence2\fR respectively, in this order. +The type can be one of three values: +.RS +.TP +\fBadded\fR +Describes an addition. I.e. items which are missing in \fIsequence1\fR +can be found in \fIsequence2\fR. +The pair of indices into \fIsequence1\fR describes where the added +range had been expected to be in \fIsequence1\fR. 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 \fIsequence2\fR 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. +.TP +\fBdeleted\fR +Describes a deletion. I.e. items which are in \fIsequence1\fR are +missing from \fIsequence2\fR. +The pair of indices into \fIsequence1\fR 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 \fIsequence2\fR describes where the deleted +range had been expected to be in \fIsequence2\fR. 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. +.TP +\fBchanged\fR +Describes a general change. I.e a range of items in \fIsequence1\fR +has been replaced by a different range of items in \fIsequence2\fR. +The pair of indices into \fIsequence1\fR 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 \fIsequence2\fR 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. +.RE +.sp +.CS + + + 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}}} + +.CE +.IP +\fINotes:\fR +.sp +.RS +.IP \(bu +An index of \fB-1\fR in a \fIdeleted\fR chunk refers to just before +the first element of the second sequence. +.IP \(bu +Also an index equal to the length of the first sequence in an +\fIadded\fR chunk refers to just behind the end of the sequence. +.RE +.TP +\fB::struct::list\fR \fBlcsInvert2\fR \fIlcs1\fR \fIlcs2\fR \fIlen1\fR \fIlen2\fR +Similar to \fBlcsInvert\fR. Instead of directly taking the result +of a call to \fBlongestCommonSubsequence\fR this subcommand expects +the indices for the two sequences in two separate lists. +.TP +\fB::struct::list\fR \fBlcsInvertMerge\fR \fIlcsData\fR \fIlen1\fR \fIlen2\fR +Similar to \fBlcsInvert\fR. It returns essentially the same +structure as that command, except that it may contain chunks of type +\fBunchanged\fR too. +.sp +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. +.sp +.CS + + + 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}}} + +.CE +.TP +\fB::struct::list\fR \fBlcsInvertMerge2\fR \fIlcs1\fR \fIlcs2\fR \fIlen1\fR \fIlen2\fR +Similar to \fBlcsInvertMerge\fR. Instead of directly taking the +result of a call to \fBlongestCommonSubsequence\fR this subcommand +expects the indices for the two sequences in two separate lists. +.TP +\fB::struct::list\fR \fBreverse\fR \fIsequence\fR +The subcommand takes a single \fIsequence\fR as argument and returns a new +sequence containing the elements of the input sequence in reverse +order. +.TP +\fB::struct::list\fR \fBshuffle\fR \fIlist\fR +The subcommand takes a \fIlist\fR 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. +.TP +\fB::struct::list\fR \fBassign\fR \fIsequence\fR \fIvarname\fR ?\fIvarname\fR?... +The subcommand assigns the first \fBn\fR elements of the input +\fIsequence\fR to the one or more variables whose names were listed +after the sequence, where \fBn\fR is the number of specified +variables. +.sp +If there are more variables specified than there are elements in the +\fIsequence\fR the empty string will be assigned to the superfluous +variables. +.sp +If there are more elements in the \fIsequence\fR than variable names +specified the subcommand returns a list containing the unassigned +elements. Else an empty list is returned. +.CS + + + tclsh> ::struct::list assign {a b c d e} foo bar + c d e + tclsh> set foo + a + tclsh> set bar + b + +.CE +.TP +\fB::struct::list\fR \fBflatten\fR ?\fB-full\fR? ?\fB--\fR? \fIsequence\fR +The subcommand takes a single \fIsequence\fR 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. +.sp +The subcommand will remove any nesting it finds if the option +\fB-full\fR is specified. +.CS + + + 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 + +.CE +.TP +\fB::struct::list\fR \fBmap\fR \fIsequence\fR \fIcmdprefix\fR +The subcommand takes a \fIsequence\fR to operate on and a command +prefix (\fIcmdprefix\fR) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of the results of that application. +.sp +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. +.sp +.CS + + + 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 + +.CE +.TP +\fB::struct::list\fR \fBmapfor\fR \fIvar\fR \fIsequence\fR \fIscript\fR +The subcommand takes a \fIsequence\fR to operate on and a tcl \fIscript\fR, +applies the script to each element of the sequence and returns a sequence +consisting of the results of that application. +.sp +The script will be evaluated as is, and has access to the current list element +through the specified iteration variable \fIvar\fR. The evaluation takes place +in the context of the caller of the subcommand. +.sp +.CS + + + 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 + +.CE +.TP +\fB::struct::list\fR \fBfilter\fR \fIsequence\fR \fIcmdprefix\fR +The subcommand takes a \fIsequence\fR to operate on and a command +prefix (\fIcmdprefix\fR) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of all elements of the \fIsequence\fR for which the command +prefix returned \fBtrue\fR. +In other words, this command filters out all elements of the input +\fIsequence\fR which fail the test the \fIcmdprefix\fR represents, and +returns the remaining elements. +.sp +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. +.sp +.CS + + + 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 + +.CE +.sp +\fINote:\fR The \fBfilter\fR is a specialized application of +\fBfold\fR where the result is extended with the current item or +not, depending o nthe result of the test. +.TP +\fB::struct::list\fR \fBfilterfor\fR \fIvar\fR \fIsequence\fR \fIexpr\fR +The subcommand takes a \fIsequence\fR to operate on and a tcl expression +(\fIexpr\fR) specifying a condition, applies the conditionto each element +of the sequence and returns a sequence consisting of all elements of the +\fIsequence\fR for which the expression returned \fBtrue\fR. +In other words, this command filters out all elements of the input +\fIsequence\fR which fail the test the condition \fIexpr\fR represents, and +returns the remaining elements. +.sp +The expression will be evaluated as is, and has access to the current list +element through the specified iteration variable \fIvar\fR. The evaluation +takes place in the context of the caller of the subcommand. +.sp +.CS + + + tclsh> # removing all odd numbers from the input + + tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0} + 2 4 + +.CE +.TP +\fB::struct::list\fR \fBsplit\fR \fIsequence\fR \fIcmdprefix\fR ?\fIpassVar\fR \fIfailVar\fR? +This is a variant of method \fBfilter\fR, see above. Instead of +returning just the elements passing the test we get lists of both +passing and failing elements. +.sp +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. +.sp +The interface to the test is the same as used by \fBfilter\fR. +.TP +\fB::struct::list\fR \fBfold\fR \fIsequence\fR \fIinitialvalue\fR \fIcmdprefix\fR +The subcommand takes a \fIsequence\fR to operate on, an arbitrary +string \fIinitial value\fR and a command prefix (\fIcmdprefix\fR) +specifying an operation. +.sp +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. +.sp +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 +.RS +.TP +\fB1\fR +Application of the command to the initial value and the first element +of the list. +.TP +\fB2\fR +Application of the command to the result of the last call and the +second element of the list. +.TP \fB...\fR +.TP +\fBi\fR +Application of the command to the result of the last call and the +\fBi\fR'th element of the list. +.TP \fB...\fR +.TP +\fBend\fR +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. +.RE +.sp +.CS + + + 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 + +.CE +.TP +\fB::struct::list\fR \fBshift\fR \fIlistvar\fR +The subcommand takes the list contained in the variable named by +\fIlistvar\fR and shifts it down one element. +After the call \fIlistvar\fR 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. +.TP +\fB::struct::list\fR \fBiota\fR \fIn\fR +The subcommand returns a list containing the integer numbers +in the range \fB[0,n)\fR. The element at index \fBi\fR +of the list contain the number \fBi\fR. +.sp +For "\fIn\fR == \fB0\fR" an empty list will be returned. +.TP +\fB::struct::list\fR \fBequal\fR \fIa\fR \fIb\fR +The subcommand compares the two lists \fIa\fR and \fIb\fR 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. +.sp +A boolean value will be returned as the result of the command. +This value will be \fBtrue\fR if the two lists are equal, and +\fBfalse\fR else. +.TP +\fB::struct::list\fR \fBrepeat\fR \fIsize\fR \fIelement1\fR ?\fIelement2\fR \fIelement3\fR...? +The subcommand creates a list of length +"\fIsize\fR * \fInumber of elements\fR" by repeating \fIsize\fR +times the sequence of elements +\fIelement1\fR \fIelement2\fR \fI...\fR. +\fIsize\fR must be a positive integer, \fIelement\fR\fBn\fR can be any +Tcl value. +Note that \fBrepeat 1 arg ...\fR is identical to +\fBlist arg ...\fR, though the \fIarg\fR is required +with \fBrepeat\fR. +.sp +\fIExamples:\fR +.sp +.CS + + + 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 + +.CE +.TP +\fB::struct::list\fR \fBrepeatn\fR \fIvalue\fR \fIsize\fR... +The subcommand creates a (nested) list containing the \fIvalue\fR in +all positions. The exact size and degree of nesting is determined by +the \fIsize\fR arguments, all of which have to be integer numbers +greater than or equal to zero. +.sp +A single argument \fIsize\fR which is a list of more than one element +will be treated as if more than argument \fIsize\fR was specified. +.sp +If only one argument \fIsize\fR is present the returned list will not +be nested, of length \fIsize\fR and contain \fIvalue\fR in all +positions. +If more than one \fIsize\fR argument is present the returned +list will be nested, and of the length specified by the last +\fIsize\fR argument given to it. The elements of that list +are defined as the result of \fBRepeat\fR for the same arguments, +but with the last \fIsize\fR value removed. +.sp +An empty list will be returned if no \fIsize\fR arguments are present. +.sp +.CS + + + 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}} + +.CE +.TP +\fB::struct::list\fR \fBdbJoin\fR ?\fB-inner\fR|\fB-left\fR|\fB-right\fR|\fB-full\fR? ?\fB-keys\fR \fIvarname\fR? {\fIkeycol\fR \fItable\fR}... +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 \fB-left\fR, \fB-right\fR, or +\fB-full\fR. If none of these options is present a regular inner +join will be performed. This can also be triggered by specifying +\fB-inner\fR. The various possible join operations are explained in +detail in section \fBTABLE JOIN\fR. +.sp +If the \fB-keys\fR 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. +.sp +What is left to explain is the format of the arguments. +.sp +The \fIkeycol\fR 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 \fB0\fR, which references the first +column. The table associated with the column index has to have at +least \fIkeycol\fR+1 columns. An error will be thrown if there are +less. +.sp +The \fItable\fR arguments represent a table or matrix of rows and +columns of values. We use the same representation as generated and +consumed by the methods \fBget rect\fR and \fBset rect\fR of +\fBmatrix\fR 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. +.sp +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 \fItable\fRs. +.TP +\fB::struct::list\fR \fBdbJoinKeyed\fR ?\fB-inner\fR|\fB-left\fR|\fB-right\fR|\fB-full\fR? ?\fB-keys\fR \fIvarname\fR? \fItable\fR... +The operations performed by this method are the same as described +above for \fBdbJoin\fR. 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 \fItable\fR 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. +.TP +\fB::struct::list\fR \fBswap\fR \fIlistvar\fR \fIi\fR \fIj\fR +The subcommand exchanges the elements at the indices \fIi\fR and +\fIj\fR in the list stored in the variable named by \fIlistvar\fR. The +list is modified in place, and also returned as the result of the +subcommand. +.TP +\fB::struct::list\fR \fBfirstperm\fR \fIlist\fR +This subcommand returns the lexicographically first permutation of the +input \fIlist\fR. +.TP +\fB::struct::list\fR \fBnextperm\fR \fIperm\fR +This subcommand accepts a permutation of a set of elements (provided +by \fIperm\fR) and returns the next permutatation in lexicographic +sequence. +.sp +The algorithm used here is by Donal E. Knuth, see section +\fBREFERENCES\fR for details. +.TP +\fB::struct::list\fR \fBpermutations\fR \fIlist\fR +This subcommand returns a list containing all permutations of the +input \fIlist\fR in lexicographic order. +.TP +\fB::struct::list\fR \fBforeachperm\fR \fIvar\fR \fIlist\fR \fIbody\fR +This subcommand executes the script \fIbody\fR once for each +permutation of the specified \fIlist\fR. The permutations are visited +in lexicographic order, and the variable \fIvar\fR is set to the +permutation for which \fIbody\fR is currently executed. The result of +the loop command is the empty string. +.PP +.SH "LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON" +.PP +The \fBlongestCommonSubsequence\fR subcommand forms the core of a +flexible system for doing differential comparisons of files, similar +to the capability offered by the Unix command \fBdiff\fR. +While this procedure is quite rapid for many tasks of file comparison, +its performance degrades severely if \fIsequence2\fR 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). +.PP +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 \fImaxOccurs\fR 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 \fBlongestCommonSubsequence2\fR implements this +heuristic. +It functions as a wrapper around \fBlongestCommonSubsequence\fR; 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. +.SH "TABLE JOIN" +This is an operation from relational algebra for relational databases. +.PP +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. +.PP +Implementing this description naively, i.e. as described above will +generate a \fIhuge\fR 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. +.PP +An \fIouter\fR join is an extension of the inner join for two +tables. There are three variants of outerjoins, called \fIleft\fR, +\fIright\fR, and \fIfull\fR outer joins. Their result always +contains all rows from an inner join and then some additional rows. +.IP [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. +.IP [2] +For the right outer join the additional rows are all rows from the right +table for which there is no key in the left table. They are joined to +an empty row of the left table to fit them into the result. +.IP [3] +The full outer join combines both left and right outer join. In other +words, the additional rows are as defined for left outer join, and +right outer join, combined. +.PP +.PP +We extend all the joins from two to \fBn\fR tables (\fBn\fR > 2) by +executing +.CS + + + (...((table1 join table2) join table3) ...) join tableN + +.CE +.PP +Examples for all the joins: +.CS + + + 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} + +.CE +.SH REFERENCES +.IP [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: \fIhttp://www.cs.dartmouth.edu/~doug/\fR +.IP [2] +Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' +volume 4". Available on the Web at the author's personal site: +\fIhttp://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: list\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +Fisher-Yates, assign, common, comparison, diff, differential, equal, equality, filter, first permutation, flatten, folding, full outer join, generate permutations, inner join, join, left outer join, list, longest common subsequence, map, next permutation, outer join, permutation, reduce, repeating, repetition, reshuffle, reverse, right outer join, shuffle, subsequence, swapping +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2003-2005 by Kevin B. Kenny. All rights reserved +Copyright (c) 2003-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/struct_set.n Index: embedded/man/files/modules/struct/struct_set.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/struct_set.n @@ -0,0 +1,382 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/struct_set.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::set" n 2.2.3 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::set \- Procedures for manipulating sets +.SH SYNOPSIS +package require \fBTcl 8.0\fR +.sp +package require \fBstruct::set ?2.2.3?\fR +.sp +\fB::struct::set\fR \fBempty\fR \fIset\fR +.sp +\fB::struct::set\fR \fBsize\fR \fIset\fR +.sp +\fB::struct::set\fR \fBcontains\fR \fIset\fR \fIitem\fR +.sp +\fB::struct::set\fR \fBunion\fR ?\fIset1\fR...? +.sp +\fB::struct::set\fR \fBintersect\fR ?\fIset1\fR...? +.sp +\fB::struct::set\fR \fBdifference\fR \fIset1\fR \fIset2\fR +.sp +\fB::struct::set\fR \fBsymdiff\fR \fIset1\fR \fIset2\fR +.sp +\fB::struct::set\fR \fBintersect3\fR \fIset1\fR \fIset2\fR +.sp +\fB::struct::set\fR \fBequal\fR \fIset1\fR \fIset2\fR +.sp +\fB::struct::set\fR \fBinclude\fR \fIsvar\fR \fIitem\fR +.sp +\fB::struct::set\fR \fBexclude\fR \fIsvar\fR \fIitem\fR +.sp +\fB::struct::set\fR \fBadd\fR \fIsvar\fR \fIset\fR +.sp +\fB::struct::set\fR \fBsubtract\fR \fIsvar\fR \fIset\fR +.sp +\fB::struct::set\fR \fBsubsetof\fR \fIA\fR \fIB\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::set\fR namespace contains several useful commands for +processing finite sets. +.PP +It exports only a single command, \fBstruct::set\fR. All +functionality provided here can be reached through a subcommand of +this command. +.PP +\fINote:\fR As of version 2.2 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run. +.SH COMMANDS +.TP +\fB::struct::set\fR \fBempty\fR \fIset\fR +Returns a boolean value indicating if the \fIset\fR is +empty (\fBtrue\fR), or not (\fBfalse\fR). +.TP +\fB::struct::set\fR \fBsize\fR \fIset\fR +Returns an integer number greater than or equal to zero. This is the +number of elements in the \fIset\fR. In other words, its cardinality. +.TP +\fB::struct::set\fR \fBcontains\fR \fIset\fR \fIitem\fR +Returns a boolean value indicating if the \fIset\fR contains the +element \fIitem\fR (\fBtrue\fR), or not (\fBfalse\fR). +.TP +\fB::struct::set\fR \fBunion\fR ?\fIset1\fR...? +Computes the set containing the union of \fIset1\fR, \fIset2\fR, +etc., i.e. "\fIset1\fR + \fIset2\fR + ...", and returns this set +as the result of the command. +.TP +\fB::struct::set\fR \fBintersect\fR ?\fIset1\fR...? +Computes the set containing the intersection of \fIset1\fR, +\fIset2\fR, etc., i.e. "\fIset1\fR * \fIset2\fR * ...", and +returns this set as the result of the command. +.TP +\fB::struct::set\fR \fBdifference\fR \fIset1\fR \fIset2\fR +Computes the set containing the difference of \fIset1\fR and +\fIset2\fR, i.e. ("\fIset1\fR - \fIset2\fR") and returns this +set as the result of the command. +.TP +\fB::struct::set\fR \fBsymdiff\fR \fIset1\fR \fIset2\fR +Computes the set containing the symmetric difference of \fIset1\fR and +\fIset2\fR, i.e. ("(\fIset1\fR - \fIset2\fR) + (\fIset2\fR - \fIset1\fR)") +and returns this set as the result of the command. +.TP +\fB::struct::set\fR \fBintersect3\fR \fIset1\fR \fIset2\fR +This command is a combination of the methods \fBintersect\fR and +\fBdifference\fR. +It returns a three-element list containing "\fIset1\fR*\fIset2\fR", +"\fIset1\fR-\fIset2\fR", and "\fIset2\fR-\fIset1\fR", in this +order. In other words, the intersection of the two parameter sets, and +their differences. +.TP +\fB::struct::set\fR \fBequal\fR \fIset1\fR \fIset2\fR +Returns a boolean value indicating if the two sets are equal +(\fBtrue\fR) or not (\fBfalse\fR). +.TP +\fB::struct::set\fR \fBinclude\fR \fIsvar\fR \fIitem\fR +The element \fIitem\fR is added to the set specified by the variable +name in \fIsvar\fR. The return value of the command is empty. This is +the equivalent of \fBlappend\fR for sets. If the variable named by +\fIsvar\fR does not exist it will be created. +.TP +\fB::struct::set\fR \fBexclude\fR \fIsvar\fR \fIitem\fR +The element \fIitem\fR is removed from the set specified by the +variable name in \fIsvar\fR. The return value of the command is +empty. This is a near-equivalent of \fBlreplace\fR for sets. +.TP +\fB::struct::set\fR \fBadd\fR \fIsvar\fR \fIset\fR +All the element of \fIset\fR are added to the set specified by the +variable name in \fIsvar\fR. The return value of the command is +empty. This is like the method \fBinclude\fR, but for the addition +of a whole set. If the variable named by \fIsvar\fR does not exist it +will be created. +.TP +\fB::struct::set\fR \fBsubtract\fR \fIsvar\fR \fIset\fR +All the element of \fIset\fR are removed from the set specified by the +variable name in \fIsvar\fR. The return value of the command is +empty. This is like the method \fBexclude\fR, but for the removal +of a whole set. +.TP +\fB::struct::set\fR \fBsubsetof\fR \fIA\fR \fIB\fR +Returns a boolean value indicating if the set \fIA\fR is a true +subset of or equal to the set \fIB\fR (\fBtrue\fR), or not +(\fBfalse\fR). +.PP +.SH REFERENCES +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: set\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +cardinality, difference, emptiness, exclusion, inclusion, intersection, membership, set, symmetric difference, union +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/struct_tree.n Index: embedded/man/files/modules/struct/struct_tree.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/struct_tree.n @@ -0,0 +1,978 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/struct_tree.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002-2004,2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::tree" n 2.1.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::tree \- Create and manipulate tree objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::tree ?2.1.1?\fR +.sp +package require \fBstruct::list ?1.5?\fR +.sp +\fB::struct::tree\fR ?\fItreeName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +.sp +\fBtreeName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fB::struct::tree::prune\fR +.sp +\fItreeName\fR \fB=\fR \fIsourcetree\fR +.sp +\fItreeName\fR \fB-->\fR \fIdesttree\fR +.sp +\fItreeName\fR \fBancestors\fR \fInode\fR +.sp +\fItreeName\fR \fBappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +.sp +\fItreeName\fR \fBattr\fR \fIkey\fR +.sp +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-nodes\fR \fIlist\fR +.sp +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.sp +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +.sp +\fItreeName\fR \fBchildren\fR ?\fB-all\fR? \fInode\fR ?\fBfilter\fR \fIcmdprefix\fR? +.sp +\fItreeName\fR \fBcut\fR \fInode\fR +.sp +\fItreeName\fR \fBdelete\fR \fInode\fR ?\fInode\fR ...? +.sp +\fItreeName\fR \fBdepth\fR \fInode\fR +.sp +\fItreeName\fR \fBdescendants\fR \fInode\fR ?\fBfilter\fR \fIcmdprefix\fR? +.sp +\fItreeName\fR \fBdeserialize\fR \fIserialization\fR +.sp +\fItreeName\fR \fBdestroy\fR +.sp +\fItreeName\fR \fBexists\fR \fInode\fR +.sp +\fItreeName\fR \fBget\fR \fInode\fR \fIkey\fR +.sp +\fItreeName\fR \fBgetall\fR \fInode\fR ?\fIpattern\fR? +.sp +\fItreeName\fR \fBkeys\fR \fInode\fR ?\fIpattern\fR? +.sp +\fItreeName\fR \fBkeyexists\fR \fInode\fR \fIkey\fR +.sp +\fItreeName\fR \fBindex\fR \fInode\fR +.sp +\fItreeName\fR \fBinsert\fR \fIparent\fR \fIindex\fR ?\fIchild\fR ?\fIchild\fR ...?? +.sp +\fItreeName\fR \fBisleaf\fR \fInode\fR +.sp +\fItreeName\fR \fBlappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +.sp +\fItreeName\fR \fBleaves\fR +.sp +\fItreeName\fR \fBmove\fR \fIparent\fR \fIindex\fR \fInode\fR ?\fInode\fR ...? +.sp +\fItreeName\fR \fBnext\fR \fInode\fR +.sp +\fItreeName\fR \fBnumchildren\fR \fInode\fR +.sp +\fItreeName\fR \fBnodes\fR +.sp +\fItreeName\fR \fBparent\fR \fInode\fR +.sp +\fItreeName\fR \fBprevious\fR \fInode\fR +.sp +\fItreeName\fR \fBrename\fR \fInode\fR \fInewname\fR +.sp +\fItreeName\fR \fBrootname\fR +.sp +\fItreeName\fR \fBserialize\fR ?\fInode\fR? +.sp +\fItreeName\fR \fBset\fR \fInode\fR \fIkey\fR ?\fIvalue\fR? +.sp +\fItreeName\fR \fBsize\fR ?\fInode\fR? +.sp +\fItreeName\fR \fBsplice\fR \fIparent\fR \fIfrom\fR ?\fIto\fR? ?\fIchild\fR? +.sp +\fItreeName\fR \fBswap\fR \fInode1\fR \fInode2\fR +.sp +\fItreeName\fR \fBunset\fR \fInode\fR \fIkey\fR +.sp +\fItreeName\fR \fBwalk\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fIloopvar\fR \fIscript\fR +.sp +\fItreeName\fR \fBwalkproc\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fIcmdprefix\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +The element names can be arbitrary strings. +.PP +A tree is thus similar to an array, but with three important +differences: +.IP [1] +Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.) +.IP [2] +Trees have a hierarchical structure, whereas an array is just an +unordered collection. +.IP [3] +Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary. +.PP +.PP +\fINote:\fR The major version of the package \fBstruct\fR has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +\fBChanges for 2.0\fR for a full list of all changes, +incompatible and otherwise. +.PP +.SH API +.SS "TREE CLASS API" +The main commands of the package are: +.TP +\fB::struct::tree\fR ?\fItreeName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? +The command creates a new tree object with an associated global Tcl +command whose name is \fItreeName\fR. This command may be used to +invoke various operations on the tree. +It has the following general form: +.RS +.TP +\fBtreeName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.sp +If \fItreeName\fR is not specified a unique name will be generated by +the package itself. If a \fIsource\fR is specified the new tree will +be initialized to it. For the operators \fB=\fR, \fB:=\fR, and +\fBas\fR \fIsource\fR is interpreted as the name of another tree +object, and the assignment operator \fB=\fR will be executed. For +\fBdeserialize\fR the \fIsource\fR is a serialized tree object and +\fBdeserialize\fR will be executed. +.sp +In other words +.sp +.CS + + + ::struct::tree mytree = b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::tree mytree + mytree = b + +.CE +.sp +and +.sp +.CS + + + ::struct::tree mytree deserialize $b + +.CE +.sp +is equivalent to +.sp +.CS + + + ::struct::tree mytree + mytree deserialize $b + +.CE +.TP +\fB::struct::tree::prune\fR +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 +\fBwalk\fR. 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. \fBpost\fR and \fBin\fR. The +only applicable orders of traversal are \fBpre\fR and +\fBboth\fR. An error is thrown if the command and chosen order of +traversal do not fit. +.PP +.PP +.SS "TREE OBJECT API" +Two general observations beforehand: +.IP [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 \fBrename\fR (see below). Whatever the +current name for the root node of the tree is, it can be retrieved by +calling the method \fBrootname\fR. +.IP [2] +The method \fBinsert\fR 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. +.PP +.PP +And now the methods supported by tree objects created by this package: +.TP +\fItreeName\fR \fB=\fR \fIsourcetree\fR +This is the assignment operator for tree objects. It copies the tree +contained in the tree object \fIsourcetree\fR over the tree data in +\fItreeName\fR. The old contents of \fItreeName\fR are deleted by this +operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fItreeName\fR \fBdeserialize\fR [\fIsourcetree\fR \fBserialize\fR] + +.CE +.TP +\fItreeName\fR \fB-->\fR \fIdesttree\fR +This is the reverse assignment operator for tree objects. It copies the tree +contained in the tree object \fItreeName\fR over the tree data in the object +\fIdesttree\fR. The old contents of \fIdesttree\fR are deleted by this +operation. +.sp +This operation is in effect equivalent to +.sp +.CS + + + \fIdesttree\fR \fBdeserialize\fR [\fItreeName\fR \fBserialize\fR] + +.CE +.TP +\fItreeName\fR \fBancestors\fR \fInode\fR +This method extends the method \fBparent\fR and returns a list +containing all ancestor nodes to the specified \fInode\fR. 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. +.TP +\fItreeName\fR \fBappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +node. Returns the new value given to the attribute \fIkey\fR. +.TP +\fItreeName\fR \fBattr\fR \fIkey\fR +.TP +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-nodes\fR \fIlist\fR +.TP +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-glob\fR \fIglobpattern\fR +.TP +\fItreeName\fR \fBattr\fR \fIkey\fR \fB-regexp\fR \fIrepattern\fR +This method retrieves the value of the attribute named \fIkey\fR, for +all nodes in the tree (matching the restriction specified via one of +the possible options) and having the specified attribute. +.sp +The result is a dictionary mapping from node names to the value of +attribute \fIkey\fR at that node. +Nodes not having the attribute \fIkey\fR, or not passing a +specified restriction, are not listed in the result. +.sp +The possible restrictions are: +.RS +.TP +\fB-nodes\fR +The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute. +.TP +\fB-glob\fR +The value is a glob pattern. Only the nodes in the tree whose names +match this pattern are searched for the attribute. +.TP +\fB-regexp\fR +The value is a regular expression. Only the nodes in the tree whose +names match this pattern are searched for the attribute. +.RE +.sp +.TP +\fItreeName\fR \fBchildren\fR ?\fB-all\fR? \fInode\fR ?\fBfilter\fR \fIcmdprefix\fR? +Return a list of the children of \fInode\fR. +If the option \fB-all\fR 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 \fIcmdprefix\fR 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 +\fBfalse\fR are removed from the result list before it is returned +to the caller. +.sp +Some examples: +.sp +.CS + + + 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]]) + () + +.CE +.TP +\fItreeName\fR \fBcut\fR \fInode\fR +Removes the node specified by \fInode\fR from the tree, but not its +children. The children of \fInode\fR are made children of the parent +of the \fInode\fR, at the index at which \fInode\fR was located. +.TP +\fItreeName\fR \fBdelete\fR \fInode\fR ?\fInode\fR ...? +Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes. +.TP +\fItreeName\fR \fBdepth\fR \fInode\fR +Return the number of steps from node \fInode\fR to the root node. +.TP +\fItreeName\fR \fBdescendants\fR \fInode\fR ?\fBfilter\fR \fIcmdprefix\fR? +This method extends the method \fBchildren\fR and returns a list +containing all nodes descending from \fInode\fR, and passing the +filter, if such was specified. +.sp +This is actually the same as +"\fItreeName\fR \fBchildren\fR \fB-all\fR". +\fBdescendants\fR should be prefered, and "children -all" +will be deprecated sometime in the future. +.TP +\fItreeName\fR \fBdeserialize\fR \fIserialization\fR +This is the complement to \fBserialize\fR. It replaces tree data in +\fItreeName\fR with the tree described by the \fIserialization\fR +value. The old contents of \fItreeName\fR are deleted by this +operation. +.TP +\fItreeName\fR \fBdestroy\fR +Destroy the tree, including its storage space and associated command. +.TP +\fItreeName\fR \fBexists\fR \fInode\fR +Returns true if the specified node exists in the tree. +.TP +\fItreeName\fR \fBget\fR \fInode\fR \fIkey\fR +Returns the value associated with the key \fIkey\fR for the node +\fInode\fR. +.TP +\fItreeName\fR \fBgetall\fR \fInode\fR ?\fIpattern\fR? +Returns a dictionary (suitable for use with [\fBarray set\fR]) +containing the attribute data for the \fInode\fR. +If the glob \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the dictionary. +.TP +\fItreeName\fR \fBkeys\fR \fInode\fR ?\fIpattern\fR? +Returns a list of keys for the \fInode\fR. +If the \fIpattern\fR is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +\fBglob\fR pattern. +.TP +\fItreeName\fR \fBkeyexists\fR \fInode\fR \fIkey\fR +Return true if the specified \fIkey\fR exists for the \fInode\fR. +.TP +\fItreeName\fR \fBindex\fR \fInode\fR +Returns the index of \fInode\fR in its parent's list of children. For +example, if a node has \fInodeFoo\fR, \fInodeBar\fR, and +\fInodeBaz\fR as children, in that order, the index of +\fInodeBar\fR is 1. +.TP +\fItreeName\fR \fBinsert\fR \fIparent\fR \fIindex\fR ?\fIchild\fR ?\fIchild\fR ...?? +Insert one or more nodes into the tree as children of the node +\fIparent\fR. The nodes will be added in the order they are given. If +\fIparent\fR is \fBroot\fR, it refers to the root of the tree. The +new nodes will be added to the \fIparent\fR node's child list at the +index given by \fIindex\fR. The \fIindex\fR can be \fBend\fR in +which case the new nodes will be added after the current last child. +Indices of the form "end-\fBn\fR" are accepted as well. +.sp +If any of the specified children already exist in \fItreeName\fR, +those nodes will be moved from their original location to the new +location indicated by this command. +.sp +If no \fIchild\fR 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 \fInode\fR\fBx\fR, where \fBx\fR is a number. If names are +specified they must neither contain whitespace nor colons (":"). +.sp +The return result from this command is a list of nodes added. +.TP +\fItreeName\fR \fBisleaf\fR \fInode\fR +Returns true if \fInode\fR is a leaf of the tree (if \fInode\fR has no +children), false otherwise. +.TP +\fItreeName\fR \fBlappend\fR \fInode\fR \fIkey\fR \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fInode\fR. Returns the new value given to the +attribute \fIkey\fR. +.TP +\fItreeName\fR \fBleaves\fR +Return a list containing all leaf nodes known to the tree. +.TP +\fItreeName\fR \fBmove\fR \fIparent\fR \fIindex\fR \fInode\fR ?\fInode\fR ...? +Make the specified nodes children of \fIparent\fR, inserting them into +the parent's child list at the index given by \fIindex\fR. 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. +.TP +\fItreeName\fR \fBnext\fR \fInode\fR +Return the right sibling of \fInode\fR, or the empty string if +\fInode\fR was the last child of its parent. +.TP +\fItreeName\fR \fBnumchildren\fR \fInode\fR +Return the number of immediate children of \fInode\fR. +.TP +\fItreeName\fR \fBnodes\fR +Return a list containing all nodes known to the tree. +.TP +\fItreeName\fR \fBparent\fR \fInode\fR +Return the parent of \fInode\fR. +.TP +\fItreeName\fR \fBprevious\fR \fInode\fR +Return the left sibling of \fInode\fR, or the empty string if +\fInode\fR was the first child of its parent. +.TP +\fItreeName\fR \fBrename\fR \fInode\fR \fInewname\fR +Renames the node \fInode\fR to \fInewname\fR. An error is thrown if +either the node does not exist, or a node with name \fInewname\fR does +exist. The result of the command is the new name of the node. +.TP +\fItreeName\fR \fBrootname\fR +Returns the name of the root node of the tree. +.TP +\fItreeName\fR \fBserialize\fR ?\fInode\fR? +This method serializes the sub-tree starting at \fInode\fR. In other +words it returns a tcl \fIvalue\fR completely describing the tree +starting at \fInode\fR. +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. +.sp +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. +.sp +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. +.sp +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. +.sp +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. +.sp +\fINote:\fR 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. +.sp +.CS + + + 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. + +.CE +.TP +\fItreeName\fR \fBset\fR \fInode\fR \fIkey\fR ?\fIvalue\fR? +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 \fIvalue\fR is +not specified, this command returns the current value assigned to the +key; if \fIvalue\fR is specified, this command assigns that value to +the key, and returns it. +.TP +\fItreeName\fR \fBsize\fR ?\fInode\fR? +Return a count of the number of descendants of the node \fInode\fR; if +no node is specified, \fBroot\fR is assumed. +.TP +\fItreeName\fR \fBsplice\fR \fIparent\fR \fIfrom\fR ?\fIto\fR? ?\fIchild\fR? +Insert a node named \fIchild\fR into the tree as a child of the node +\fIparent\fR. If \fIparent\fR is \fBroot\fR, 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 \fIfrom\fR. The children of \fIparent\fR +which are in the range of the indices \fIfrom\fR and \fIto\fR are made +children of \fIchild\fR. If the value of \fIto\fR is not specified it +defaults to \fBend\fR. If no name is given for \fIchild\fR, a name +will be generated for the new node. The generated name is of the form +\fInode\fR\fBx\fR, where \fBx\fR is a number. The return result +from this command is the name of the new node. +.sp +The arguments \fIfrom\fR and \fIto\fR are regular list indices, i.e. +the form "end-\fBn\fR" is accepted as well. +.TP +\fItreeName\fR \fBswap\fR \fInode1\fR \fInode2\fR +Swap the position of \fInode1\fR and \fInode2\fR in the tree. +.TP +\fItreeName\fR \fBunset\fR \fInode\fR \fIkey\fR +Removes a keyed value from the node \fInode\fR. The method will do +nothing if the \fIkey\fR does not exist. +.TP +\fItreeName\fR \fBwalk\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fIloopvar\fR \fIscript\fR +Perform a breadth-first or depth-first walk of the tree starting at +the node \fInode\fR. The type of walk, breadth-first or depth-first, +is determined by the value of \fItype\fR; \fBbfs\fR indicates +breadth-first, \fBdfs\fR 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 \fIorder\fR; \fBpre\fR indicates +pre-order, \fBpost\fR indicates post-order, \fBboth\fR indicates +both-order and \fBin\fR indicates in-order. Pre-order is the +default. +.sp +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 \fIand\fR 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. +.sp +As the walk progresses, the \fIscript\fR 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 \fIloopvar\fR. If one +only one variable is specified it will be set to the id of the +node. When two variables are specified, i.e. \fIloopvar\fR 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. +.sp +There are three possible actions: \fBenter\fR, \fBleave\fR, +or \fBvisit\fR. \fBenter\fR actions occur during pre-order +walks; \fBleave\fR actions occur during post-order walks; +\fBvisit\fR actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +\fBenter\fR for the first evaluation, and \fBleave\fR for the +second. +.sp +\fINote\fR: The \fBenter\fR 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 \fIscript\fR to the children of the node +will immediately influence the walker and the steps it will take. +.sp +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. +.sp +At last a small table showing the relationship between the various +options and the possible actions. +.sp +.CS + + + 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 + ----- ---- ----- ----- + +.CE +.sp +Note the command \fB::struct::tree::prune\fR. 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 \fBpost\fR or \fBin\fR as these modes visit +the children before their parent, making pruning non-sensical. +.TP +\fItreeName\fR \fBwalkproc\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fIcmdprefix\fR +This method is like method \fBwalk\fR 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. +.PP +.SS "CHANGES FOR 2.0" +The following noteworthy changes have occurred: +.IP [1] +The API for accessing attributes and their values has been +simplified. +.sp +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 \fIincompatible\fR change allowed us to +simplify the signature of all methods handling attributes. +.sp +Especially the flag \fB-key\fR is not required anymore, even more, +its use is now forbidden. Please read the documentation for the +methods \fBset\fR, \fBget\fR, \fBgetall\fR, \fBunset\fR, +\fBappend\fR, \fBlappend\fR, \fBkeyexists\fR +and \fBkeys\fR for a description of the new API's. +.IP [2] +The methods \fBkeys\fR and \fBgetall\fR now take an optional +pattern argument and will return only attribute data for keys matching +this pattern. +.IP [3] +Nodes can now be renamed. See the documentation for the method +\fBrename\fR. +.IP [4] +The structure has been extended with API's for the serialization and +deserialization of tree objects, and a number of operations based on +them (tree assignment, copy construction). +.sp +Please read the documentation for the methods \fBserialize\fR, +\fBdeserialize\fR, \fB=\fR, and \fB-->\fR, and the +documentation on the construction of tree objects. +.sp +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. +.IP [5] +The walker API has been streamlined and made more similar to the +command \fBforeach\fR. In detail: +.RS +.IP \(bu +The superfluous option \fB-command\fR has been removed. +.IP \(bu +Ditto for the place holders. Instead of the placeholders two loop +variables have to be specified to contain node and action information. +.IP \(bu +The old command argument has been documented as a script now, which it +was in the past too. +.IP \(bu +The fact that \fBenter\fR 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 \fIthese\fR 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. +.RE +.IP [6] +A new method, \fBattr\fR, was added allowing the query and +retrieval of attribute data without regard to the node relationship. +.IP [7] +The method \fBchildren\fR 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. +.PP +.SH EXAMPLES +The following example demonstrates the creation of new nodes: +.CS + + + 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. + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: tree\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +breadth-first, depth-first, in-order, node, post-order, pre-order, serialization, tree +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002-2004,2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/struct/struct_tree1.n Index: embedded/man/files/modules/struct/struct_tree1.n ================================================================== --- /dev/null +++ embedded/man/files/modules/struct/struct_tree1.n @@ -0,0 +1,534 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/struct/struct_tree1.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "struct::tree_v1" n 1.2.2 tcllib "Tcl Data Structures" +.BS +.SH NAME +struct::tree_v1 \- Create and manipulate tree objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBstruct::tree ?1.2.2?\fR +.sp +\fBtreeName\fR \fBoption\fR ?\fIarg arg ...\fR? +.sp +\fItreeName\fR \fBappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fItreeName\fR \fBchildren\fR \fInode\fR +.sp +\fItreeName\fR \fBcut\fR \fInode\fR +.sp +\fItreeName\fR \fBdelete\fR \fInode\fR ?\fInode\fR ...? +.sp +\fItreeName\fR \fBdepth\fR \fInode\fR +.sp +\fItreeName\fR \fBdestroy\fR +.sp +\fItreeName\fR \fBexists\fR \fInode\fR +.sp +\fItreeName\fR \fBget\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +.sp +\fItreeName\fR \fBgetall\fR \fInode\fR +.sp +\fItreeName\fR \fBkeys\fR \fInode\fR +.sp +\fItreeName\fR \fBkeyexists\fR \fInode\fR ?-key \fIkey\fR? +.sp +\fItreeName\fR \fBindex\fR \fInode\fR +.sp +\fItreeName\fR \fBinsert\fR \fIparent\fR \fIindex\fR ?\fIchild\fR ?\fIchild\fR ...?? +.sp +\fItreeName\fR \fBisleaf\fR \fInode\fR +.sp +\fItreeName\fR \fBlappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +.sp +\fItreeName\fR \fBmove\fR \fIparent\fR \fIindex\fR \fInode\fR ?\fInode\fR ...? +.sp +\fItreeName\fR \fBnext\fR \fInode\fR +.sp +\fItreeName\fR \fBnumchildren\fR \fInode\fR +.sp +\fItreeName\fR \fBparent\fR \fInode\fR +.sp +\fItreeName\fR \fBprevious\fR \fInode\fR +.sp +\fItreeName\fR \fBset\fR \fInode\fR ?\fB-key\fR \fIkey\fR? ?\fIvalue\fR? +.sp +\fItreeName\fR \fBsize\fR ?\fInode\fR? +.sp +\fItreeName\fR \fBsplice\fR \fIparent\fR \fIfrom\fR ?\fIto\fR? ?\fIchild\fR? +.sp +\fItreeName\fR \fBswap\fR \fInode1\fR \fInode2\fR +.sp +\fItreeName\fR \fBunset\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +.sp +\fItreeName\fR \fBwalk\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fB-command\fR \fIcmd\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fB::struct::tree\fR command creates a new tree object with an +associated global Tcl command whose name is \fItreeName\fR. This +command may be used to invoke various operations on the tree. It has +the following general form: +.TP +\fBtreeName\fR \fBoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +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. +.PP +The element names can be arbitrary strings. +.PP +A tree is thus similar to an array, but with three important +differences: +.IP [1] +Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.) +.IP [2] +Trees have a hierarchical structure, whereas an array is just an +unordered collection. +.IP [3] +Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary. +.PP +.PP +The following commands are possible for tree objects: +.TP +\fItreeName\fR \fBappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR to one of the keyed values associated with an +node. If no \fIkey\fR is specified, the key \fBdata\fR is assumed. +.TP +\fItreeName\fR \fBchildren\fR \fInode\fR +Return a list of the children of \fInode\fR. +.TP +\fItreeName\fR \fBcut\fR \fInode\fR +Removes the node specified by \fInode\fR from the tree, but not its +children. The children of \fInode\fR are made children of the parent +of the \fInode\fR, at the index at which \fInode\fR was located. +.TP +\fItreeName\fR \fBdelete\fR \fInode\fR ?\fInode\fR ...? +Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes. +.TP +\fItreeName\fR \fBdepth\fR \fInode\fR +Return the number of steps from node \fInode\fR to the root node. +.TP +\fItreeName\fR \fBdestroy\fR +Destroy the tree, including its storage space and associated command. +.TP +\fItreeName\fR \fBexists\fR \fInode\fR +Returns true if the specified node exists in the tree. +.TP +\fItreeName\fR \fBget\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +Return the value associated with the key \fIkey\fR for the node +\fInode\fR. If no key is specified, the key \fBdata\fR is assumed. +.TP +\fItreeName\fR \fBgetall\fR \fInode\fR +Returns a serialized list of key/value pairs (suitable for use with +[\fBarray set\fR]) for the \fInode\fR. +.TP +\fItreeName\fR \fBkeys\fR \fInode\fR +Returns a list of keys for the \fInode\fR. +.TP +\fItreeName\fR \fBkeyexists\fR \fInode\fR ?-key \fIkey\fR? +Return true if the specified \fIkey\fR exists for the \fInode\fR. If +no \fIkey\fR is specified, the key \fBdata\fR is assumed. +.TP +\fItreeName\fR \fBindex\fR \fInode\fR +Returns the index of \fInode\fR in its parent's list of children. For +example, if a node has \fInodeFoo\fR, \fInodeBar\fR, and +\fInodeBaz\fR as children, in that order, the index of +\fInodeBar\fR is 1. +.TP +\fItreeName\fR \fBinsert\fR \fIparent\fR \fIindex\fR ?\fIchild\fR ?\fIchild\fR ...?? +Insert one or more nodes into the tree as children of the node +\fIparent\fR. The nodes will be added in the order they are given. If +\fIparent\fR is \fBroot\fR, it refers to the root of the tree. The +new nodes will be added to the \fIparent\fR node's child list at the +index given by \fIindex\fR. The \fIindex\fR can be \fBend\fR in +which case the new nodes will be added after the current last child. +.sp +If any of the specified children already exist in \fItreeName\fR, +those nodes will be moved from their original location to the new +location indicated by this command. +.sp +If no \fIchild\fR 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 \fInode\fR\fBx\fR, where \fBx\fR is a number. If names are +specified they must neither contain whitespace nor colons (":"). +.sp +The return result from this command is a list of nodes added. +.TP +\fItreeName\fR \fBisleaf\fR \fInode\fR +Returns true if \fInode\fR is a leaf of the tree (if \fInode\fR has no +children), false otherwise. +.TP +\fItreeName\fR \fBlappend\fR \fInode\fR ?-key \fIkey\fR? \fIvalue\fR +Appends a \fIvalue\fR (as a list) to one of the keyed values +associated with an \fInode\fR. If no \fIkey\fR is specified, the key +\fBdata\fR is assumed. +.TP +\fItreeName\fR \fBmove\fR \fIparent\fR \fIindex\fR \fInode\fR ?\fInode\fR ...? +Make the specified nodes children of \fIparent\fR, inserting them into +the parent's child list at the index given by \fIindex\fR. 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. +.TP +\fItreeName\fR \fBnext\fR \fInode\fR +Return the right sibling of \fInode\fR, or the empty string if +\fInode\fR was the last child of its parent. +.TP +\fItreeName\fR \fBnumchildren\fR \fInode\fR +Return the number of immediate children of \fInode\fR. +.TP +\fItreeName\fR \fBparent\fR \fInode\fR +Return the parent of \fInode\fR. +.TP +\fItreeName\fR \fBprevious\fR \fInode\fR +Return the left sibling of \fInode\fR, or the empty string if +\fInode\fR was the first child of its parent. +.TP +\fItreeName\fR \fBset\fR \fInode\fR ?\fB-key\fR \fIkey\fR? ?\fIvalue\fR? +Set or get one of the keyed values associated with a node. If no key +is specified, the key \fBdata\fR is assumed. Each node that is +added to a tree has the value "" assigned to the key \fBdata\fR +automatically. A node may have any number of keyed values associated +with it. If \fIvalue\fR is not specified, this command returns the +current value assigned to the key; if \fIvalue\fR is specified, this +command assigns that value to the key. +.TP +\fItreeName\fR \fBsize\fR ?\fInode\fR? +Return a count of the number of descendants of the node \fInode\fR; if +no node is specified, \fBroot\fR is assumed. +.TP +\fItreeName\fR \fBsplice\fR \fIparent\fR \fIfrom\fR ?\fIto\fR? ?\fIchild\fR? +Insert a node named \fIchild\fR into the tree as a child of the node +\fIparent\fR. If \fIparent\fR is \fBroot\fR, 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 \fIfrom\fR. The children of \fIparent\fR +which are in the range of the indices \fIfrom\fR and \fIto\fR are made +children of \fIchild\fR. If the value of \fIto\fR is not specified it +defaults to \fBend\fR. If no name is given for \fIchild\fR, a name +will be generated for the new node. The generated name is of the form +\fInode\fR\fBx\fR, where \fBx\fR is a number. The return result +from this command is the name of the new node. +.TP +\fItreeName\fR \fBswap\fR \fInode1\fR \fInode2\fR +Swap the position of \fInode1\fR and \fInode2\fR in the tree. +.TP +\fItreeName\fR \fBunset\fR \fInode\fR ?\fB-key\fR \fIkey\fR? +Removes a keyed value from the node \fInode\fR. If no key is +specified, the key \fBdata\fR is assumed. +.TP +\fItreeName\fR \fBwalk\fR \fInode\fR ?\fB-order\fR \fIorder\fR? ?\fB-type\fR \fItype\fR? \fB-command\fR \fIcmd\fR +Perform a breadth-first or depth-first walk of the tree starting at +the node \fInode\fR. The type of walk, breadth-first or depth-first, +is determined by the value of \fItype\fR; \fBbfs\fR indicates +breadth-first, \fBdfs\fR 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 \fIorder\fR; \fBpre\fR indicates +pre-order, \fBpost\fR indicates post-order, \fBboth\fR indicates +both-order and \fBin\fR indicates in-order. Pre-order is the +default. +.sp +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 \fIand\fR 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. +.sp +As the walk progresses, the command \fIcmd\fR will be evaluated at +each node. Percent substitution will be performed on \fIcmd\fR before +evaluation, just as in a \fBbind\fR script. The following +substitutions are recognized: +.RS +.TP +\fB%%\fR +Insert the literal % character. +.TP +\fB%t\fR +Name of the tree object. +.TP +\fB%n\fR +Name of the current node. +.TP +\fB%a\fR +Name of the action occurring; one of \fBenter\fR, \fBleave\fR, +or \fBvisit\fR. \fBenter\fR actions occur during pre-order +walks; \fBleave\fR actions occur during post-order walks; +\fBvisit\fR actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +\fBenter\fR for the first evaluation, and \fBleave\fR for the +second. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIstruct :: tree\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +tree +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/tar/tar.n Index: embedded/man/files/modules/tar/tar.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tar/tar.n @@ -0,0 +1,423 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tar/tar.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tar" n 0.7 tcllib "Tar file handling" +.BS +.SH NAME +tar \- Tar file creation, extraction & manipulation +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBtar ?0.7?\fR +.sp +\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR? +.sp +\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR? +.sp +\fB::tar::untar\fR \fItarball\fR \fIargs\fR +.sp +\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR? +.sp +\fB::tar::create\fR \fItarball\fR \fIfiles\fR \fIargs\fR +.sp +\fB::tar::add\fR \fItarball\fR \fIfiles\fR \fIargs\fR +.sp +\fB::tar::remove\fR \fItarball\fR \fIfiles\fR +.sp +.BE +.SH DESCRIPTION +.PP +.TP +\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR? +Returns a list of the files contained in \fItarball\fR. The order is not sorted and depends on the order +files were stored in the archive. +.sp +If the option \fB-chan\fR is present \fItarball\fR is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will \fInot\fR close the channel. +.TP +\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR? +Returns a nested dict containing information on the named ?file? in \fItarball\fR, +or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys +"\fBmode\fR \fBuid\fR \fBgid\fR \fBsize\fR \fBmtime\fR \fBtype\fR \fBlinkname\fR \fBuname\fR \fBgname\fR +\fBdevmajor\fR \fBdevminor\fR" +.CS + + +% ::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} + +.CE +.sp +If the option \fB-chan\fR is present \fItarball\fR is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will \fInot\fR close the channel. +.TP +\fB::tar::untar\fR \fItarball\fR \fIargs\fR +Extracts \fItarball\fR. \fI-file\fR and \fI-glob\fR 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. +.RS +.TP +\fB-dir\fR dirName +Directory to extract to. Uses \fBpwd\fR if none is specified +.TP +\fB-file\fR fileName +Only extract the file with this name. The name is matched against the complete path +stored in the archive including directories. +.TP +\fB-glob\fR pattern +Only extract files patching this glob style pattern. The pattern is matched against the complete path +stored in the archive. +.TP +\fB-nooverwrite\fR +Dont overwrite files that already exist +.TP +\fB-nomtime\fR +Leave the file modification time as the current time instead of setting it to the value in the archive. +.TP +\fB-noperms\fR +In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive. +.TP +\fB-chan\fR +If this option is present \fItarball\fR is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will \fInot\fR close the channel. +.RE +.sp +.CS + + +% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] { +puts "Extracted $file ($size bytes)" +} + +.CE +.TP +\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR? +Returns the contents of \fIfileName\fR from the \fItarball\fR +.sp +.CS + + +% set readme [::tar::get tarball.tar doc/README] { +% puts $readme +} + +.CE +.sp +If the option \fB-chan\fR is present \fItarball\fR is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will \fInot\fR close the channel. +.TP +\fB::tar::create\fR \fItarball\fR \fIfiles\fR \fIargs\fR +Creates a new tar file containing the \fIfiles\fR. \fIfiles\fR must be specified +as a single argument which is a proper list of filenames. +.RS +.TP +\fB-dereference\fR +Normally \fBcreate\fR 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. +.TP +\fB-chan\fR +If this option is present \fItarball\fR is interpreted as an open channel. +It is assumed that the channel was opened for writing, and configured for binary output. +The command will \fInot\fR close the channel. +.RE +.sp +.CS + + +% ::tar::create new.tar [glob -nocomplain file*] +% ::tar::contents new.tar +file1 file2 file3 + +.CE +.TP +\fB::tar::add\fR \fItarball\fR \fIfiles\fR \fIargs\fR +Appends \fIfiles\fR to the end of the existing \fItarball\fR. \fIfiles\fR must be specified +as a single argument which is a proper list of filenames. +.RS +.TP +\fB-dereference\fR +Normally \fBadd\fR 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. +.TP +\fB-prefix\fR string +Normally \fBadd\fR will store files under exactly the name specified as +argument. Specifying a ?-prefix? causes the \fIstring\fR to be +prepended to every name. +.TP +\fB-quick\fR +The only sure way to find the position in the \fItarball\fR where new +files can be added is to read it from start, but if \fItarball\fR 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 \fBadd\fR to do the latter. +.RE +.sp +.TP +\fB::tar::remove\fR \fItarball\fR \fIfiles\fR +Removes \fIfiles\fR from the \fItarball\fR. 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. +.CS + + +% ::tar::remove new.tar {file2 file3} +% ::tar::contents new.tar +file3 + +.CE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItar\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +archive, tape archive, tar +.SH CATEGORY +File formats ADDED embedded/man/files/modules/tepam/tepam_argument_dialogbox.n Index: embedded/man/files/modules/tepam/tepam_argument_dialogbox.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tepam/tepam_argument_dialogbox.n @@ -0,0 +1,871 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tepam/tepam_argument_dialogbox.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009/2010, Andreas Drollinger +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tepam::argument_dialogbox" n 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager" +.BS +.SH NAME +tepam::argument_dialogbox \- TEPAM argument_dialogbox, reference manual +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBTk 8.3\fR +.sp +package require \fBtepam ?0.4?\fR +.sp +\fBtepam::argument_dialogbox\fR \fIitem_name item_attributes ?item_name item_attributes? ?...?\fR +.sp +\fBtepam::argument_dialogbox\fR {\fIitem_name item_attributes ?item_name item_attributes? ?...?\fR} +.sp +.BE +.SH DESCRIPTION +.SH "ARGUMENT DIALOGBOX CALL" +TEPAM's \fBargument_dialogbox\fR is a flexible and easily usable data entry form generator. Each data entry element of a form is defined via a \fIdata entry item\fR that can be provided to \fBargument_dialogbox\fR in two formats: +.TP +\fBtepam::argument_dialogbox\fR \fIitem_name item_attributes ?item_name item_attributes? ?...?\fR +Using this first format, each \fIdata entry item\fR is defined via a pair of two arguments. The first one is the \fIitem name\fR that defines the entry widget that has to be used in the form. The second argument, called \fIitem attributes\fR, specifies the variable which is attributed to the data entry element as well as eventual formatting and context information. +.sp +The \fBargument_dialogbox\fR returns \fBok\fR if the entered data have been acknowledged (via the \fIOK\fR button) and validated by a data checker. If the entered data have been rejected (via the \fICancel\fR button) the \fBargument_dialogbox\fR returns \fBcancel\fR. +.sp +A small example illustrates how the \fBargument_dialogbox\fR can be employed: +.CS + +set DialogResult [\fBtepam::argument_dialogbox\fR \\ + \fB-title\fR "Itinerary selection" \\ + \fB-file\fR {\fI-label "Itinerary report" -variable report_file\fR} \\ + \fB-frame\fR {\fI-label "Itinerary start"\fR} \\ + \fB-comment\fR {\fI-text "Specify your itinerary start location"\fR} \\ + \fB-entry\fR {\fI-label "City" -variable start_city -type string\fR} \\ + \fB-entry\fR {\fI-label "Street" -variable start_street -type string -optional 1\fR} \\ + \fB-entry\fR {\fI-label "Street number" -variable start_street_nbr -type integer -optional 1\fR} \\ + \fB-frame\fR {\fI-label "Itinerary destination"\fR} \\ + \fB-comment\fR {\fI-text "Specify your itinerary destination"\fR} \\ + \fB-entry\fR {\fI-label "City" -variable dest_city -type string\fR} \\ + \fB-entry\fR {\fI-label "Street" -variable dest_street -type string -optional 1\fR} \\ + \fB-entry\fR {\fI-label "Street number" -variable dest_street_nbr -type integer -optional 1\fR} \\ + \fB-frame\fR {} \\ + \fB-checkbutton\fR {\fI-label "Don't use highways" -variable no_highway\fR}] +.CE +.IP +This example opens a dialog box that has the title \fIItinerary selection\fR. 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. +.TP +\fBtepam::argument_dialogbox\fR {\fIitem_name item_attributes ?item_name item_attributes? ?...?\fR} +Sometimes it is simpler to provide all the data entry item definitions in form of a single list to \fBargument_dialogbox\fR, and not as individual arguments. The second format that is supported by \fBargument_dialogbox\fR corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to \fBargument_dialogbox\fR. The previous example can therefore also be written in the following way: +.CS + +set DialogResult [\fBtepam::argument_dialogbox {\fR + \fB-title\fR "Itinerary selection" + \fB-file\fR {\fI-label "Itinerary report" -variable report_file\fR} + ... + \fB-checkbutton\fR {\fI-label "Don't use highways" -variable no_highway\fR} \fB}\fR] +.CE +.PP +The commands \fBargument_dialogbox\fR as well as \fBprocedure\fR are exported from the namespace \fBtepam\fR. To use these commands without the \fBtepam::\fR namespace prefix, it is sufficient to import them into the main namespace: +.CS + +\fBnamespace import tepam::*\fR + +set DialogResult [\fBargument_dialogbox\fR \\ + -title "Itinerary selection" + ... +.CE +The following subsections explain the different argument item types that are accepted by the \fBargument_dialogbox\fR, 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 \fBargument_dialogbox\fR. +.SS "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: +.CS + +tepam::argument_dialogbox \\ + \fB-<argument_name>\fR \fIstring\fR \\ + ... +.CE +The following items are classified into this group: +.TP +-title \fIstring\fR +The dialog box window's title which is by default \fIDialog\fR can be changed with the \fI-title\fR item: +.CS + +tepam::argument_dialogbox \\ + \fB-title\fR "System configuration" \\ + ... +.CE +.TP +-window \fIstring\fR +The argument dialog box uses by default \fI.dialog\fR as dialog top level window. This path can be changed with the \fI-window\fR item: +.CS + +tepam::argument_dialogbox \\ + \fB-window\fR .dialog \\ + ... +.CE +.TP +-parent \fIstring\fR +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. +.CS + +tepam::argument_dialogbox \\ + \fB-parent\fR .my_appl \\ + ... +.CE +.TP +-context \fIstring\fR +If a context is defined the dialog box's state, e.g. the entered data as well as the window size and position, is saved and restored then 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. +.CS + +tepam::argument_dialogbox \\ + \fB-context\fR destination_definitions \\ + ... +.CE +.PP +.SS "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. +.PP +The items of this classification group require as item attributes a definition list, which contains itself attribute name and value pairs: +.CS + +tepam::argument_dialogbox \\ + ... + \fB-<argument_name>\fR { \fI + ?-<attribute_name> <attribute_value>? + ?-<attribute_name> <attribute_value>? + ?...?\fR + } + ... +.CE +The following items are classified into this group: +.TP +-frame \fIlist\fR +The \fI-frame\fR 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: +.RS +.TP +-label \fIstring\fR +An optional frame label can be specified with the \fI-label\fR statement. +.RE +.IP +Example: +.CS + +tepam::argument_dialogbox \\ + ... + \fB-frame\fR {\fI-label "Destination address"\fR} + ... +.CE +.IP +To close an open frame without opening a new one, an empty list has to be provided to the \fI-frame\fR statement. +.CS + +tepam::argument_dialogbox \\ + ... + \fB-frame\fR {} + ... +.CE +.TP +-sep [const {{}}] +Entry widgets can be separated with the \fI-sep\fR statement which doesn't require additional definitions. The related definition list has to exist, but its content is ignored. +.CS + +tepam::argument_dialogbox \\ + ... + \fB-sep\fR {} + ... +.CE +.TP +-comment \fIstring\fR +Comments and descriptions can be added with the \fI-text\fR attribute of the \fI-comment\fR item. Please note that each entry widget itself can also contain a \fI-text\fR attribute for comments and descriptions. But the \fI-comment\fR item allows for example adding a description between two frames. +.CS + +tepam::argument_dialogbox \\ + ... + \fB-comment\fR {\fI-text "Specify bellow the destination address"\fR} + ... +.CE +.TP +-yscroll \fB0\fR|\fB1\fR|\fBauto\fR +This attribute allows controlling an eventual vertical scrollbar. Setting it to \fB0\fR will permanently disable the scrollbar, setting it to \fB1\fR will enable it. By default it is set to \fBauto\fR. The scrollbar is enabled in this mode only if the vertical data entry form size exceeds 66% of the screen height. +.CS + +tepam::argument_dialogbox \\ + ... + \fB-yscroll\fR \fBauto\fR + ... +.CE +.PP +.SS "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: +.CS + +tepam::argument_dialogbox \\ + ... + \fB-<argument_name>\fR { \fI + ?-<attribute_name> <attribute_value>? + ?-<attribute_name> <attribute_value>? + ?...?\fR + } + ... +.CE +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 \fBEntry Widget Item Attributes\fR. +.PP +TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional application specific entry widgets (see \fBAPPLICATION SPECIFIC ENTRY WIDGETS\fR): +.TP +-entry \fIlist\fR +The \fI-entry\fR item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings. +.CS + +tepam::argument_dialogbox \\ + \fB-entry\fR {-label Name -variable Entry} +.CE +.TP +-text \fIlist\fR +The \fI-text\fR item generates a multi line text entry widget. The widget's height can be selected with the \fI-height\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-text\fR {-label Name -variable Text -height 5} +.CE +.TP +-checkbox \fIlist\fR +A group of check boxes is created with the \fI-checkbox\fR item. The number of check boxes and their option values are specified with a list assigned to the \fI-choices\fR attribute or via a variable declared with the \fI-choicevariable\fR attribute: +.CS + +tepam::argument_dialogbox \\ + \fB-checkbox\fR {-label "Font sytle" -variable FontStyle \\ + -choices {bold italic underline} -default italic} +.CE +.IP +If the check boxes' labels should differ from the option values, their labels can be defined with the \fI-choicelabels\fR attribute: +.CS + +tepam::argument_dialogbox \\ + \fB-checkbox\fR {-label "Font sytle" -variable FontStyle \\ + -choices {bold italic underline} \\ + -choicelabels {Bold Italic Underline} \\ + -default italic} +.CE +.IP +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. +.TP +-radiobox \fIlist\fR +A group of radio boxes is created with the \fI-radiobox\fR item. The number of radio boxes and their option values are specified with a list assigned to the \fI-choices\fR attribute or via a variable declared with the \fI-choicevariable\fR attribute. +.sp +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. +.CS + +tepam::argument_dialogbox \\ + \fB-radiobox\fR {-label "Text adjustment" -variable Adjustment \\ + -choices {left center right} -default left} +.CE +.IP +If the radio boxes' labels should differ from the option values, their labels can be defined with the \fI-choicelabels\fR attribute: +.CS + +tepam::argument_dialogbox \\ + \fB-radiobox\fR {-label "Text adjustment" -variable Adjustment \\ + -choices {left center right} \\ + -choicelabels {Left Center Right} -default left} +.CE +.TP +-checkbutton \fIlist\fR +The \fI-checkbutton\fR entry widget allows activating or deactivating a single choice option. The result written into the variable will either be \fB0\fR if the check button was not activated or \fB1\fR if it was activated. An eventually provided default value has also to be either \fB0\fR or \fB1\fR. +.CS + +tepam::argument_dialogbox \\ + \fB-checkbutton\fR {-label Capitalize -variable Capitalize -default 1} +.CE +.PP +Several types of list and combo boxes are available to handle selection lists. +.TP +-combobox \fIlist\fR +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 \fI-choices\fR attribute, or via a variable that is specified with the \fI-choicevariable\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-combobox\fR {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12} +.CE +.IP +And here is an example of using a variable to define the selection list: +.CS + +set TextSizes {8 9 10 12 15 18} +tepam::argument_dialogbox \\ + \fB-combobox\fR {-label "Text size" -variable Size -choicevariable TextSizes -default 12} +.CE +.TP +-listbox \fIlist\fR +In contrast to the combo box, the list box is always displayed by the \fIlistbox\fR entry widget. Only one element is selectable unless the \fI-multiple_selection\fR attribute is set. The list box height can be selected with the \fI-height\fR 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: +.CS + +set set AvailableSizes +for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]} + +tepam::argument_dialogbox \\ + \fB-listbox\fR {-label "Distance" -variable Distance \\ + -choicevariable AvailableSizes -default 6 -height 5} +.CE +.IP +Here is a multi-element selection example. Please note that also the default selection can contain multiple elements: +.CS + +tepam::argument_dialogbox \\ + \fB-listbox\fR {-label "Text styles" -variable Styles \\ + -choices {bold italic underline overstrike} \\ + -choicelabels {Bold Italic Underline Overstrike} \\ + -default {bold underline} -multiple_selection 1 \\ + -height 3} +.CE +.TP +-disjointlistbox \fIlist\fR +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. +.sp +Disjoint listboxes allow always selecting multiple elements. With the exception of the \fI-multiple_selection\fR attribute, disjointed list boxes are accepting the same attributes as the normal listbox, e.g. \fI-height, -choices, -choicevariable, -default\fR. +.CS + +tepam::argument_dialogbox \\ + \fB-disjointlistbox\fR {-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}} +.CE +.PP +The file and directory selectors are building a next group of data entry widgets. A paragraph of section \fBEntry Widget Item Attributes\fR explains the widget specific attributes that allow specifying the targeted file types, active directory etc. +.TP +-file \fIlist\fR +The item \fI-file\fR creates a group composed by an entry widget together with a button that allows opening a file browser. The data type \fIfile\fR is automatically selected for this entry if no data type has been explicitly defined with the \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-file\fR {-label "Image file" -variable ImageF \\ + -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \\ + -initialfile "picture.gif"} +.CE +.TP +-existingfile \fIlist\fR +The item \fI-existingfile\fR 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 \fIexistingfile\fR is automatically selected for this entry if no data type has been explicitly defined with the \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-existingfile\fR {-label "Image file" -variable ImageF \\ + -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \\ + -initialfile "picture.gif"} +.CE +.TP +-directory \fIlist\fR +The item \fI-directory\fR creates a group composed by an entry widget together with a button that allows opening a directory browser. The data type \fIdirectory\fR is automatically selected for this entry if no data type has been explicitly defined with the \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-directory\fR {-label "Report directory" -variable ReportDir} +.CE +.TP +-existingdirectory \fIlist\fR +The item \fI-existingdirectory\fR 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 \fIexistingdirectory\fR is automatically selected for this entry if no data type has been explicitly defined with the \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-existingdirectory\fR {-label "Report directory" -variable ReportDir} +.CE +.PP +Finally, there is a last group of some other special data entry widgets. +.TP +-color \fIlist\fR +The color selector is composed by an entry widget together with a button that allows opening a color browser. The data type \fIcolor\fR is automatically selected for this entry widget type if no data type has been explicitly defined with the \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-color\fR {-label "Background color" -variable Color -default red} +.CE +.TP +-font \fIlist\fR +The font selector is composed by an entry widget together with a button that allows opening a font browser. The data type \fIfont\fR is automatically selected for this entry widget type if no data type has been explicitly defined with the \fI-type\fR attribute. The entry widget displays an example text in the format of the selected font. +.sp +The font browser allows selecting by default the font families provided by the \fBfont families\fR 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 \fI-font_families\fR or \fI-font_sizes\fR attributes. +.sp +If no default font is provided via the \fI-default\fR 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. +.CS + +tepam::argument_dialogbox \\ + \fB-font\fR {-label "Font" -variable Font \\ + -font_sizes {8 10 12 16} \\ + -default {Arial 20 italic}} +.CE +.PP +.SS "ENTRY WIDGET ITEM ATTRIBUTES" +All the entry widget items are accepting the following attributes: +.TP +-text \fIstring\fR +Eventual descriptions and comments specified with the \fI-text\fR attribute are displayed above the entry widget. +.CS + +tepam::argument_dialogbox \\ + -entry {\fB-text "Please enter your name bellow"\fR -variable Name} +.CE +.TP +-label \fIstring\fR +The label attribute creates left to the entry widget a label using the provided string as label text: +.CS + +tepam::argument_dialogbox \\ + -entry {\fB-label Name\fR -variable Name} +.CE +.TP +-variable \fIstring\fR +All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget's data are stored inside the defined variables. +.CS + +tepam::argument_dialogbox \\ + -existingdirectory {-label "Report directory" \fB-variable ReportDir\fR} +.CE +.TP +-default \fIstring\fR +Eventual default data for the entry widgets can be provided via the \fI-default\fR 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. +.CS + +tepam::argument_dialogbox \\ + -checkbox {-label "Font sytle" -variable FontStyle \\ + -choices {bold italic underline} \fB-default italic\fR} +.CE +.TP +-optional \fB0\fR|\fB1\fR +Data can be specified as optional or mandatory with the \fI-optional\fR attribute that requires either \fB0\fR (mandatory) or \fB1\fR (optional) as attribute data. +.sp +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. +.CS + +tepam::argument_dialogbox \\ + -entry {-label "City" -variable start_city -type string} \\ + -entry {-label "Street" -variable start_street -type string \fB-optional 0\fR} \\ + -entry {-label "Street number" -variable start_street_nbr -type integer \fB-optional 1\fR} \\ +.CE +.TP +-type \fIstring\fR +If the data type is defined with the \fI-type\fR 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. +.sp +The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by \fBtepam::procedure\fR (see the \fItepam::procedure reference manual\fR). +.sp +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 \fI-type\fR attribute. +.CS + +tepam::argument_dialogbox \\ + \fB-entry\fR {-label "Street number" -variable start_street_nbr \fB-type integer\fR} \\ +.CE +.TP +-range \fIstring\fR +Values can be constrained with the \fI-range\fR attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. +.sp +The \fI-range\fR attribute has to be used only for numerical arguments, like integers and doubles. +.CS + +tepam::argument_dialogbox \\ + -entry {-label Month -variable Month -type integer \fB-range {1 12}\fR} +.CE +.TP +-validatecommand \fIstring\fR +More complex value validations than type checks can be performed via specific validation commands that are declared with the \fI-validatecommand\fR attribute. +The provided validation command can be a script (command sequence) in which the pattern \fI%P\fR is replaced by the value that has to be checked. +.CS + +tepam::argument_dialogbox \\ + -entry {-label "Your comment" -variable YourCom \\ + \fB-validatecommand\fR "IllegalWordDetector %P"} ] +.CE +.PP +Some other attributes are supported by the list and combo boxes as well as by the radio and check buttons. +.TP +-choices \fIstring\fR +Choice lists can directly be defined with the \fI-choices\fR attribute. This way to define choice lists is especially adapted for smaller, fixed selection lists. +.CS + +tepam::argument_dialogbox \\ + -listbox {-label "Text styles" -variable Styles \\ + \fB-choices {bold italic underline}\fR -default underline +.CE +.TP +-choicelabels \fIstring\fR \fI(only check and radio buttons)\fR +If the check and radio boxes' labels should differ from the option values, they can be defined with the \fI-choicelabels\fR attribute: +.CS + +tepam::argument_dialogbox \\ + -checkbox {-label "Font sytle" -variable FontStyle \\ + -choices {bold italic underline} \\ + \fB-choicelabels {Bold Italic Underline}\fR +.CE +.TP +-choicevariable \fIstring\fR +Another way to define the choice lists is using the \fI-choicevariable\fR attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists. +.CS + +set TextSizes {8 9 10 12 15 18} +tepam::argument_dialogbox \\ + -combobox {-label "Text size" -variable Size \fB-choicevariable TextSizes\fR} +.CE +.TP +-multiple_selection \fB0\fR|\fB1\fR +The list box item (\fB-listbox\fR) allows by default selecting only one list element. By setting the \fI-multiple_selection\fR attribute to \fB1\fR, multiple elements can be selected. +.CS + +tepam::argument_dialogbox \\ + -listbox {-label "Text styles" -variable Styles \\ + -choices {bold italic underline} -default underline \\ + \fB-multiple_selection 1\fR -height 3} +.CE +.PP +Some additional attributes are supported by the file and directory selection widgets. +.TP +-filetypes \fIstring\fR +The file type attribute is used by the \fB-file\fR and \fB-existingfile\fR items to define the file endings that are searched by the file browser. +.CS + +tepam::argument_dialogbox \\ + -file {-label "Image file" -variable ImageF \\ + \fB-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}\fR} +.CE +.TP +-initialfile \fIstring\fR +The initial file used by the file browsers of the \fB-file\fR and \fB-existingfile\fR widgets are by default the file defined with the \fI-default\fR attribute, unless a file is specified with the \fI-initialfile\fR attribute. +.CS + +tepam::argument_dialogbox \\ + -file {-variable ImageF \fB-initialfile "picture.gif"\fR} +.CE +.TP +-activedir \fIstring\fR +The \fI-activedir\fR 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 (\fI-initialfile\fR) if defined, and otherwise by the directory of the default file/directory, specified with the \fI-default\fR attribute. +.CS + +tepam::argument_dialogbox \\ + -file "-variable ImageF \fB-activedir $pwd\fR" +.CE +.PP +Finally, there is a last attribute supported by some widgets: +.TP +-height \fIstring\fR +All widgets containing a selection list (\fB-listbox\fR, \fB-disjointlistbox\fR, \fB-font\fR) as well as the multi line \fB-text\fR widget are accepting the \fI-height\fR attribute that defines the number of displayed rows of the selection lists. +.CS + +tepam::argument_dialogbox \\ + -listbox {-label "Text size" -variable Size \\ + -choices {8 9 10 12 15 18} -default 12 \fB-height 3\fR} +.CE +.IP +If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box' size. +.PP +.SH "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 \fBtepam\fR 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: +.CS + +\fIproc\fR tepam::ad_form(<WidgetName>) {W Command {Par ""}} { + \fIupvar Option Option; # if required\fR + \fIvariable argument_dialogbox; # if required\fR + switch $Command { + "create" <CreateCommandSequence> + "set_choice" <SetChoiceCommandSequence> + "set" <SetCommandv> + "get" <GetCommandSequence> + } +} +.CE +\fBArgument_dialogbox\fR takes care about the \fI-label\fR and \fI-text\fR 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 \fIW\fR argument. +.PP +The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument \fICommand\fR: +.TP +\fIcreate\fR +The entry widget is called a first time with the command \fIcreate\fR to build the data entry widget. +.sp +The frames that are made available by \fBargument_dialogbox\fR 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 \fBad_form(make_expandable) $W\fR has to be executed when an entry widget is built. +.TP +\fIset_choice\fR +The entry widget procedure is only called with the \fIset_choice\fR command if the \fI-choices\fR or \fI-choicevariable\fR has been specified. The command is therefore only relevant for list and combo boxes. +.sp +The available selection list that is either specified with the \fI-choices\fR or \fI-choicevariable\fR attribute is provided via the \fIPar\fR argument to the entry widget procedure. This list can be used to initialize an available choice list. +.TP +\fIset\fR +If a default value is either defined via the \fI-default\fR attribute or via a preceding call the entry widget procedure is called with the \fIset\fR command. The argument \fIPar\fR contains in this case the value to which the entry widget has to be initialized. +.TP +\fIget\fR +The entry widget procedure's command \fIget\fR has to return the current value of the entry widget. +.PP +Eventually specified entry widget item attributes are available via the \fBOption\fR array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the \fBupvar\fR command. +.PP +There may be a need to store some information in a variable. The array variable \fBargument_dialogbox\fR has to be used for this purpose together with array indexes starting with \fI"$W,"\fR, e.g. \fIargument_dialogbox($W,values)\fR. +.PP +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 \fIentry\fR widget: +.CS + +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]} + } +} +.CE +It is also possible to relay on an existing entry widget procedure to derive a new, more specific one. The \fIradiobox\fR widget is used for example, to create a new entry widget that allows selecting either \fIleft\fR, \fIcenter\fR or \fIright\fR. The original \fIradiobox\fR widget is called with the \fIset_choice\fR command immediately after the \fIcreate\fR command, to define the fixed list of selection options. +.CS + +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 +} +.CE +Please consult the TEPAM package source file to find additional and more complex examples of entry widget procedures. +.SH VARIABLES +The \fBargument_dialogbox\fR is using two variables inside the namespace \fB::tepam\fR: +.TP +\fBargument_dialogbox\fR +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. \fIargument_dialogbox($W,<sub_index>)\fR. +.TP +\fBlast_parameters\fR +This array variable is only used by an argument dialog box if its context has been specified via the \fI-context\fR 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. +.sp +To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the \fBlast_parameter\fR array variable contents in a configuration file which is loaded the next time an application is launched. +.PP +.SH "SEE ALSO" +tepam(n), tepam::procedure(n) +.SH KEYWORDS +data entry form, parameter entry form +.SH CATEGORY +Argument entry form, mega widget +.SH COPYRIGHT +.nf +Copyright (c) 2009/2010, Andreas Drollinger + +.fi ADDED embedded/man/files/modules/tepam/tepam_introduction.n Index: embedded/man/files/modules/tepam/tepam_introduction.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tepam/tepam_introduction.n @@ -0,0 +1,538 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tepam/tepam_introduction.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009/2010, Andreas Drollinger +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tepam" n 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager" +.BS +.SH NAME +tepam \- An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager +.SH DESCRIPTION +.PP +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 \fItepam::procedure\fR and \fItepam::argument_dialogbox\fR reference manuals. +.SH 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: +.PP +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. +.PP +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. +.PP +Here is a short overview about all major TEPAM features: +.IP \(bu +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. +.IP \(bu +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. +.IP \(bu +Flexible usage of flags (switches), options (named arguments) and unnamed arguments. Option names are optionally automatically completed. +.IP \(bu +Support for default values, mandatory/optional options and arguments, choice lists, value ranges, multiple usable options/arguments. +.IP \(bu +Choice of a \fInamed arguments first, unnamed arguments later\fR procedure calling style (typical for Tcl commands) or of an \fIunnamed arguments first, named arguments later\fR procedure calling style (typical for Tk commands). +.IP \(bu +In case the \fInamed arguments first, unnamed arguments later\fR style (Tcl) is selected: Clear separation between options and arguments via the "--" flag. The unnamed arguments can optionally be accessed as options (named arguments). +.IP \(bu +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. +.IP \(bu +Many predefined types exist (integer, boolean, double, color, file, font, ...). Other application specific types can easily be added. +.IP \(bu +Automatic help and usage text generation if a procedure is called with the \fI-help\fR flag. +.IP \(bu +Automatic generation of an interactive argument definition form, in case a procedure is called with the \fI-interactive\fR flag. +.IP \(bu +Procedure calls can be logged which is useful to get for interactively called procedures the command call lines. +.IP \(bu +Powerful and code efficient generation of complex parameter definition forms. +.PP +.SH "PROCEDURE DECLARATION" +TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word \fBproc\fR, a procedure is declared with the TEPAM command \fBprocedure\fR which takes as \fBproc\fR also 3 arguments: The procedure name, the procedure header and the procedure body. +.PP +The following example declares the subcommand \fBmessage\fR of the procedure \fBdisplay\fR. This command has several named and unnamed arguments: +.CS + +\fBtepam::procedure\fR {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"} + } +} { +\fI puts "display message:" + foreach var {mtype font level fg bg no_border log_file text} { + if {[info exists $var]} { + puts " $var=[set $var]" + } + } +\fR} +.CE +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. +.PP +As the example above shows, the TEPAM command \fBprocedure\fR 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 \fBproc\fR and a command declared with \fBprocedure\fR. +.PP +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. +.PP +A list of argument definition statements assigned to the \fI-args\fR argument is defining the procedure arguments. Each argument definition statement starts with the argument name, optionally followed by some argument attributes. +.PP +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 \fInone\fR. +.PP +Named and unnamed arguments are mandatory, unless they are declared with the \fI-optional\fR flag and unless they have a default value specified with the \fI-default\fR option. Named arguments and the last unnamed argument can have the attribute \fI-multiple\fR, which means that they can be defined multiple times. The expected argument data type is specified with the \fI-type\fR option. TEPAM defines a large set of standard data types which can easily be completed with application specific data types. +.PP +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). +.SH "PROCEDURE HELP" +The declared procedure can simply be called with the \fI-help\fR option to get the information about the usage of the procedure and its arguments: +.CS + +\fBdisplay message\fR -help +\fI -> +NAME + display message - Displays a simple message box +SYNOPSYS + display message + [-mtype <mtype>] : + Message type, default: "Warning", choices: {Info Warning Error} + [-font <font>] : + Message text font, type: font, default: Arial 10 italic + [-level <level>] : + Message level, type: integer, range: 1..10 + [-fg <fg>] : + Message color, type: color, default: black + [-bg <bg>] : + Background color, type: color + [-no_border ] : + Use a splash window style (no border) + [-log_file <log_file>] : + Optional message log file, type: file + <text> : + Multiple text lines to display, type: string +DESCRIPTION + This procedure allows displaying a configurable message box.\fR +.CE +.SH "PROCEDURE CALL" +The specified procedure can be called in many ways. The following listing shows some valid procedure calls: +.CS + +\fBdisplay message\fR "The document hasn't yet been saved!" +\fI-> display message: + mtype=Warning + font=Arial 10 italic + fg=black + no_border=0 + text={The document hasn't yet been saved!}\fR + +\fBdisplay message\fR -fg red -bg black "Please save first the document" +\fI-> display message: + mtype=Warning + font=Arial 10 italic + fg=red + bg=black + no_border=0 + text={Please save first the document}\fR + +\fBdisplay message\fR -mtype Error -no_border "Why is here no border?" +\fI-> display message: + mtype=Error + font=Arial 10 italic + fg=black + no_border=1 + text={Why is here no border?}\fR + +\fBdisplay message\fR -font {Courier 12} -level 10 \\ + "Is there enough space?" "Reduce otherwise the font size!" +\fI-> display message: + mtype=Warning + font=Courier 12 + level=10 + fg=black + no_border=0 + text={Is there enough space?} {Reduce otherwise the font size!}\fR +.CE +The next lines show how wrong arguments are recognized. The \fItext\fR argument that is mandatory is missing in the first procedure call: +.CS + +\fBdisplay message\fR -font {Courier 12} +\fI -> display message: Required argument is missing: text\fR +.CE +Only known arguments are accepted: +.CS + +\fBdisplay message\fR -category warning Hello +\fI -> display message: Argument '-category' not known\fR +.CE +Argument types are automatically checked and an error message is generated in case the argument value has not the expected type: +.CS + +\fBdisplay message\fR -fg MyColor "Hello" +\fI -> display message: Argument 'fg' requires type 'color'. \\ + Provided value: 'MyColor'\fR +.CE +Selection choices have to be respected ... +.CS + +\fBdisplay message\fR -mtype Fatal Hello +\fI -> display message: Argument (mtype) has to be one of the \\ + following elements: Info, Warning, Error\fR +.CE +... as well as valid value ranges: +.CS + +\fBdisplay message\fR -level 12 Hello +\fI -> display message: Argument (level) has to be between 1 and 10\fR +.CE +.SH "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 \fI-interactive\fR flag. +.CS + +\fBdisplay message\fR -interactive +.CE +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. +.PP +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. +.PP +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. +.SH "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. TEPAM's provided argument dialog box allows crating complex parameter definition forms in a very efficient way. +.PP +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: +.CS + +\fBtepam::argument_dialogbox\fR \\ + \fB-existingfile\fR {-label "Source file" -variable SourceFile} \\ + \fB-existingdirectory\fR {-label "Destination folder" -variable DestDir} \\ + \fB-checkbutton\fR {-label "Overwrite existing file" -variable Overwrite} +.CE +The \fBargument_dialogbox\fR returns \fBok\fR if the entered data are validated. It will return \fBcancel\fR if the data entry has been canceled. After the validation of the entered data, the \fBargument_dialogbox\fR defines all the specified variables with the entered data inside the calling context. +.PP +An \fBargument_dialogbox\fR 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. +.PP +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. +.PP +The attribute list contains pairs of attribute names and attribute data. The primary attribute is \fI-variable\fR used to specify the variable in the calling context into which the entered data has to be stored. Another often used attribute is \fI-label\fR 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. +.PP +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 \fI-frame\fR and \fI-sep\fR which allows organizing the different entry widgets in frames and sections: +.CS + +set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"} + +set Result [\fBtepam::argument_dialogbox\fR \\ + \fB-title\fR "System configuration" \\ + \fB-context\fR test_1 \\ + \fB-frame\fR {-label "Entries"} \\ + \fB-entry\fR {-label Entry1 -variable Entry1} \\ + \fB-entry\fR {-label Entry2 -variable Entry2 -default "my default"} \\ + \fB-frame\fR {-label "Listbox & combobox"} \\ + \fB-listbox\fR {-label "Listbox, single selection" -variable Listbox1 \\ + -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \\ + \fB-listbox\fR {-label "Listbox, multiple selection" -variable Listbox2 + -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} + -multiple_selection 1 -height 3} \\ + \fB-disjointlistbox\fR {-label "Disjoined listbox" -variable DisJntListbox + -choicevariable ChoiceList \\ + -default {"Choice 3" "Choice 5"} -height 3} \\ + \fB-combobox\fR {-label "Combobox" -variable Combobox \\ + -choices {1 2 3 4 5 6 7 8} -default 3} \\ + \fB-frame\fR {-label "Checkbox, radiobox and checkbutton"} \\ + \fB-checkbox\fR {-label Checkbox -variable Checkbox + -choices {bold italic underline} -choicelabels {Bold Italic Underline} \\ + -default italic} \\ + \fB-radiobox\fR {-label Radiobox -variable Radiobox + -choices {bold italic underline} -choicelabels {Bold Italic Underline} \\ + -default underline} \\ + \fB-checkbutton\fR {-label CheckButton -variable Checkbutton -default 1} \\ + \fB-frame\fR {-label "Files & directories"} \\ + \fB-existingfile\fR {-label "Input file" -variable InputFile} \\ + \fB-file\fR {-label "Output file" -variable OutputFile} \\ + \fB-sep\fR {} \\ + \fB-existingdirectory\fR {-label "Input directory" -variable InputDirectory} \\ + \fB-directory\fR {-label "Output irectory" -variable OutputDirectory} \\ + \fB-frame\fR {-label "Colors and fonts"} \\ + \fB-color\fR {-label "Background color" -variable Color -default red} \\ + \fB-sep\fR {} \\ + \fB-font\fR {-label "Font" -variable Font -default {Courier 12 italic}}] +.CE +The \fBargument_dialogbox\fR defines all the specified variables with the entered data and returns \fBok\fR if the data have been validated via the Ok button. If the data entry is cancelled by activating the Cancel button, the \fBargument_dialogbox\fR returns \fBcancel\fR. +.CS + +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]'" + } +} +\fI-> 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'\fR +.CE +.SH "SEE ALSO" +tepam::argument_dialogbox(n), tepam::procedure(n) +.SH KEYWORDS +argument integrity, argument validation, arguments, entry mask, parameter entry form, procedure, subcommand +.SH CATEGORY +Procedures, arguments, parameters, options +.SH COPYRIGHT +.nf +Copyright (c) 2009/2010, Andreas Drollinger + +.fi ADDED embedded/man/files/modules/tepam/tepam_procedure.n Index: embedded/man/files/modules/tepam/tepam_procedure.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tepam/tepam_procedure.n @@ -0,0 +1,1191 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tepam/tepam_procedure.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009/2010, Andreas Drollinger +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tepam::procedure" n 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager" +.BS +.SH NAME +tepam::procedure \- TEPAM procedure, reference manual +.SH SYNOPSIS +package require \fBTcl 8.3\fR +.sp +package require \fBtepam ?0.4?\fR +.sp +\fBtepam::procedure\fR \fIname\fR \fIattributes\fR \fIbody\fR +.sp +.BE +.SH 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 \fBproc\fR: 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. +.PP +TEPAM simplifies also the handling of the different types of argument, like the \fInamed arguments\fR (often also called \fIoptions\fR) and the \fIunnamed arguments\fR. TEPAM supports the \fInamed first, unnamed later\fR style (typical Tcl command style) as well as also the \fIunnamed first, named later\fR 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. +.PP +An informal overview of all the TEPAM procedure declaration and calling features as well as a short introduction into TEPAM is provided by \fItepam(n)\fR. +.SH TERMINOLOGY +The exact meaning of several terms that are used in this document will be shortly explained to avoid any ambiguities and misunderstandings. +.TP +\fISubcommand\fR +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. +.sp +The \fBstring\fR command is an example of such a command that implements for example subcommands to check a character string's length, to compare strings, to extract substrings, etc: +.CS + +\fBstring length\fR \fIstring\fR +\fBstring compare\fR \fIstring\fR \fIstring\fR +\fBstring range\fR \fIstring\fR \fIfirst\fR \fIlast\fR +... +.CE +.sp +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 \fBstring\fR command's class check could be implemented as independent sub-sub-commands of the \fBstring\fR command: +.CS + +\fBstring is alnum\fR \fIstring\fR +\fBstring is integer\fR \fIstring\fR +\fBstring is double\fR \fIstring\fR +... +.CE +.TP +\fIProcedure attribute\fR +TEPAM allows attaching to a declared procedure different kind of attributes. Some of these attributes are \fIjust\fR 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. +.TP +\fIArgument\fR +TEPAM uses the term \fIargument\fR for the parameters of a procedure. +.sp +The following example calls the subcommand \fBstring compare\fR with several arguments: +.CS + +\fBstring compare\fR \fI-nocase -length 3 "emphasized" "emphasised"\fR +.CE +.IP +The following paragraphs discuss these different argument types. +.TP +\fINamed argument\fR +Some parameters, as \fI-length 3\fR of the subcommand \fBstring compare\fR have to be provided as pairs of argument names and argument values. This parameter type is often also called \fIoption\fR. +.sp +TEPAM uses the term \fInamed argument\fR for such options as well as for the flags (see next item). +.TP +\fIFlag, switch\fR +Another parameter type is the \fIflag\fR or the \fIswitch\fR. Flags are provided simply by naming the flag leading with the '-' character. The \fI-nocase\fR of the previous \fBstring compare\fR example is such a flag. +.sp +\fIFlags\fR are considered by TEPAM like a special form of \fInamed arguments\fR. +.TP +\fIUnnamed argument\fR +For the other parameters, e.g. the ones for which the argument name has not to be mentioned, TEPAM uses the term \fIunnamed argument\fR. The previous \fBstring compare\fR example uses for the two provided character strings two \fIunnamed arguments\fR. +.TP +\fIArgument attribute\fR +TEPAM allows describing the purpose of each procedure argument with \fIargument attributes\fR. 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. +.TP +\fINamed arguments first, unnamed arguments later\fR +The \fBstring compare\fR command of the previous example requires that the \fInamed arguments\fR (options, flags) are provided first. The two mandatory (unnamed) arguments have to be provided as last argument. +.sp +This is the usual Tcl style (exceptions exist) which is referred in the TEPAM documentation as \fInamed arguments first, unnamed arguments later style\fR. +.TP +\fIUnnamed arguments first, named arguments later\fR +In contrast to most Tcl commands, Tk uses generally (exceptions exist also here) a different calling style where the \fIunnamed arguments\fR have to be provided first, before the \fInamed arguments\fR have to be provided: +.CS + +\fBpack\fR \fI.ent1 .ent2 -fill x -expand yes -side left\fR +.CE +.IP +This style is referred in the TEPAM documentation as \fIunnamed arguments first, named arguments later style\fR. +.PP +.SH "PROCEDURE DECLARATION" +TEPAM allows declaring new Tcl procedures with the command \fBtepam::procedure\fR that has similar to the standard Tcl command \fBproc\fR also 3 arguments: +.TP +\fBtepam::procedure\fR \fIname\fR \fIattributes\fR \fIbody\fR +.PP +The TEPAM procedure declaration syntax is demonstrated by the following example: +.CS + +\fBtepam::procedure\fR {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" +} +.CE +The 3 arguments of \fBprocedure\fR are: +.TP +\fIname\fR +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. +.sp +Here are some valid procedure declarations using different procedure names (the attribute and body arguments are empty for simplicity): +.CS + +\fI# Simple procedure name:\fR +tepam::procedure \fBdisplay_message\fR {} {} +\fI\fR +\fI# Procedure declared in the main namespace:\fR +tepam::procedure \fB::display_message\fR {} {} +\fI\fR +\fI# Procedure in the namespace\fR \fB::ns\fR\fI:\fR +tepam::procedure \fB::ns::display_message\fR {} {} +\fI\fR +\fI# Declaration of the subcommand\fR \fBmessage\fR \fIof the procedure\fR \fBdisplay\fR\fI:\fR +tepam::procedure \fB{display message}\fR {} {} +.CE +.TP +\fIattributes\fR +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. +.sp +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 \fBProcedure Attributes\fR discusses in detail the available procedure attributes. +.sp +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 \fBArgument Declaration\fR discusses in detail all the argument definition attributes. +.TP +\fIbody\fR +This is the normal procedure body. The declared arguments will be available to the procedure body in form of variables. +.sp +The procedure body will only be executed if the provided set of arguments could be validated by the TEPAM argument manager. +.CS + +tepam::procedure {display_message} { + -args { + {-\fBmtype\fR -default Warning -choices {Warning Error}} + {\fBtext\fR -type string} + } +} { + puts "Message type: \fB$mtype\fR" + puts "Message: \fB$text\fR" +} +.CE +.PP +The commands \fBprocedure\fR as well as \fBargument_dialogbox\fR are exported from the namespace \fBtepam\fR. To use these commands without the \fBtepam::\fR namespace prefix, it is sufficient to import them into the main namespace: +.CS + +\fBnamespace import tepam::*\fR + +\fBprocedure\fR {display_message} { + -args { + ... +.CE +.SS "PROCEDURE ATTRIBUTES" +The first group of procedure attributes is not affecting the behavior of the declared procedure. These attributes are just used for the purpose of documentation and help text generation: +.TP +-category \fIstring\fR +A category can be assigned to a procedure for documentation purposes. Any string is accepted as category. +.TP +-short_description \fIstring\fR +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. +.TP +-description \fIstring\fR +The (full) description assigned to a procedure is used to create user manual and help pages. +.TP +-return \fIstring\fR +The \fI-return\fR attribute allows defining the expected return value of a procedure (used for documentation purposes). +.TP +-example \fIstring\fR +A help text or manual page of a procedure can be enriched with eventual examples, using the \fI-example\fR attribute. +.PP +The following attributes are not relevant for the documentation and help text generation, but they affect the behavior of the declared procedure: +.TP +-named_arguments_first \fB0\fR|\fB1\fR +This attribute defines the calling style of a procedure. TEPAM uses by default the \fInamed arguments first, unnamed arguments later\fR style (Tcl). This default behavior can globally be changed by setting the variable \fBtepam::named_arguments_first\fR to \fB0\fR. This global calling style can be changed individually for a procedure with the procedure's \fI-named_arguments_first\fR attribute. +.TP +-auto_argument_name_completion \fB0\fR|\fB1\fR +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 \fBtepam::auto_argument_name_completion\fR to \fB0\fR. This global setting of the automatic argument name completion can be changed individually for a procedure with the \fI-auto_argument_name_completion\fR procedure attribute. +.TP +-interactive_display_format \fBextended\fR|\fBshort\fR +A procedure declared with the TEPAM \fBprocedure\fR command can always be called with the \fB-interactive\fR 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 \fIextended\fR mode is more adapted for small procedure argument sets, the \fBshort\fR form is more adequate for huge procedure argument sets. +.sp +The choice to use short or extended forms can be globally configured via the variable \fBtepam::interactive_display_format\fR. This global setting can then be changed individually for a procedure with the \fI-interactive_display_format\fR procedure attribute. +.TP +-args \fIlist\fR +The procedure's arguments are declared via the \fI-args\fR 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 procedure's \fI-args\fR attribute. +.sp +The argument definition syntax will be described more in detail in the following sub section. +.PP +The following attribute allows controlling the logging settings for an individual procedure: +.TP +-command_log \fB0\fR|\fB1\fR|\fB"interactive"\fR +This argument configures the logging of the procedure calls into the list variable \fBtepam::ProcedureCallLogList\fR. The default configuration defined by the variable \fBtepam::command_log\fR will be used if this argument is not defined in a procedure declaration. +.sp +Setting this argument to \fB0\fR will disable any procedure call loggings, setting it to \fB1\fR will log any procedure calls and setting it to \fBinteractive\fR will log just the procedures that are called interactively (procedures called with the \fB-interactive\fR flag). +.PP +.SS "ARGUMENT DECLARATION" +The following example shows the structure that is used for the argument definitions in the context of a procedure declaration: +.CS + +tepam::procedure {display_message} { + -args \fB{ + {-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"} + }\fR +} { +} +.CE +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: +.CS + +tepam::procedure <name> { + -args \fB{ + {<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> \\ + <arg_attr_name_1b> <arg_attr_value_1b> ...} + {<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> \\ + <arg_attr_name_2b> <arg_attr_value_2b> ...} + ... + }\fR +} <body> +.CE +The argument names and attributes have to be used in the following way: +.TP +Argument name (\fI<argument_name_<n>>\fR) +The provided argument name specifies whether the argument is an \fIunnamed argument\fR or a \fInamed argument\fR. 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. +.RS +.TP +\fI"<Name>"\fR +This is the simplest form of an argument name: An argument whose name is not starting with '-' is an \fIunnamed argument\fR. The parameter provided during a procedure call will be assigned to a variable with the name \fI<Name>\fR. +.CS + +tepam::procedure {print_string} { + -args { + {\fBtext\fR -type string -description "This is an unnamed argument"} + } +} { + puts \fB$text\fR +} + +print_string \fB"Hello"\fR +\fI -> Hello\fR +.CE +.TP +\fI"-<Name>"\fR +An argument whose name starts with '-' is a \fInamed argument\fR (also called \fIoption\fR). The parameter provided during a procedure call will be assigned to a variable with the name \fI<Name>\fR (not \fI-<Name>\fR). +.CS + +tepam::procedure {print_string} { + -args { + {\fB-text\fR -type string -description "This is a named argument"} + } +} { + puts \fB$text\fR +} + +print_string \fB-text "Hello"\fR +\fI -> Hello\fR +.CE +.TP +\fI"--"\fR +This flag allows clearly specifying the end of the named arguments and the beginning of the unnamed arguments, in case the \fInamed arguments first, unnamed arguments later style (Tcl)\fR has been selected. +.sp +If the \fIunnamed arguments first, named arguments later style (Tk)\fR 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. +.TP +\fI"-"\fR or \fI""\fR +A blank argument name (either '-' or \fI''\fR) starts a comment for the following arguments. +.CS + +tepam::procedure {print_time} { + -interactive_display_format short + -args { + {hours -type integer -description "Hour"} + {minutes -type integer -description "Minute"} + + \fB{- The following arguments are optional:}\fR + {seconds -type integer -default 0 -description "Seconds"} + {milliseconds -type integer -default 0 -description "Milliseconds"} + } +} { + puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]" +} +.CE +.IP +Argument comments are basically used in the graphical argument definition forms that are created if a procedure is called interactively. +.TP +\fI"#*"\fR +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. +.sp +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. +.CS + +tepam::procedure {complex_multiply} { + -description "This function perform a complex multiplication" + -args { + \fB{#### First complex number ####}\fR + {-r0 -type double -description "First number's real part"} + {-i0 -type double -description "First number's imaginary part"} + + \fB{#### Second complex number ####}\fR + {-r1 -type double -description "Second number's real part"} + {-i1 -type double -description "Second number's imaginary part"} + } +} { + return [expr $r0*$r1 - $i0*$i1] +} +.CE +.RE +.TP +Argument attributes (\fI<arg_attr_name_<mn>> <arg_attr_value_<mn>>\fR) +The following argument attributes are supported: +.RS +.TP +-description \fIstring\fR +The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument. +.TP +-type \fItype\fR +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. +.sp +The section \fBARGUMENT TYPES\fR provides a list of predefined data types and explains how application specific types can be specified. +.sp +The argument type \fInone\fR has a special meaning. An argument that has the type \fInone\fR is handled as a \fIflag\fR. A flag is always optional and its related variable contains the logical value \fB1\fR if the flag has been defined during the procedure call, or otherwise \fB0\fR. +.TP +-default \fIvalue\fR +Eventual default values can be defined with the -default argument attribute. Arguments with default values are automatically optional arguments. +.TP +-optional|-mandatory +Arguments are by default mandatory, unless a default value is defined. The flag \fI-optional\fR transforms an argument into an optional argument. +.sp +In case an optional argument is not defined during a procedure call, the corresponding variable will not be defined. +The flag \fI-mandatory\fR is the opposite to \fI-optional\fR. This flag exists only for completion reason, since an argument is anyway mandatory by default. +.TP +-multiple +Arguments that have the \fI-multiple\fR 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. +.sp +The \fI-multiple\fR 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 \fI-multiple\fR attribute is an unnamed argument, this one has to be the absolute last one of all unnamed arguments. +.TP +-choices \fIlist\fR +A possible set of valid argument values can be attributed to an argument via the \fI-choices\fR attribute. The argument value provided during a procedure call will be checked against the provided choice values. +.TP +-choicelabels \fIlist\fR +An eventual short description can be attributed to each choice option with the \fI-choicelabels\fR attribute. These descriptions will be used in the generated help texts and as radio and check box labels for the interactive calls. +.sp +The \fI-choicelabels\fR attribute is optional, but if it is defined, its list needs to have the identical size as the \fI-choices\fR argument list. +.TP +-range \fI{double double}\fR +Another argument constraint can be defined with the \fI-range\fR attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. The \fI-range\fR attribute has to be used only for numerical arguments, like integers and doubles. +.TP +-validatecommand \fIscript\fR +Eventual more complex argument value validations can be performed via specific validation commands that are assigned to the \fI-validatecommand\fR attribute. The provided validation command can be a complete script in which the pattern \fI%P\fR is replaced by the argument value that has to be validated. +An example of a validation command declaration is: +.CS + +tepam::procedure {display_message} { + -args { + {text -type string -description "Message text" \\ + \fB-validatecommand "IllegalWordDetector %P"\fR} +} { +} +.CE +.TP +-widget \fIstring\fR +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 \fI-widget\fR attribute allows specifying explicitly a certain widget type for an argument. +.sp +.TP +-auxargs \fIlist\fR +In case a procedure is called interactively, additional argument attributes can be provided to the interactive argument definition form via the \fI-auxargs\fR attribute that is itself a list of attribute name/attribute value pairs: +.CS + +-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \\ + -<arg_attr_name_1b> <arg_attr_value_1b> + ... +} +.CE +.IP +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 \fI-auxargs\fR attribute to the argument definition form: +.CS + +tepam::procedure LoadPicture { + -args { + {FileName -type existingfile -description "Picture file" \\ + \fB-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}\fR} + } +} { +} +.CE +.TP +-auxargs_commands \fIscript\fR +If the auxiliary argument attributes are not static but have to be dynamically adaptable, the \fI-auxargs_commands\fR 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 \fI-auxargs_commands\fR attribute. The provided commands are executed in the context of the calling procedure. +.CS + +-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \\ + -<arg_attr_name_1b> <arg_attr_command_1b> + ... +} +.CE +.RE +.PP +.SH VARIABLES +Several variables defined inside the \fB::tepam\fR namespace are impacting the mode of operation of the procedures that have been declared with TEPAM' \fBprocedure\fR command. +.TP +\fBnamed_arguments_first\fR +This variable defines the general calling style of the procedures. It is by default set to \fB1\fR which selects the \fInamed arguments first, unnamed arguments later\fR style (Tcl style). +.sp +By setting this variable to \fB0\fR, the \fInamed arguments first, unnamed arguments later\fR style is globally selected (Tk style): +.CS + +set tepam::named_arguments_first 0 +.CE +.sp +While this variable defines the general calling style, the procedure attribute \fI-named_arguments_first\fR can adapt this style individually for each declared procedure. +.TP +\fBauto_argument_name_completion\fR +This variable controls the general automatic argument name matching mode. By default it is set to \fB1\fR, meaning that the called procedures are trying to match eventually abbreviated argument names with the declared argument names. +.sp +By setting this variable to \fB0\fR the automatic argument name matching mode is disabled: +.CS + +set tepam::auto_argument_name_completion 0 +.CE +.sp +While this variable defines the general matching mode, the procedure attribute \fI-auto_argument_name_completion\fR can adapt this mode individually for each declared procedure. +.TP +\fBinteractive_display_format\fR +A procedure declared via the TEPAM \fBprocedure\fR command can always be called with the \fB-interactive\fR switch. By doing so, a graphical form will be generated that allows entering interactively all procedure arguments. +.sp +There are two display modes for these interactive forms. The \fIextended\fR mode which is the default mode is more adapted for small procedure argument sets. The \fBshort\fR form is more adequate for huge procedure argument sets: +.CS + +set tepam::interactive_display_format "short" +.CE +.sp +The choice to use short or extended forms can be globally configured via the variable \fBinteractive_display_format\fR. +This global setting can be changed individually for a procedure with the procedure attribute \fI-interactive_display_format\fR. +.TP +\fBhelp_line_length\fR +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: +.CS + +set tepam::help_line_length 120 +.CE +.IP +Since this variable is applied directly during the help text generation, its value can continuously be adapted to the current need. +.TP +\fBcommand_log\fR +Procedure calls can be logged inside the list variable \fBtepam::ProcedureCallLogList\fR. The variable \fBtepam::command_log\fR controls the default logging settings for any procedures. The following configurations are supported: +.RS +.IP \(bu +\fI0\fR: Disables any procedure call loggings +.IP \(bu +\fI1\fR: Enables any procedure call loggings +.sp +.IP \(bu +\fI"interactive"\fR: Will log any procedures called interactively (e.g. procedures called with the -interactive flag). This is the default configuration. +.RE +.IP +This default logging configuration can be changed individually for each procedure with the \fI-command_log\fR attribute. +.PP +.SH "ARGUMENT TYPES" +A comprehensive set of procedure argument types that is already predefined by TEPAM can easily be completed with additional types that are required for a specific application. +.SS "PREDEFINED ARGUMENT TYPES" +To remember, a type can be assigned to each specified procedure argument: +.CS + +tepam::procedure {warning} { + -args { + {-font \fB-type font\fR -default {Arial 10 italic}} + {-severity_level \fB-type integer\fR -optional -range {1 10}} + {-fg \fB-type color\fR -optional -description "Message color"} + {text \fB-type string\fR -multiple -description "Multiple text lines to display"} + } +} { + ... +} +.CE +There are some \fIspecial purpose types\fR that are building the first category of predefined argument types: +.IP \(bu +\fBnone\fR +.sp +A \fIflag\fR, also called \fIswitch\fR, is defined as a named argument that has the type \fBnone\fR. Flags are always optional and the default value of the assigned variable is set to \fB0\fR. In contrast to the (normal) named arguments, no argument value has to be provided to a flag. +.CS + +tepam::procedure flag_test { + -args { + \fB{-flag -type none -description "This is a flag"}\fR + } +} { + puts \fB$flag\fR +} + +flag_test +\fI-> 0\fR + +flag_test -flag +\fI-> 1\fR +.CE +.sp +Since no argument value has to be provided to a flag, also no data check is performed for this argument type. +.IP \(bu +\fBstring\fR +.sp +\fBString\fR 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. +.IP \(bu +\fBtext\fR +.sp +\fBText\fR is identical to \fBstring\fR with the exception that it allows entering multi line strings during interactive procedure calls. +.IP \(bu +\fB{}\fR +.sp +A \fBblank\fR 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 \fBblank\fR type behaves identically than an argument that has a \fBstring\fR type, e.g. no argument data checks are performed. The only difference is that the data type \fBstring\fR is mentioned in the generated help documentation, while this is not the case for \fBblank\fR type. +.PP +.PP +Several \fInumerical types\fR are defined by TEPAM. The type validation procedures are using the \fBstring is <type> -strict\fR 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: +.CS + +string is \fB<type_to_check>\fR -strict \fI<argument_value>\fR +.CE +.IP \(bu +\fIboolean\fR +.sp +.IP \(bu +\fIinteger\fR +.sp +.IP \(bu +\fIdouble\fR +.sp +.PP +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: +.CS + +string is \fI<type_to_check>\fR \fI<argument_value>\fR +.CE +.IP \(bu +\fIalnum\fR +.sp +.IP \(bu +\fIalpha\fR +.sp +.IP \(bu +\fIascii\fR +.sp +.IP \(bu +\fIcontrol\fR +.sp +.IP \(bu +\fIdigit\fR +.sp +.IP \(bu +\fIgraph\fR +.sp +.IP \(bu +\fIlower\fR +.sp +.IP \(bu +\fIprint\fR +.sp +.IP \(bu +\fIpunct\fR +.sp +.IP \(bu +\fIspace\fR +.sp +.IP \(bu +\fIupper\fR +.sp +.IP \(bu +\fIwordchar\fR +.sp +.IP \(bu +\fIxdigit\fR +.sp +.PP +.PP +In addition to the data types checked with the \fBstring is <type>\fR commands, TEPAM specifies some other useful data types: +.IP \(bu +\fIchar\fR +.sp +Each string that has a length of 1 character meets the \fIcharacter\fR type. The type check is made with the following expression: +.CS + +expr [string length \fI<argument_value>\fR]==1 +.CE +.IP \(bu +\fIcolor\fR +.sp +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 \fIcolor\fR. TEPAM is using the following command to validate the color type: +.CS + +expr ![catch {winfo rgb . \fI<argument_value>\fR}] +.CE +.IP \(bu +\fIfont\fR +.sp +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 \fIfont\fR type. TEPAM is using the following command to validate the color type: +.CS + +expr ![catch {font measure <argument_value> ""}] +.CE +.IP \(bu +\fIfile\fR +.sp +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. +.sp +The following expression is used to validate the file names: +.CS + +expr [string length <argument_value>]>0 && ![regexp {[\\"*?<>:]} <argument_value>] +.CE +.IP \(bu +\fIexistingfile\fR +.sp +The argument is valid if it matches with an existing file. The following check is performed to validate the arguments of this type: +.CS + +file exists <argument_value> +.CE +.IP \(bu +\fIdirectory\fR +.sp +The directory argument is validated exactly in the same way as the file arguments. +.IP \(bu +\fIexistingdirectory\fR +.sp +The argument is valid if it matches with an existing directory. The following check is performed to validate the arguments of this type: +.CS + +file isdirectory <argument_value> +.CE +.PP +.SS "DEFINING APPLICATION SPECIFIC ARGUMENT TYPES" +To add support for a new application specific argument type it is just necessary to add into the namespace \fBtepam\fR a validation function \fBValidation(<type>)\fR. This function requires one argument. It has to returns \fB1\fR if the provided argument matches with the relevant data type. The function has to return otherwise \fB0\fR. +.PP +The validation command section of the "\fItepam.tcl\fR" package provides sufficient examples of validation functions, since it implements the ones for the standard TEPAM types. +.PP +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: +.CS + +proc tepam::Validate(two_char) {v} {expr [string length $v]==2} +.CE +.SH "PROCEDURE CALLS" +.SS HELP +Each procedure can be called with the \fI-help\fR flag. The procedure will then print a generated help text to \fIstdout\fR and will then return without performing any additional actions. +.PP +Taking the first procedure declared in \fBPROCEDURE CALLS\fR, the help request and the printed help text would be: +.CS + +\fBdisplay message -help\fR +\fI-> +NAME + display message - Displays a simple message box +SYNOPSIS + display message + [-mtype <mtype>] + Message type, default: "Warning", choices: {Info, Warning, Error} + <text> + Multiple text lines to display, type: string +DESCRIPTION + This procedure allows displaying a configurable message box. The default + message type that is created is a warning, but also errors and info can + be generated. + The procedure accepts multiple text lines. +EXAMPLE + display message -mtype Warning "Save first your job"\fR +.CE +The argument manager is checking if the last provided argument is \fI-help\fR and generates the requested help message if this is the case. So, also the following example will print the help message: +.CS + +\fBdisplay message -mtype Info "It is 7:00" -help\fR +.CE +On the other hand, the following call will result in an error: +.CS + +\fBdisplay message -help -mtype Info "It is 7:00"\fR +\fI-> +display message: Argument '-help' not known\fR +.CE +.SS "INTERACTIVE PROCEDURE CALL" +Calling a procedure with the \fI-interactive\fR flag will open a graphical form that allows specifying interactively all procedure arguments. The Tk library has to be loaded to use the interactive call. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in \fBPROCEDURE CALLS\fR: +.CS + +package require Tk +\fBdisplay message -interactive\fR +.CE +Also the \fI-interactive\fR flag has to be placed at the last argument position as this is also required for the \fI-help\fR flag. Arguments defined before the \fI-interactive\fR flag will be ignored. The following example is therefore also a valid interactive procedure call: +.CS + +\fBdisplay message\fR -mtype Info "It is 7:00" \fB-interactive\fR +.CE +.SS "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 \fI-multiple\fR attribute. So, the following declared procedure ... +.CS + +tepam::procedure {display_message} { + -args { + {mtype -choices {Info Warning Error}} + {text -type string -multiple} + } +} { + puts "$mtype: [join $text]" +} +.CE +... can for example be called in the following ways: +.CS + +\fBdisplay_message Info "It is PM 7:00."\fR +\fI-> Info: It is PM 7:00.\fR + +\fBdisplay_message Info "It is PM 7:00." "You should go home."\fR +\fI-> Info: It is PM 7:00. You should go home.\fR +.CE +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: +.CS + +\fBdisplay_message -mtype Info -text "It is PM 7:00."\fR +\fI-> Info: It is PM 7:00.\fR + +\fBdisplay_message -text "It is PM 7:00." -mtype Info\fR +\fI-> Info: It is PM 7:00.\fR + +\fBdisplay_message -mtype Info -text "It is PM 7:00." -text "You should go home."\fR +\fI-> Info: It is PM 7:00. You should go home.\fR + +\fBdisplay_message -text "It is PM 7:00." -text "You should go home." -mtype Info\fR +\fI-> Info: It is PM 7:00. You should go home.\fR +.CE +.SS "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. +.PP +The following declared procedure ... +.CS + +tepam::procedure {display_message} { + -args { + {-mtype -choices {Info Warning Error}} + {-text -type string -multiple} + } +} { + puts "$mtype: [join $text]" +} +.CE +... can be called in the following ways: +.CS + +\fBdisplay_message -mtype Info -text "It is PM 7:00."\fR +\fI-> Info: It is PM 7:00.\fR + +\fBdisplay_message -text "It is PM 7:00." -mtype Info\fR +\fI-> Info: It is PM 7:00.\fR + +\fBdisplay_message -mtype Info -text "It is PM 7:00." -text "You should go home."\fR +\fI-> Info: It is PM 7:00. You should go home.\fR + +\fBdisplay_message -text "It is PM 7:00." -text "You should go home." -mtype Info\fR +\fI-> Info: It is PM 7:00. You should go home.\fR +.CE +Also named arguments that have not the \fI-multiple\fR attribute can be provided multiple times. Only the last provided argument will be retained in such a case: +.CS + +\fBdisplay_message -mtype Info -text "It is PM 7:00." -mtype Warning\fR +\fI-> Warning: It is PM 7:00.\fR +.CE +.SS "UNNAMED ARGUMENTS FIRST, NAMED ARGUMENTS LATER (TK STYLE)" +A procedure that has been defined while the variable \fBtepam::named_arguments_first\fR was set to 1, or with the procedure attribute \fI-named_arguments_first\fR 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: +.CS + +\fBset tepam::named_arguments_first 1\fR +tepam::procedure my_proc { + -args { + {-n1 -default ""} + {-n2 -default ""} + {u1 -default ""} + {u2 -default ""} + } +} { + puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" +} +.CE +The unnamed arguments are placed at the end of procedure call, after the named arguments: +.CS + +my_proc \fB-n1 N1 -n2 N2 U1 U2\fR +\fI-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'\fR +.CE +The argument parser considers the first argument that doesn't start with the '-' character as well as all following arguments as unnamed argument: +.CS + +my_proc \fBU1 U2\fR +\fI-> n1:'', n2:'', u1:'U1', u2:'U2'\fR +.CE +Named arguments can be defined multiple times. If the named argument has the \fI-multiply\fR attribute, all argument values will be collected in a list. Otherwise, only the last provided attribute value will be retained: +.CS + +my_proc \fB-n1 N1 -n2 N2 -n1 M1 U1 U2\fR +\fI-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'\fR +.CE +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: +.CS + +my_proc \fB-n1 N1 -n2 N2 "->" "<-"\fR +\fI-> my_proc: Argument '->' not known\fR + +set U1 "->" +my_proc -n1 N1 -n2 N2 $U1 U2}] +my_proc: Argument '->' not known +.CE +The '--' flag allows separating unambiguously the unnamed arguments from the named arguments. All data after the '--' flag will be considered as unnamed argument: +.CS + +my_proc \fB-n1 N1 -n2 N2 -- "->" "<-"\fR +\fI-> n1:'N1', n2:'N2', u1:'->', u2:'<-'\fR + +set U1 "->" +my_proc \fB-n1 N1 -n2 N2 -- $U1 U2\fR +\fI-> n1:'N1', n2:'N2', u1:'->', u2:'<-'\fR +.CE +.SS "NAMED ARGUMENTS FIRST, UNNAMED ARGUMENTS LATER (TCL STYLE)" +The Tk calling style will be chosen if a procedure is defined while the variable \fBtepam::named_arguments_first\fR is set to 0, or if the procedure attribute \fI-named_arguments_first\fR has been set to 0. The following procedure will be used in this section to illustrate this calling style: +.CS + +\fBset tepam::named_arguments_first 0\fR +tepam::procedure my_proc { + -args { + {-n1 -default ""} + {-n2 -default ""} + {u1} + {u2 -default "" -multiple} + } +} { + puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" +} +.CE +The unnamed arguments have to be provided first in this case. The named arguments are provided afterwards: +.CS + +my_proc \fBU1 U2 -n1 N1 -n2 N2\fR +\fI-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'\fR +.CE +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. +.PP +An argument value will only be assigned to an unnamed argument that is optional (that has either the \fI-optional\fR 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. +.PP +Argument values are assigned to an argument that has the \fI-multiple\fR attribute as long as the parameter value doesn't starts with the '-' character. +.PP +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. +.PP +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 \fIu1\fR is a mandatory argument: +.CS + +my_proc +\fI-> my_proc: Required argument is missing: u1\fR +.CE +The procedure call is valid if one parameter is provided for \fIu1\fR: +.CS + +my_proc \fBU1\fR +\fI-> n1:'', n2:'', u1:'U1', u2:''\fR +.CE +If more parameters are provided that are not starting with the '-' character, they will be attributed to the unnamed arguments. \fIU2\fR will receive 3 of these parameters, since it accepts multiple values: +.CS + +my_proc \fBU1 U2 U3 U4\fR +\fI-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'\fR +.CE +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: +.CS + +my_proc \fBU1 U2 U3 U4 -U5\fR +\fI-> my_proc: Argument '-U5' not known\fR +.CE +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 \fInext\fR unnamed argument. This was certainly not the intention in the following example: +.CS + +my_proc \fB-n1 N1\fR +\fI-> n1:'', n2:'', u1:'-n1', u2:'N1'\fR +.CE +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: +.CS + +my_proc \fBU1 -n1 N1\fR +\fI-> n1:'N1', n2:'', u1:'U1', u2:''\fR +.CE +No unnamed arguments are allowed behind the named arguments: +.CS + +my_proc \fBU1 -n1 N1 U2\fR +\fI-> my_proc: Argument 'U2' is not an option\fR +.CE +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: +.CS + +my_proc \fB-- -n1 N1\fR +\fI-> n1:'N1', n2:'', u1:'--', u2:''\fR +.CE +But the '--' flag is simply ignored if the argument parser has started to handle the named arguments: +.CS + +my_proc \fBU1 -- -n1 N1\fR +\fI-> n1:'N1', n2:'', u1:'U1', u2:''\fR + +my_proc \fBU1 -n1 N1 -- -n2 N2\fR +\fI-> n1:'N1', n2:'N2', u1:'U1', u2:''\fR +.CE +.SS "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 \fBargs\fR variable that contains always the unprocessed argument list: +.CS + +tepam::procedure {display_message} { + -args { + {-mtype -choices {Warning Error} -default Warning} + {text -type string -multiple} + + } +} { + puts "args: \fB$args\fR" +} +display_message -mtype Warning "It is 7:00" +\fI-> args: -mtype Warning {It is 7:00}\fR +.CE +.SH "SEE ALSO" +tepam(n), tepam::argument_dialogbox(n) +.SH KEYWORDS +argument integrity, argument validation, arguments, procedure, subcommand +.SH CATEGORY +Procedures, arguments, parameters, options +.SH COPYRIGHT +.nf +Copyright (c) 2009/2010, Andreas Drollinger + +.fi ADDED embedded/man/files/modules/term/ansi_cattr.n Index: embedded/man/files/modules/term/ansi_cattr.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_cattr.n @@ -0,0 +1,465 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_cattr.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::code::attr" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::code::attr \- ANSI attribute sequences +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::ansi::code ?0.1?\fR +.sp +package require \fBterm::ansi::code::attr ?0.1?\fR +.sp +\fB::term::ansi::code::attr::names\fR +.sp +\fB::term::ansi::code::attr::import\fR ?\fIns\fR? ?\fIarg\fR...? +.sp +\fB::term::ansi::code::attr::fgblack\fR +.sp +\fB::term::ansi::code::attr::fgred\fR +.sp +\fB::term::ansi::code::attr::fggreen\fR +.sp +\fB::term::ansi::code::attr::fgyellow\fR +.sp +\fB::term::ansi::code::attr::fgblue\fR +.sp +\fB::term::ansi::code::attr::fgmagenta\fR +.sp +\fB::term::ansi::code::attr::fgcyan\fR +.sp +\fB::term::ansi::code::attr::fgwhite\fR +.sp +\fB::term::ansi::code::attr::fgdefault\fR +.sp +\fB::term::ansi::code::attr::bgblack\fR +.sp +\fB::term::ansi::code::attr::bgred\fR +.sp +\fB::term::ansi::code::attr::bggreen\fR +.sp +\fB::term::ansi::code::attr::bgyellow\fR +.sp +\fB::term::ansi::code::attr::bgblue\fR +.sp +\fB::term::ansi::code::attr::bgmagenta\fR +.sp +\fB::term::ansi::code::attr::bgcyan\fR +.sp +\fB::term::ansi::code::attr::bgwhite\fR +.sp +\fB::term::ansi::code::attr::bgdefault\fR +.sp +\fB::term::ansi::code::attr::bold\fR +.sp +\fB::term::ansi::code::attr::dim\fR +.sp +\fB::term::ansi::code::attr::italic\fR +.sp +\fB::term::ansi::code::attr::underline\fR +.sp +\fB::term::ansi::code::attr::blink\fR +.sp +\fB::term::ansi::code::attr::revers\fR +.sp +\fB::term::ansi::code::attr::hidden\fR +.sp +\fB::term::ansi::code::attr::strike\fR +.sp +\fB::term::ansi::code::attr::nobold\fR +.sp +\fB::term::ansi::code::attr::noitalic\fR +.sp +\fB::term::ansi::code::attr::nounderline\fR +.sp +\fB::term::ansi::code::attr::noblink\fR +.sp +\fB::term::ansi::code::attr::norevers\fR +.sp +\fB::term::ansi::code::attr::nohidden\fR +.sp +\fB::term::ansi::code::attr::nostrike\fR +.sp +\fB::term::ansi::code::attr::reset\fR +.sp +.BE +.SH 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 +\fBterm::ansi::send\fR. +.SH API +.SS INTROSPECTION +.TP +\fB::term::ansi::code::attr::names\fR +This command is for introspection. It returns as its result a list +containing the names of all attribute commands. +.TP +\fB::term::ansi::code::attr::import\fR ?\fIns\fR? ?\fIarg\fR...? +This command imports some or all attribute commands into the namespace +\fIns\fR. This is by default the namespace \fIattr\fR. 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. +.PP +.SS ATTRIBUTES +.TP +\fB::term::ansi::code::attr::fgblack\fR +Set text color to \fIBlack\fR. +.TP +\fB::term::ansi::code::attr::fgred\fR +Set text color to \fIRed\fR. +.TP +\fB::term::ansi::code::attr::fggreen\fR +Set text color to \fIGreen\fR. +.TP +\fB::term::ansi::code::attr::fgyellow\fR +Set text color to \fIYellow\fR. +.TP +\fB::term::ansi::code::attr::fgblue\fR +Set text color to \fIBlue\fR. +.TP +\fB::term::ansi::code::attr::fgmagenta\fR +Set text color to \fIMagenta\fR. +.TP +\fB::term::ansi::code::attr::fgcyan\fR +Set text color to \fICyan\fR. +.TP +\fB::term::ansi::code::attr::fgwhite\fR +Set text color to \fIWhite\fR. +.TP +\fB::term::ansi::code::attr::fgdefault\fR +Set default text color (\fIBlack\fR). +.TP +\fB::term::ansi::code::attr::bgblack\fR +Set background to \fIBlack\fR. +.TP +\fB::term::ansi::code::attr::bgred\fR +Set background to \fIRed\fR. +.TP +\fB::term::ansi::code::attr::bggreen\fR +Set background to \fIGreen\fR. +.TP +\fB::term::ansi::code::attr::bgyellow\fR +Set background to \fIYellow\fR. +.TP +\fB::term::ansi::code::attr::bgblue\fR +Set background to \fIBlue\fR. +.TP +\fB::term::ansi::code::attr::bgmagenta\fR +Set background to \fIMagenta\fR. +.TP +\fB::term::ansi::code::attr::bgcyan\fR +Set background to \fICyan\fR. +.TP +\fB::term::ansi::code::attr::bgwhite\fR +Set background to \fIWhite\fR. +.TP +\fB::term::ansi::code::attr::bgdefault\fR +Set default background (Transparent). +.TP +\fB::term::ansi::code::attr::bold\fR +Bold on. +.TP +\fB::term::ansi::code::attr::dim\fR +Dim on. +.TP +\fB::term::ansi::code::attr::italic\fR +Italics on. +.TP +\fB::term::ansi::code::attr::underline\fR +Underscore on. +.TP +\fB::term::ansi::code::attr::blink\fR +Blink on. +.TP +\fB::term::ansi::code::attr::revers\fR +Reverse on. +.TP +\fB::term::ansi::code::attr::hidden\fR +Hidden on. +.TP +\fB::term::ansi::code::attr::strike\fR +Strike-through on. +.TP +\fB::term::ansi::code::attr::nobold\fR +Bold off. +.TP +\fB::term::ansi::code::attr::noitalic\fR +Italics off. +.TP +\fB::term::ansi::code::attr::nounderline\fR +Underscore off. +.TP +\fB::term::ansi::code::attr::noblink\fR +Blink off. +.TP +\fB::term::ansi::code::attr::norevers\fR +Reverse off. +.TP +\fB::term::ansi::code::attr::nohidden\fR +Hidden off. +.TP +\fB::term::ansi::code::attr::nostrike\fR +Strike-through off. +.TP +\fB::term::ansi::code::attr::reset\fR +Reset all attributes to their default values. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ansi, attribute control, color control, control, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ansi_cctrl.n Index: embedded/man/files/modules/term/ansi_cctrl.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_cctrl.n @@ -0,0 +1,756 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_cctrl.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::code::ctrl" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::code::ctrl \- ANSI control sequences +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::ansi::code ?0.1?\fR +.sp +package require \fBterm::ansi::code::ctrl ?0.1.1?\fR +.sp +\fB::term::ansi::code::ctrl::names\fR +.sp +\fB::term::ansi::code::ctrl::import\fR ?\fIns\fR? ?\fIarg\fR...? +.sp +\fB::term::ansi::code::ctrl::eeol\fR +.sp +\fB::term::ansi::code::ctrl::esol\fR +.sp +\fB::term::ansi::code::ctrl::el\fR +.sp +\fB::term::ansi::code::ctrl::ed\fR +.sp +\fB::term::ansi::code::ctrl::eu\fR +.sp +\fB::term::ansi::code::ctrl::es\fR +.sp +\fB::term::ansi::code::ctrl::sd\fR +.sp +\fB::term::ansi::code::ctrl::su\fR +.sp +\fB::term::ansi::code::ctrl::ch\fR +.sp +\fB::term::ansi::code::ctrl::sc\fR +.sp +\fB::term::ansi::code::ctrl::rc\fR +.sp +\fB::term::ansi::code::ctrl::sca\fR +.sp +\fB::term::ansi::code::ctrl::rca\fR +.sp +\fB::term::ansi::code::ctrl::st\fR +.sp +\fB::term::ansi::code::ctrl::ct\fR +.sp +\fB::term::ansi::code::ctrl::cat\fR +.sp +\fB::term::ansi::code::ctrl::qdc\fR +.sp +\fB::term::ansi::code::ctrl::qds\fR +.sp +\fB::term::ansi::code::ctrl::qcp\fR +.sp +\fB::term::ansi::code::ctrl::rd\fR +.sp +\fB::term::ansi::code::ctrl::elw\fR +.sp +\fB::term::ansi::code::ctrl::dlw\fR +.sp +\fB::term::ansi::code::ctrl::eg\fR +.sp +\fB::term::ansi::code::ctrl::lg\fR +.sp +\fB::term::ansi::code::ctrl::scs0\fR \fItag\fR +.sp +\fB::term::ansi::code::ctrl::scs1\fR \fItag\fR +.sp +\fB::term::ansi::code::ctrl::sda\fR \fIarg\fR... +.sp +\fB::term::ansi::code::ctrl::sda_fgblack\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgred\fR +.sp +\fB::term::ansi::code::ctrl::sda_fggreen\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgyellow\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgblue\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgmagenta\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgcyan\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgwhite\fR +.sp +\fB::term::ansi::code::ctrl::sda_fgdefault\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgblack\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgred\fR +.sp +\fB::term::ansi::code::ctrl::sda_bggreen\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgyellow\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgblue\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgmagenta\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgcyan\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgwhite\fR +.sp +\fB::term::ansi::code::ctrl::sda_bgdefault\fR +.sp +\fB::term::ansi::code::ctrl::sda_bold\fR +.sp +\fB::term::ansi::code::ctrl::sda_dim\fR +.sp +\fB::term::ansi::code::ctrl::sda_italic\fR +.sp +\fB::term::ansi::code::ctrl::sda_underline\fR +.sp +\fB::term::ansi::code::ctrl::sda_blink\fR +.sp +\fB::term::ansi::code::ctrl::sda_revers\fR +.sp +\fB::term::ansi::code::ctrl::sda_hidden\fR +.sp +\fB::term::ansi::code::ctrl::sda_strike\fR +.sp +\fB::term::ansi::code::ctrl::sda_nobold\fR +.sp +\fB::term::ansi::code::ctrl::sda_noitalic\fR +.sp +\fB::term::ansi::code::ctrl::sda_nounderline\fR +.sp +\fB::term::ansi::code::ctrl::sda_noblink\fR +.sp +\fB::term::ansi::code::ctrl::sda_norevers\fR +.sp +\fB::term::ansi::code::ctrl::sda_nohidden\fR +.sp +\fB::term::ansi::code::ctrl::sda_nostrike\fR +.sp +\fB::term::ansi::code::ctrl::sda_reset\fR +.sp +\fB::term::ansi::send::fcp\fR \fIrow\fR \fIcol\fR +.sp +\fB::term::ansi::code::ctrl::cu\fR ?\fIn\fR? +.sp +\fB::term::ansi::code::ctrl::cd\fR ?\fIn\fR? +.sp +\fB::term::ansi::code::ctrl::cf\fR ?\fIn\fR? +.sp +\fB::term::ansi::code::ctrl::cb\fR ?\fIn\fR? +.sp +\fB::term::ansi::code::ctrl::ss\fR ?\fIs\fR \fIe\fR? +.sp +\fB::term::ansi::code::ctrl::skd\fR \fIcode\fR \fIstr\fR +.sp +\fB::term::ansi::code::ctrl::title\fR \fIstr\fR +.sp +\fB::term::ansi::code::ctrl::gron\fR +.sp +\fB::term::ansi::code::ctrl::groff\fR +.sp +\fB::term::ansi::code::ctrl::tlc\fR +.sp +\fB::term::ansi::code::ctrl::trc\fR +.sp +\fB::term::ansi::code::ctrl::brc\fR +.sp +\fB::term::ansi::code::ctrl::blc\fR +.sp +\fB::term::ansi::code::ctrl::ltj\fR +.sp +\fB::term::ansi::code::ctrl::ttj\fR +.sp +\fB::term::ansi::code::ctrl::rtj\fR +.sp +\fB::term::ansi::code::ctrl::btj\fR +.sp +\fB::term::ansi::code::ctrl::fwj\fR +.sp +\fB::term::ansi::code::ctrl::hl\fR +.sp +\fB::term::ansi::code::ctrl::vl\fR +.sp +\fB::term::ansi::code::ctrl::groptim\fR \fIstr\fR +.sp +\fB::term::ansi::code::ctrl::clear\fR +.sp +\fB::term::ansi::code::ctrl::init\fR +.sp +\fB::term::ansi::code::ctrl::showat\fR \fIrow\fR \fIcol\fR \fItext\fR +.sp +.BE +.SH 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 \fBterm::ansi::send\fR. +.SH API +.SS INTROSPECTION +.TP +\fB::term::ansi::code::ctrl::names\fR +This command is for introspection. It returns as its result a list +containing the names of all attribute commands. +.TP +\fB::term::ansi::code::ctrl::import\fR ?\fIns\fR? ?\fIarg\fR...? +This command imports some or all attribute commands into the namespace +\fIns\fR. This is by default the namespace \fIctrl\fR. 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. +.PP +.SS SEQUENCES +.TP +\fB::term::ansi::code::ctrl::eeol\fR +Erase (to) End Of Line +.TP +\fB::term::ansi::code::ctrl::esol\fR +Erase (to) Start Of Line +.TP +\fB::term::ansi::code::ctrl::el\fR +Erase (current) Line +.TP +\fB::term::ansi::code::ctrl::ed\fR +Erase Down (to bottom) +.TP +\fB::term::ansi::code::ctrl::eu\fR +Erase Up (to top) +.TP +\fB::term::ansi::code::ctrl::es\fR +Erase Screen +.TP +\fB::term::ansi::code::ctrl::sd\fR +Scroll Down +.TP +\fB::term::ansi::code::ctrl::su\fR +Scroll Up +.TP +\fB::term::ansi::code::ctrl::ch\fR +Cursor Home +.TP +\fB::term::ansi::code::ctrl::sc\fR +Save Cursor +.TP +\fB::term::ansi::code::ctrl::rc\fR +Restore Cursor (Unsave) +.TP +\fB::term::ansi::code::ctrl::sca\fR +Save Cursor + Attributes +.TP +\fB::term::ansi::code::ctrl::rca\fR +Restore Cursor + Attributes +.TP +\fB::term::ansi::code::ctrl::st\fR +Set Tab (@ current position) +.TP +\fB::term::ansi::code::ctrl::ct\fR +Clear Tab (@ current position) +.TP +\fB::term::ansi::code::ctrl::cat\fR +Clear All Tabs +.TP +\fB::term::ansi::code::ctrl::qdc\fR +Query Device Code +.TP +\fB::term::ansi::code::ctrl::qds\fR +Query Device Status +.TP +\fB::term::ansi::code::ctrl::qcp\fR +Query Cursor Position +.TP +\fB::term::ansi::code::ctrl::rd\fR +Reset Device +.TP +\fB::term::ansi::code::ctrl::elw\fR +Enable Line Wrap +.TP +\fB::term::ansi::code::ctrl::dlw\fR +Disable Line Wrap +.TP +\fB::term::ansi::code::ctrl::eg\fR +Enter Graphics Mode +.TP +\fB::term::ansi::code::ctrl::lg\fR +Exit Graphics Mode +.TP +\fB::term::ansi::code::ctrl::scs0\fR \fItag\fR +Set default character set +.TP +\fB::term::ansi::code::ctrl::scs1\fR \fItag\fR +Set alternate character set +Select Character Set. +.sp +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. +.sp +The legal tags, and their meanings, are: +.RS +.TP +A +United Kingdom Set +.TP +B +ASCII Set +.TP +0 +Special Graphics +.TP +1 +Alternate Character ROM Standard Character Set +.TP +2 +Alternate Character ROM Special Graphics +.RE +.TP +\fB::term::ansi::code::ctrl::sda\fR \fIarg\fR... +Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package \fBterm::ansi::code::attr\fR. For +convenience this package also provides additional commands each setting a single +specific attribute. +.TP +\fB::term::ansi::code::ctrl::sda_fgblack\fR +Set text color to \fIBlack\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgred\fR +Set text color to \fIRed\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fggreen\fR +Set text color to \fIGreen\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgyellow\fR +Set text color to \fIYellow\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgblue\fR +Set text color to \fIBlue\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgmagenta\fR +Set text color to \fIMagenta\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgcyan\fR +Set text color to \fICyan\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgwhite\fR +Set text color to \fIWhite\fR. +.TP +\fB::term::ansi::code::ctrl::sda_fgdefault\fR +Set default text color (\fIBlack\fR). +.TP +\fB::term::ansi::code::ctrl::sda_bgblack\fR +Set background to \fIBlack\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgred\fR +Set background to \fIRed\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bggreen\fR +Set background to \fIGreen\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgyellow\fR +Set background to \fIYellow\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgblue\fR +Set background to \fIBlue\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgmagenta\fR +Set background to \fIMagenta\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgcyan\fR +Set background to \fICyan\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgwhite\fR +Set background to \fIWhite\fR. +.TP +\fB::term::ansi::code::ctrl::sda_bgdefault\fR +Set default background (Transparent). +.TP +\fB::term::ansi::code::ctrl::sda_bold\fR +Bold on. +.TP +\fB::term::ansi::code::ctrl::sda_dim\fR +Dim on. +.TP +\fB::term::ansi::code::ctrl::sda_italic\fR +Italics on. +.TP +\fB::term::ansi::code::ctrl::sda_underline\fR +Underscore on. +.TP +\fB::term::ansi::code::ctrl::sda_blink\fR +Blink on. +.TP +\fB::term::ansi::code::ctrl::sda_revers\fR +Reverse on. +.TP +\fB::term::ansi::code::ctrl::sda_hidden\fR +Hidden on. +.TP +\fB::term::ansi::code::ctrl::sda_strike\fR +Strike-through on. +.TP +\fB::term::ansi::code::ctrl::sda_nobold\fR +Bold off. +.TP +\fB::term::ansi::code::ctrl::sda_noitalic\fR +Italics off. +.TP +\fB::term::ansi::code::ctrl::sda_nounderline\fR +Underscore off. +.TP +\fB::term::ansi::code::ctrl::sda_noblink\fR +Blink off. +.TP +\fB::term::ansi::code::ctrl::sda_norevers\fR +Reverse off. +.TP +\fB::term::ansi::code::ctrl::sda_nohidden\fR +Hidden off. +.TP +\fB::term::ansi::code::ctrl::sda_nostrike\fR +Strike-through off. +.TP +\fB::term::ansi::code::ctrl::sda_reset\fR +Reset all attributes to their default values. +.TP +\fB::term::ansi::send::fcp\fR \fIrow\fR \fIcol\fR +Force Cursor Position (aka Go To). +.TP +\fB::term::ansi::code::ctrl::cu\fR ?\fIn\fR? +Cursor Up. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::code::ctrl::cd\fR ?\fIn\fR? +Cursor Down. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::code::ctrl::cf\fR ?\fIn\fR? +Cursor Forward. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::code::ctrl::cb\fR ?\fIn\fR? +Cursor Backward. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::code::ctrl::ss\fR ?\fIs\fR \fIe\fR? +Scroll Screen (entire display, or between rows start end, inclusive). +.TP +\fB::term::ansi::code::ctrl::skd\fR \fIcode\fR \fIstr\fR +Set Key Definition. +.TP +\fB::term::ansi::code::ctrl::title\fR \fIstr\fR +Set the terminal title. +.TP +\fB::term::ansi::code::ctrl::gron\fR +Switch to character/box graphics. I.e. switch to the alternate font. +.TP +\fB::term::ansi::code::ctrl::groff\fR +Switch to regular characters. I.e. switch to the default font. +.TP +\fB::term::ansi::code::ctrl::tlc\fR +Character graphics, Top Left Corner. +.TP +\fB::term::ansi::code::ctrl::trc\fR +Character graphics, Top Right Corner. +.TP +\fB::term::ansi::code::ctrl::brc\fR +Character graphics, Bottom Right Corner. +.TP +\fB::term::ansi::code::ctrl::blc\fR +Character graphics, Bottom Left Corner. +.TP +\fB::term::ansi::code::ctrl::ltj\fR +Character graphics, Left T Junction. +.TP +\fB::term::ansi::code::ctrl::ttj\fR +Character graphics, Top T Junction. +.TP +\fB::term::ansi::code::ctrl::rtj\fR +Character graphics, Right T Junction. +.TP +\fB::term::ansi::code::ctrl::btj\fR +Character graphics, Bottom T Junction. +.TP +\fB::term::ansi::code::ctrl::fwj\fR +Character graphics, Four-Way Junction. +.TP +\fB::term::ansi::code::ctrl::hl\fR +Character graphics, Horizontal Line. +.TP +\fB::term::ansi::code::ctrl::vl\fR +Character graphics, Vertical Line. +.TP +\fB::term::ansi::code::ctrl::groptim\fR \fIstr\fR +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. +.TP +\fB::term::ansi::code::ctrl::clear\fR +Clear screen. In essence a sequence of CursorHome + EraseDown. +.TP +\fB::term::ansi::code::ctrl::init\fR +Initialize default and alternate fonts to ASCII and box graphics. +.TP +\fB::term::ansi::code::ctrl::showat\fR \fIrow\fR \fIcol\fR \fItext\fR +Format the block of text for display at the specified location. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ansi, attribute control, color control, control, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ansi_cmacros.n Index: embedded/man/files/modules/term/ansi_cmacros.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_cmacros.n @@ -0,0 +1,312 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_cmacros.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::code::macros" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::code::macros \- Macro sequences +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBtextutil::repeat \fR +.sp +package require \fBtextutil::tabify \fR +.sp +package require \fBterm::ansi::code::macros ?0.1?\fR +.sp +\fB::term::ansi::code::macros::names\fR +.sp +\fB::term::ansi::code::macros::import\fR ?\fIns\fR? ?\fIarg\fR...? +.sp +\fB::term::ansi::code::macros::menu\fR \fImenu\fR +.sp +\fB::term::ansi::code::macros::frame\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +This package provides higher level control sequences for more complex +shapes. +.SH API +.SS INTROSPECTION +.TP +\fB::term::ansi::code::macros::names\fR +This command is for introspection. It returns as its result a list +containing the names of all attribute commands. +.TP +\fB::term::ansi::code::macros::import\fR ?\fIns\fR? ?\fIarg\fR...? +This command imports some or all attribute commands into the namespace +\fIns\fR. This is by default the namespace \fImacros\fR. 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. +.PP +.SS SEQUENCES +.TP +\fB::term::ansi::code::macros::menu\fR \fImenu\fR +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. +.sp +The description, \fImenu\fR, is a dictionary mapping from menu label +to command character. +.TP +\fB::term::ansi::code::macros::frame\fR \fIstring\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ansi, control, frame, menu, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ansi_code.n Index: embedded/man/files/modules/term/ansi_code.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_code.n @@ -0,0 +1,296 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_code.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::code" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::code \- Helper for control sequences +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::ansi::code ?0.1?\fR +.sp +\fB::term::ansi::code::esc\fR \fIstr\fR +.sp +\fB::term::ansi::code::escb\fR \fIstr\fR +.sp +\fB::term::ansi::code::define\fR \fIname\fR \fIescape\fR \fIcode\fR +.sp +\fB::term::ansi::code::const\fR \fIname\fR \fIcode\fR +.sp +.BE +.SH DESCRIPTION +This package provides commands enabling the definition of control +sequences in an easy manner. +.PP +.TP +\fB::term::ansi::code::esc\fR \fIstr\fR +This command returns the argument string, prefixed with the ANSI +escape character, "\\033." +.TP +\fB::term::ansi::code::escb\fR \fIstr\fR +This command returns the argument string, prefixed with a common ANSI +escape sequence, "\\033[". +.TP +\fB::term::ansi::code::define\fR \fIname\fR \fIescape\fR \fIcode\fR +This command defines a procedure \fIname\fR which returns the control +sequence \fIcode\fR, beginning with the specified escape sequence, +either \fBesc\fR, or \fBescb\fR. +.TP +\fB::term::ansi::code::const\fR \fIname\fR \fIcode\fR +This command defines a procedure \fIname\fR which returns the control +sequence \fIcode\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +control, declare, define, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ansi_ctrlu.n Index: embedded/man/files/modules/term/ansi_ctrlu.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_ctrlu.n @@ -0,0 +1,320 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_ctrlu.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::ctrl::unix" n 0.1.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::ctrl::unix \- Control operations and queries +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::ansi::ctrl::unix ?0.1.1?\fR +.sp +\fB::term::ansi::ctrl::unix::import\fR ?\fIns\fR? ?\fIarg\fR...? +.sp +\fB::term::ansi::ctrl::unix::raw\fR +.sp +\fB::term::ansi::ctrl::unix::raw\fR +.sp +\fB::term::ansi::ctrl::unix::columns\fR +.sp +\fB::term::ansi::ctrl::unix::rows\fR +.sp +.BE +.SH DESCRIPTION +\fIWARNING\fR: This package is unix-specific and depends on the +availability of two unix system commands for terminal control, +i.e. \fBstty\fR and \fBtput\fR, both of which have to be found +in the \fB$PATH\fR. If any of these two commands is missing the +loading of the package will fail. +.PP +The package provides commands to switch the standard input of the +current process between \fIraw\fR and \fIcooked\fR input modes, and +to query the size of terminals, i.e. the available number of columns +and lines. +.SH API +.SS INTROSPECTION +.TP +\fB::term::ansi::ctrl::unix::import\fR ?\fIns\fR? ?\fIarg\fR...? +This command imports some or all attribute commands into the namespace +\fIns\fR. This is by default the namespace \fIctrl\fR. 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. +.PP +.SS OPERATIONS +.TP +\fB::term::ansi::ctrl::unix::raw\fR +This command switches the standard input of the current process to +\fIraw\fR 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. +.TP +\fB::term::ansi::ctrl::unix::raw\fR +This command switches the standard input of the current process to +\fIcooked\fR 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. +.TP +\fB::term::ansi::ctrl::unix::columns\fR +This command queries the terminal connected to the standard input for +the number of columns available for display. +.TP +\fB::term::ansi::ctrl::unix::rows\fR +This command queries the terminal connected to the standard input for +the number of rows (aka lines) available for display. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +ansi, columns, control, cooked, input mode, lines, raw, rows, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ansi_send.n Index: embedded/man/files/modules/term/ansi_send.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ansi_send.n @@ -0,0 +1,748 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ansi_send.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::ansi::send" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::ansi::send \- Output of ANSI control sequences to terminals +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::ansi::send ?0.1?\fR +.sp +\fB::term::ansi::send::import\fR ?\fIns\fR? \fI...\fR +.sp +\fB::term::ansi::send::eeol\fR +.sp +\fB::term::ansi::send::esol\fR +.sp +\fB::term::ansi::send::el\fR +.sp +\fB::term::ansi::send::ed\fR +.sp +\fB::term::ansi::send::eu\fR +.sp +\fB::term::ansi::send::es\fR +.sp +\fB::term::ansi::send::sd\fR +.sp +\fB::term::ansi::send::su\fR +.sp +\fB::term::ansi::send::ch\fR +.sp +\fB::term::ansi::send::sc\fR +.sp +\fB::term::ansi::send::rc\fR +.sp +\fB::term::ansi::send::sca\fR +.sp +\fB::term::ansi::send::rca\fR +.sp +\fB::term::ansi::send::st\fR +.sp +\fB::term::ansi::send::ct\fR +.sp +\fB::term::ansi::send::cat\fR +.sp +\fB::term::ansi::send::qdc\fR +.sp +\fB::term::ansi::send::qds\fR +.sp +\fB::term::ansi::send::qcp\fR +.sp +\fB::term::ansi::send::rd\fR +.sp +\fB::term::ansi::send::elw\fR +.sp +\fB::term::ansi::send::dlw\fR +.sp +\fB::term::ansi::send::eg\fR +.sp +\fB::term::ansi::send::lg\fR +.sp +\fB::term::ansi::send::scs0\fR \fItag\fR +.sp +\fB::term::ansi::send::scs1\fR \fItag\fR +.sp +\fB::term::ansi::send::sda\fR \fIarg\fR... +.sp +\fB::term::ansi::send::sda_fgblack\fR +.sp +\fB::term::ansi::send::sda_fgred\fR +.sp +\fB::term::ansi::send::sda_fggreen\fR +.sp +\fB::term::ansi::send::sda_fgyellow\fR +.sp +\fB::term::ansi::send::sda_fgblue\fR +.sp +\fB::term::ansi::send::sda_fgmagenta\fR +.sp +\fB::term::ansi::send::sda_fgcyan\fR +.sp +\fB::term::ansi::send::sda_fgwhite\fR +.sp +\fB::term::ansi::send::sda_fgdefault\fR +.sp +\fB::term::ansi::send::sda_bgblack\fR +.sp +\fB::term::ansi::send::sda_bgred\fR +.sp +\fB::term::ansi::send::sda_bggreen\fR +.sp +\fB::term::ansi::send::sda_bgyellow\fR +.sp +\fB::term::ansi::send::sda_bgblue\fR +.sp +\fB::term::ansi::send::sda_bgmagenta\fR +.sp +\fB::term::ansi::send::sda_bgcyan\fR +.sp +\fB::term::ansi::send::sda_bgwhite\fR +.sp +\fB::term::ansi::send::sda_bgdefault\fR +.sp +\fB::term::ansi::send::sda_bold\fR +.sp +\fB::term::ansi::send::sda_dim\fR +.sp +\fB::term::ansi::send::sda_italic\fR +.sp +\fB::term::ansi::send::sda_underline\fR +.sp +\fB::term::ansi::send::sda_blink\fR +.sp +\fB::term::ansi::send::sda_revers\fR +.sp +\fB::term::ansi::send::sda_hidden\fR +.sp +\fB::term::ansi::send::sda_strike\fR +.sp +\fB::term::ansi::send::sda_nobold\fR +.sp +\fB::term::ansi::send::sda_noitalic\fR +.sp +\fB::term::ansi::send::sda_nounderline\fR +.sp +\fB::term::ansi::send::sda_noblink\fR +.sp +\fB::term::ansi::send::sda_norevers\fR +.sp +\fB::term::ansi::send::sda_nohidden\fR +.sp +\fB::term::ansi::send::sda_nostrike\fR +.sp +\fB::term::ansi::send::sda_reset\fR +.sp +\fB::term::ansi::send::fcp\fR \fIrow\fR \fIcol\fR +.sp +\fB::term::ansi::send::cu\fR ?\fIn\fR? +.sp +\fB::term::ansi::send::cd\fR ?\fIn\fR? +.sp +\fB::term::ansi::send::cf\fR ?\fIn\fR? +.sp +\fB::term::ansi::send::cb\fR ?\fIn\fR? +.sp +\fB::term::ansi::send::ss\fR ?\fIs\fR \fIe\fR? +.sp +\fB::term::ansi::send::skd\fR \fIcode\fR \fIstr\fR +.sp +\fB::term::ansi::send::title\fR \fIstr\fR +.sp +\fB::term::ansi::send::gron\fR +.sp +\fB::term::ansi::send::groff\fR +.sp +\fB::term::ansi::send::tlc\fR +.sp +\fB::term::ansi::send::trc\fR +.sp +\fB::term::ansi::send::brc\fR +.sp +\fB::term::ansi::send::blc\fR +.sp +\fB::term::ansi::send::ltj\fR +.sp +\fB::term::ansi::send::ttj\fR +.sp +\fB::term::ansi::send::rtj\fR +.sp +\fB::term::ansi::send::btj\fR +.sp +\fB::term::ansi::send::fwj\fR +.sp +\fB::term::ansi::send::hl\fR +.sp +\fB::term::ansi::send::vl\fR +.sp +\fB::term::ansi::send::groptim\fR \fIstr\fR +.sp +\fB::term::ansi::send::clear\fR +.sp +\fB::term::ansi::send::init\fR +.sp +\fB::term::ansi::send::showat\fR \fIrow\fR \fIcol\fR \fItext\fR +.sp +.BE +.SH 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 \fIstdout\fR. +.PP +The commands are defined using the control sequences provided by the package +\fBterm::ansi::code::ctrl\fR. 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 \fIstdout\fR. +.TP +\fB::term::ansi::send::import\fR ?\fIns\fR? \fI...\fR +Imports the commands of this package into the namespace \fIns\fR. If not specified +it defaults to \fIsend\fR. Note that this default is a relative namespace name, +i.e. the actual namespace will be created under the current namespace. +.sp +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. +.TP +\fB::term::ansi::send::eeol\fR +Erase (to) End Of Line. +.TP +\fB::term::ansi::send::esol\fR +Erase (to) Start Of Line. +.TP +\fB::term::ansi::send::el\fR +Erase (current) Line. +.TP +\fB::term::ansi::send::ed\fR +Erase Down (to bottom). +.TP +\fB::term::ansi::send::eu\fR +Erase Up (to top). +.TP +\fB::term::ansi::send::es\fR +Erase Screen. +.TP +\fB::term::ansi::send::sd\fR +Scroll Down. +.TP +\fB::term::ansi::send::su\fR +Scroll Up. +.TP +\fB::term::ansi::send::ch\fR +Cursor Home. +.TP +\fB::term::ansi::send::sc\fR +Save Cursor. Note: Only one saved position can be handled. +This is no unlimited stack. Saving before restoring will +overwrite the saved data. +.TP +\fB::term::ansi::send::rc\fR +Restore Cursor (Unsave). +.TP +\fB::term::ansi::send::sca\fR +Save Cursor + Attributes. +.TP +\fB::term::ansi::send::rca\fR +Restore Cursor + Attributes. +.TP +\fB::term::ansi::send::st\fR +Set Tab (@ current position). +.TP +\fB::term::ansi::send::ct\fR +Clear Tab (@ current position). +.TP +\fB::term::ansi::send::cat\fR +Clear All Tabs. +.TP +\fB::term::ansi::send::qdc\fR +Query Device Code. +.TP +\fB::term::ansi::send::qds\fR +Query Device Status. +.TP +\fB::term::ansi::send::qcp\fR +Query Cursor Position. +.TP +\fB::term::ansi::send::rd\fR +Reset Device. +.TP +\fB::term::ansi::send::elw\fR +Enable Line Wrap. +.TP +\fB::term::ansi::send::dlw\fR +Disable Line Wrap. +.TP +\fB::term::ansi::send::eg\fR +Enter Graphics Mode. +.TP +\fB::term::ansi::send::lg\fR +Exit Graphics Mode. +.TP +\fB::term::ansi::send::scs0\fR \fItag\fR +.TP +\fB::term::ansi::send::scs1\fR \fItag\fR +Select Character Set. +.sp +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. +.sp +The legal tags, and their meanings, are: +.RS +.TP +A +United Kingdom Set +.TP +B +ASCII Set +.TP +0 +Special Graphics +.TP +1 +Alternate Character ROM Standard Character Set +.TP +2 +Alternate Character ROM Special Graphics +.RE +.TP +\fB::term::ansi::send::sda\fR \fIarg\fR... +Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package \fBterm::ansi::code::attr\fR. For +convenience this package also provides additional commands each setting a single +specific attribute. +.TP +\fB::term::ansi::send::sda_fgblack\fR +Set text color to \fIBlack\fR. +.TP +\fB::term::ansi::send::sda_fgred\fR +Set text color to \fIRed\fR. +.TP +\fB::term::ansi::send::sda_fggreen\fR +Set text color to \fIGreen\fR. +.TP +\fB::term::ansi::send::sda_fgyellow\fR +Set text color to \fIYellow\fR. +.TP +\fB::term::ansi::send::sda_fgblue\fR +Set text color to \fIBlue\fR. +.TP +\fB::term::ansi::send::sda_fgmagenta\fR +Set text color to \fIMagenta\fR. +.TP +\fB::term::ansi::send::sda_fgcyan\fR +Set text color to \fICyan\fR. +.TP +\fB::term::ansi::send::sda_fgwhite\fR +Set text color to \fIWhite\fR. +.TP +\fB::term::ansi::send::sda_fgdefault\fR +Set default text color (\fIBlack\fR). +.TP +\fB::term::ansi::send::sda_bgblack\fR +Set background to \fIBlack\fR. +.TP +\fB::term::ansi::send::sda_bgred\fR +Set background to \fIRed\fR. +.TP +\fB::term::ansi::send::sda_bggreen\fR +Set background to \fIGreen\fR. +.TP +\fB::term::ansi::send::sda_bgyellow\fR +Set background to \fIYellow\fR. +.TP +\fB::term::ansi::send::sda_bgblue\fR +Set background to \fIBlue\fR. +.TP +\fB::term::ansi::send::sda_bgmagenta\fR +Set background to \fIMagenta\fR. +.TP +\fB::term::ansi::send::sda_bgcyan\fR +Set background to \fICyan\fR. +.TP +\fB::term::ansi::send::sda_bgwhite\fR +Set background to \fIWhite\fR. +.TP +\fB::term::ansi::send::sda_bgdefault\fR +Set default background (Transparent). +.TP +\fB::term::ansi::send::sda_bold\fR +Bold on. +.TP +\fB::term::ansi::send::sda_dim\fR +Dim on. +.TP +\fB::term::ansi::send::sda_italic\fR +Italics on. +.TP +\fB::term::ansi::send::sda_underline\fR +Underscore on. +.TP +\fB::term::ansi::send::sda_blink\fR +Blink on. +.TP +\fB::term::ansi::send::sda_revers\fR +Reverse on. +.TP +\fB::term::ansi::send::sda_hidden\fR +Hidden on. +.TP +\fB::term::ansi::send::sda_strike\fR +Strike-through on. +.TP +\fB::term::ansi::send::sda_nobold\fR +Bold off. +.TP +\fB::term::ansi::send::sda_noitalic\fR +Italics off. +.TP +\fB::term::ansi::send::sda_nounderline\fR +Underscore off. +.TP +\fB::term::ansi::send::sda_noblink\fR +Blink off. +.TP +\fB::term::ansi::send::sda_norevers\fR +Reverse off. +.TP +\fB::term::ansi::send::sda_nohidden\fR +Hidden off. +.TP +\fB::term::ansi::send::sda_nostrike\fR +Strike-through off. +.TP +\fB::term::ansi::send::sda_reset\fR +Reset all attributes to their default values. +.TP +\fB::term::ansi::send::fcp\fR \fIrow\fR \fIcol\fR +Force Cursor Position (aka Go To). +.TP +\fB::term::ansi::send::cu\fR ?\fIn\fR? +Cursor Up. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::send::cd\fR ?\fIn\fR? +Cursor Down. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::send::cf\fR ?\fIn\fR? +Cursor Forward. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::send::cb\fR ?\fIn\fR? +Cursor Backward. \fIn\fR defaults to 1. +.TP +\fB::term::ansi::send::ss\fR ?\fIs\fR \fIe\fR? +Scroll Screen (entire display, or between rows start end, inclusive). +.TP +\fB::term::ansi::send::skd\fR \fIcode\fR \fIstr\fR +Set Key Definition. +.TP +\fB::term::ansi::send::title\fR \fIstr\fR +Set the terminal title. +.TP +\fB::term::ansi::send::gron\fR +Switch to character/box graphics. I.e. switch to the alternate font. +.TP +\fB::term::ansi::send::groff\fR +Switch to regular characters. I.e. switch to the default font. +.TP +\fB::term::ansi::send::tlc\fR +Character graphics, Top Left Corner. +.TP +\fB::term::ansi::send::trc\fR +Character graphics, Top Right Corner. +.TP +\fB::term::ansi::send::brc\fR +Character graphics, Bottom Right Corner. +.TP +\fB::term::ansi::send::blc\fR +Character graphics, Bottom Left Corner. +.TP +\fB::term::ansi::send::ltj\fR +Character graphics, Left T Junction. +.TP +\fB::term::ansi::send::ttj\fR +Character graphics, Top T Junction. +.TP +\fB::term::ansi::send::rtj\fR +Character graphics, Right T Junction. +.TP +\fB::term::ansi::send::btj\fR +Character graphics, Bottom T Junction. +.TP +\fB::term::ansi::send::fwj\fR +Character graphics, Four-Way Junction. +.TP +\fB::term::ansi::send::hl\fR +Character graphics, Horizontal Line. +.TP +\fB::term::ansi::send::vl\fR +Character graphics, Vertical Line. +.TP +\fB::term::ansi::send::groptim\fR \fIstr\fR +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. +.TP +\fB::term::ansi::send::clear\fR +Clear screen. In essence a sequence of CursorHome + EraseDown. +.TP +\fB::term::ansi::send::init\fR +Initialize default and alternate fonts to ASCII and box graphics. +.TP +\fB::term::ansi::send::showat\fR \fIrow\fR \fIcol\fR \fItext\fR +Show the block of text at the specified location. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +character output, control, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/imenu.n Index: embedded/man/files/modules/term/imenu.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/imenu.n @@ -0,0 +1,387 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/imenu.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::interact::menu" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::interact::menu \- Terminal widget, menu +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::interact::menu ?0.1?\fR +.sp +\fBterm::interact::menu\fR \fIobject\fR \fIdict\fR ?\fIoptions\fR...? +.sp +\fIobject\fR \fBinteract\fR +.sp +\fIobject\fR \fBdone\fR +.sp +\fIobject\fR \fBclear\fR +.sp +\fIobject\fR \fBconfigure\fR +.sp +\fIobject\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobject\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fIobject\fR \fBcget\fR \fIoption\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for the creation of a simple menu +control. +.SH "CLASS API" +The package exports a single command, the class command, enabling the +creation of menu instances. Its API is: +.TP +\fBterm::interact::menu\fR \fIobject\fR \fIdict\fR ?\fIoptions\fR...? +This command creates a new menu object with the name \fIobject\fR, +initializes it, and returns the fully qualified name of the object +command as its result. +.sp +The argument is the menu to show, possibly followed by configuration +options and their values. The options are explained in the section +\fBConfiguration\fR. The menu is a dictionary maping labels +to symbolic action codes. +.PP +.SH "OBJECT API" +The objects created by the class command provide the methods listed +below: +.TP +\fIobject\fR \fBinteract\fR +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 \fBInteraction\fR for a description of the +possible interaction. +.sp +The method returns the symbolic action of the menu item selected by +the user at the end of the interaction. +.TP +\fIobject\fR \fBdone\fR +This method can be used by user supplied actions to terminate the +interaction with the object. +.TP +\fIobject\fR \fBclear\fR +This method can be used by user supplied actions to remove the menu +from the terminal. +.TP +\fIobject\fR \fBconfigure\fR +.TP +\fIobject\fR \fBconfigure\fR \fIoption\fR +.TP +\fIobject\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.TP +\fIobject\fR \fBcget\fR \fIoption\fR +Standard methods to retrieve and configure the options of the menu. +.PP +.SH CONFIGURATION +A menu instance recognizes the following options: +.TP +\fB-in\fR chan +Specifies the channel to read character sequences from. Defaults to +\fBstdin\fR. +.TP +\fB-out\fR chan +Specifies the channel to write the menu contents to. Defaults to +\fBstdout\fR. +.TP +\fB-column\fR 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. +.TP +\fB-line\fR 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. +.TP +\fB-height\fR int +Specifies the number of lines of text to show at most in the +display. Defaults to 25. +.TP +\fB-actions\fR dict +Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section \fBInteraction\fR. +.TP +\fB-hilitleft\fR int +.TP +\fB-hilitright\fR 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. +.TP +\fB-framed\fR 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. +.PP +.SH 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. +.TP +Cursor Up +The selection is moved up one entry, except if the first entry of the +menu is already selected. +.TP +Cursor Down +The selection is moved down one entry, except if the last entry of the +menu is already selected. +.TP +Enter/Return +The interaction with the object is terminated. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +control, menu, terminal, text display +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/ipager.n Index: embedded/man/files/modules/term/ipager.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/ipager.n @@ -0,0 +1,388 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/ipager.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::interact::pager" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::interact::pager \- Terminal widget, paging +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::interact::pager ?0.1?\fR +.sp +\fBterm::interact::pager\fR \fIobject\fR \fItext\fR ?\fIoptions\fR...? +.sp +\fIobject\fR \fBinteract\fR +.sp +\fIobject\fR \fBdone\fR +.sp +\fIobject\fR \fBclear\fR +.sp +\fIobject\fR \fBtext\fR \fItext\fR +.sp +\fIobject\fR \fBconfigure\fR +.sp +\fIobject\fR \fBconfigure\fR \fIoption\fR +.sp +\fIobject\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.sp +\fIobject\fR \fBcget\fR \fIoption\fR +.sp +.BE +.SH DESCRIPTION +This package provides a class for the creation of a simple paging +text display. +.SH "CLASS API" +The package exports a single command, the class command, enabling the +creation of pager instances. Its API is: +.TP +\fBterm::interact::pager\fR \fIobject\fR \fItext\fR ?\fIoptions\fR...? +This command creates a new pager object with the name \fIobject\fR, +initializes it, and returns the fully qualified name of the object +command as its result. +.sp +The argument is the text to show, possibly followed by configuration +options and their values. The options are explained in the section +\fBConfiguration\fR. +.PP +.SH "OBJECT API" +The objects created by the class command provide the methods listed +below: +.TP +\fIobject\fR \fBinteract\fR +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 \fBInteraction\fR for a description of the +possible interaction. +.TP +\fIobject\fR \fBdone\fR +This method can be used by user supplied actions to terminate the +interaction with the object. +.TP +\fIobject\fR \fBclear\fR +This method can be used by user supplied actions to remove the pager +from the terminal. +.TP +\fIobject\fR \fBtext\fR \fItext\fR +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. +.TP +\fIobject\fR \fBconfigure\fR +.TP +\fIobject\fR \fBconfigure\fR \fIoption\fR +.TP +\fIobject\fR \fBconfigure\fR \fIoption\fR \fIvalue\fR... +.TP +\fIobject\fR \fBcget\fR \fIoption\fR +Standard methods to retrieve and configure the options of the pager. +.PP +.SH CONFIGURATION +A pager instance recognizes the following options: +.TP +\fB-in\fR chan +Specifies the channel to read character sequences from. Defaults to +\fBstdin\fR. +.TP +\fB-out\fR chan +Specifies the channel to write the pager contents to. Defaults to +\fBstdout\fR. +.TP +\fB-column\fR 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. +.TP +\fB-line\fR 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. +.TP +\fB-height\fR int +Specifies the number of lines of text to show at most in the +display. Defaults to 25. +.TP +\fB-actions\fR dict +Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section \fBInteraction\fR. +.PP +.SH 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. +.TP +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. +.TP +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. +.TP +Page Up +The text is scrolled down a page. The pager will not react if the +first line of the text is already shown. +.TP +Page Down +The text is scrolled up a page. The pager will not react if the last +line of the text is already shown. +.TP +Enter/Return +The interaction with the object is terminated. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +control, pager, terminal, text display +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/receive.n Index: embedded/man/files/modules/term/receive.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/receive.n @@ -0,0 +1,316 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/receive.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::receive" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::receive \- General input from terminals +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::receive ?0.1?\fR +.sp +\fB::term::receive::getch\fR ?\fIchan\fR? +.sp +\fB::term::receive::listen\fR \fIcmd\fR ?\fIchan\fR? +.sp +\fIcmd\fR \fBprocess\fR \fIstring\fR +.sp +\fIcmd\fR \fBeof\fR +.sp +\fB::term::receive::unlisten\fR ?\fIchan\fR? +.sp +.BE +.SH DESCRIPTION +This package provides the most primitive commands for receiving +characters to a terminal. They are in essence convenient wrappers +around the builtin commands \fBread\fR and \fBfileevent\fR. +.TP +\fB::term::receive::getch\fR ?\fIchan\fR? +This command reads a single character from the channel with handle +\fIchan\fR and returns it as the result of the command. +.sp +If not specified \fIchan\fR defaults to \fBstdin\fR. +.sp +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 \fBterm::ansi::ctrl::unix\fR. +.TP +\fB::term::receive::listen\fR \fIcmd\fR ?\fIchan\fR? +This command sets up a filevent listener for the channel with handle +\fIchan\fR and invokes the command prefix \fIcmd\fR whenever +characters have been received, or EOF was reached. +.sp +If not specified \fIchan\fR defaults to \fBstdin\fR. +.sp +The signature of the command prefix is +.RS +.TP +\fIcmd\fR \fBprocess\fR \fIstring\fR +This method is invoked when characters were received, and \fIstring\fR +holds them for processing. +.TP +\fIcmd\fR \fBeof\fR +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. +.RE +.TP +\fB::term::receive::unlisten\fR ?\fIchan\fR? +This command disables the filevent listener for the channel with handle +\fIchan\fR. +.sp +If not specified \fIchan\fR defaults to \fBstdin\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +character input, control, get character, listener, receiver, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/term.n Index: embedded/man/files/modules/term/term.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/term.n @@ -0,0 +1,271 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/term.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term \- General terminal control +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm ?0.1?\fR +.sp +.BE +.SH 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +control, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/term_bind.n Index: embedded/man/files/modules/term/term_bind.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/term_bind.n @@ -0,0 +1,360 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/term_bind.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::receive::bind" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::receive::bind \- Keyboard dispatch from terminals +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::receive::bind ?0.1?\fR +.sp +\fBterm::receive::bind\fR \fIobject\fR ?\fImap\fR? +.sp +\fIobject\fR \fBmap\fR \fIstr\fR \fIcmd\fR +.sp +\fIobject\fR \fBdefault\fR \fIcmd\fR +.sp +\fIobject\fR \fBlisten\fR ?\fIchan\fR? +.sp +\fIobject\fR \fBunlisten\fR ?\fIchan\fR? +.sp +\fIobject\fR \fBreset\fR +.sp +\fIobject\fR \fBnext\fR \fIchar\fR +.sp +\fIobject\fR \fBprocess\fR \fIstr\fR +.sp +\fIobject\fR \fBeof\fR +.sp +.BE +.SH 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. +.SH "CLASS API" +The package exports a single command, the +class command, enabling the creation of +dispatcher instances. Its API +is: +.TP +\fBterm::receive::bind\fR \fIobject\fR ?\fImap\fR? +This command creates a new dispatcher object with the name +\fIobject\fR, initializes it, and returns the fully qualified name of +the object command as its result. +.sp +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. +.PP +.SH "OBJECT API" +The objects created by the class command provide the methods listed +below: +.TP +\fIobject\fR \fBmap\fR \fIstr\fR \fIcmd\fR +This method adds an additional mapping from the string \fIstr\fR to +the action \fIcmd\fR. The mapping will take effect immediately +should the processor be in a prefix of \fIstr\fR, 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. +.TP +\fIobject\fR \fBdefault\fR \fIcmd\fR +This method defines a default action \fIcmd\fR 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 \fBmap\fR. +.TP +\fIobject\fR \fBlisten\fR ?\fIchan\fR? +This methods sets up a filevent listener for the channel with handle +\fIchan\fR and invokes the dispatcher object whenever characters have +been received, or EOF was reached. +.sp +If not specified \fIchan\fR defaults to \fBstdin\fR. +.TP +\fIobject\fR \fBunlisten\fR ?\fIchan\fR? +This methods removes the filevent listener for the channel with handle +\fIchan\fR. +.sp +If not specified \fIchan\fR defaults to \fBstdin\fR. +.TP +\fIobject\fR \fBreset\fR +This method resets the character processor +to the beginning of the tree. +.TP +\fIobject\fR \fBnext\fR \fIchar\fR +This method causes the character processor to process the character +\fIc\fR. This may simply advance the internal state, or invoke an +associated action for a recognized sequence. +.TP +\fIobject\fR \fBprocess\fR \fIstr\fR +This method causes the character processor to process the character +sequence \fIstr\fR, advancing the internal state and invoking action +as necessary. This is a callback for \fBlisten\fR. +.TP +\fIobject\fR \fBeof\fR +This method causes the character processor to handle EOF on the +input. This is currently no-op. +This is a callback for \fBlisten\fR. +.PP +.SH 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. +.PP +In other words, the set of recognized strings has to form a +\fIprefix code\fR. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +character input, control, dispatcher, listener, receiver, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/term/term_send.n Index: embedded/man/files/modules/term/term_send.n ================================================================== --- /dev/null +++ embedded/man/files/modules/term/term_send.n @@ -0,0 +1,286 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/term/term_send.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "term::send" n 0.1 tcllib "Terminal control" +.BS +.SH NAME +term::send \- General output to terminals +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBterm::send ?0.1?\fR +.sp +\fB::term::send::wrch\fR \fIchan\fR \fIstr\fR +.sp +\fB::term::send::wr\fR \fIstr\fR +.sp +.BE +.SH DESCRIPTION +This package provides the most primitive commands for sending characters +to a terminal. They are in essence convenient wrappers around the +builtin command \fBputs\fR. +.TP +\fB::term::send::wrch\fR \fIchan\fR \fIstr\fR +Send the text \fIstr\fR to the channel specified by the handle \fIchan\fR. +In contrast to the builtin command \fBputs\fR 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. +.TP +\fB::term::send::wr\fR \fIstr\fR +This convenience command is like \fB::term::send::wrch\fR, except that the +destination channel is fixed to \fIstdout\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIterm\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +character output, control, terminal +.SH CATEGORY +Terminal control +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/textutil/adjust.n Index: embedded/man/files/modules/textutil/adjust.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/adjust.n @@ -0,0 +1,415 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/adjust.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::adjust" n 0.7.1 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::adjust \- Procedures to adjust, indent, and undent paragraphs +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::adjust ?0.7.1?\fR +.sp +\fB::textutil::adjust::adjust\fR \fIstring\fR ?\fIoption value...\fR? +.sp +\fB::textutil::adjust::readPatterns\fR \fIfilename\fR +.sp +\fB::textutil::adjust::listPredefined\fR +.sp +\fB::textutil::adjust::getPredefined\fR \fIfilename\fR +.sp +\fB::textutil::adjust::indent\fR \fIstring\fR \fIprefix\fR ?\fIskip\fR? +.sp +\fB::textutil::adjust::undent\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::adjust\fR provides commands that manipulate +strings or texts (a.k.a. long strings or string with embedded newlines +or paragraphs), adjusting, or indenting them. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::adjust::adjust\fR \fIstring\fR ?\fIoption value...\fR? +Do a justification on the \fIstring\fR 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. +.sp +Together with \fB::textutil::adjust::indent\fR it is possible to +create properly wrapped paragraphs with arbitrary indentations. +.sp +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 +\fIreal\fR line. +Each \fIreal\fR line is placed in a \fIlogical\fR line, which has +exactly a given length (see the option \fB-length\fR below). +The \fIreal\fR line may be shorter. Again by default, trailing spaces +are ignored before returning the string (see the option \fB-full\fR +below). +.sp +The following options may be used after the \fIstring\fR parameter, +and change the way the command places a \fIreal\fR line in a +\fIlogical\fR line. +.RS +.TP +\fB-full\fR \fIboolean\fR +If set to \fBfalse\fR (default), trailing space characters are +deleted before returning the string. If set to \fBtrue\fR, any +trailing space characters are left in the string. +.TP +\fB-hyphenate\fR \fIboolean\fR +If set to \fBfalse\fR (default), no hyphenation will be done. If set +to \fBtrue\fR, the command will try to hyphenate the last word of a +line. \fINote\fR: Hyphenation patterns must be loaded prior, using +the command \fB::textutil::adjust::readPatterns\fR. +.TP +\fB-justify\fR \fBcenter|left|plain|right\fR +Sets the justification of the returned string to either \fBleft\fR +(default), \fBcenter\fR, \fBplain\fR or \fBright\fR. 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 \fBplain\fR and the number of +printable chars in the last line is less than 90% of the length of a +line (see the option \fB-length\fR), then this line is justified +with the \fBleft\fR value, avoiding the expansion of this line when +it is too small. The meaning of each value is: +.RS +.TP +\fBcenter\fR +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 \fB-full\fR). +.TP +\fBleft\fR +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 \fB-full\fR). +.TP +\fBplain\fR +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 \fIreal\fR line, between 2 (or more) words. +.TP +\fBright\fR +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 \fB-full\fR option. +.RE +.TP +\fB-length\fR \fIinteger\fR +Set the length of the \fIlogical\fR line in the string to +\fIinteger\fR. \fIinteger\fR must be a positive integer +value. Defaults to \fB72\fR. +.TP +\fB-strictlength\fR +\fIboolean\fR] +If set to \fBfalse\fR (default), a line can exceed the specified +\fB-length\fR if a single word is longer than \fB-length\fR. If +set to \fBtrue\fR, words that are longer than \fB-length\fR are +split so that no line exceeds the specified \fB-length\fR. +.RE +.TP +\fB::textutil::adjust::readPatterns\fR \fIfilename\fR +Loads the internal storage for hyphenation patterns with the contents +of the file \fIfilename\fR. This has to be done prior to calling +command \fB::textutil::adjust::adjust\fR with "\fB-hyphenate\fR +\fBtrue\fR", or the hyphenation process will not work correctly. +.sp +The package comes with a number of predefined pattern files, and the +command \fB::textutil::adjust::listPredefined\fR can be used to find +out their names. +.TP +\fB::textutil::adjust::listPredefined\fR +This command returns a list containing the names of the hyphenation +files coming with this package. +.TP +\fB::textutil::adjust::getPredefined\fR \fIfilename\fR +Use this command to query the package for the full path name of the +hyphenation file \fIfilename\fR coming with the package. Only the +filenames found in the list returned by +\fB::textutil::adjust::listPredefined\fR are legal arguments for this +command. +.TP +\fB::textutil::adjust::indent\fR \fIstring\fR \fIprefix\fR ?\fIskip\fR? +Each line in the \fIstring\fR is indented by adding the string +\fIprefix\fR at its beginning. The modified string is returned +as the result of the command. +.sp +If \fIskip\fR is specified the first \fIskip\fR lines are left +untouched. The default for \fIskip\fR is \fB0\fR, causing the +modification of all lines. Negative values for \fIskip\fR are treated +like \fB0\fR. In other words, \fIskip\fR > \fB0\fR creates a +hanging indentation. +.sp +Together with \fB::textutil::adjust::adjust\fR it is possible to +create properly wrapped paragraphs with arbitrary indentations. +.TP +\fB::textutil::adjust::undent\fR \fIstring\fR +The command computes the common prefix for all lines in \fIstring\fR +consisting solely out of whitespace, removes this from each line and +returns the modified string. +.sp +Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove. +.sp +Together with \fB::textutil::adjust::adjust\fR it is possible to +create properly wrapped paragraphs with arbitrary indentations. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +TeX, adjusting, formatting, hyphenation, indenting, justification, paragraph, string, undenting +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/expander.n Index: embedded/man/files/modules/textutil/expander.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/expander.n @@ -0,0 +1,724 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/expander.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) William H. Duquette, http://www.wjduquette.com/expand +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::expander" n 1.3.1 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::expander \- Procedures to process templates and expand text. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::expander ?1.3.1?\fR +.sp +\fB::textutil::expander\fR \fIexpanderName\fR +.sp +\fIexpanderName\fR \fBcappend\fR \fItext\fR +.sp +\fIexpanderName\fR \fBcget\fR \fIvarname\fR +.sp +\fIexpanderName\fR \fBcis\fR \fIcname\fR +.sp +\fIexpanderName\fR \fBcname\fR +.sp +\fIexpanderName\fR \fBcpop\fR \fIcname\fR +.sp +\fIexpanderName\fR \fBctopandclear\fR +.sp +\fIexpanderName\fR \fBcpush\fR \fIcname\fR +.sp +\fIexpanderName\fR \fBcset\fR \fIvarname\fR \fIvalue\fR +.sp +\fIexpanderName\fR \fBcvar\fR \fIvarname\fR +.sp +\fIexpanderName\fR \fBerrmode\fR \fInewErrmode\fR +.sp +\fIexpanderName\fR \fBevalcmd\fR ?\fInewEvalCmd\fR? +.sp +\fIexpanderName\fR \fBexpand\fR \fIstring\fR ?\fIbrackets\fR? +.sp +\fIexpanderName\fR \fBlb\fR ?\fInewbracket\fR? +.sp +\fIexpanderName\fR \fBrb\fR ?\fInewbracket\fR? +.sp +\fIexpanderName\fR \fBreset\fR +.sp +\fIexpanderName\fR \fBsetbrackets\fR \fIlbrack rbrack\fR +.sp +\fIexpanderName\fR \fBtextcmd\fR ?\fInewTextCmd\fR? +.sp +\fIexpanderName\fR \fBwhere\fR +.sp +.BE +.SH DESCRIPTION +.PP +The Tcl \fBsubst\fR command is often used to support a kind of +template processing. Given a string with embedded variables or +function calls, \fBsubst\fR will interpolate the variable and function +values, returning the new string: +.PP +.CS + + + % set greeting "Howdy" + Howdy + % proc place {} {return "World"} + % subst {$greeting, [place]!} + Howdy, World! + % + +.CE +.PP +By defining a suitable set of Tcl commands, \fBsubst\fR can be used to +implement a markup language similar to HTML. +.PP +The \fBsubst\fR command is efficient, but it has three drawbacks for +this kind of template processing: +.IP \(bu +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. +.IP \(bu +Embedded commands are necessarily bracketed by \fB[\fR and +\fB]\fR; 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 \fB<<\fR +and \fB>>\fR as the embedded code delimiters instead. +.IP \(bu +There's no easy way to handle incremental input, as one might wish to +do when reading data from a socket. +.PP +.PP +At present, expander solves the first two problems; eventually it will +solve the third problem as well. +.PP +The following section describes the command API to the expander; this +is followed by the tutorial sections, see \fBTUTORIAL\fR. +.SH "EXPANDER API" +.PP +The \fBtextutil::expander\fR 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. +.TP +\fB::textutil::expander\fR \fIexpanderName\fR +The command creates a new expander object with an associated Tcl +command whose name is \fIexpanderName\fR. This command may be used to +invoke various operations on the graph. If the \fIexpanderName\fR is +not fully qualified it is interpreted as relative to the current +namespace. The command has the following general form: +.CS + + +\fIexpanderName\fR option ?\fIarg arg ...\fR? + +.CE +.IP +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.PP +.PP +The following commands are possible for expander objects: +.TP +\fIexpanderName\fR \fBcappend\fR \fItext\fR +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. +.TP +\fIexpanderName\fR \fBcget\fR \fIvarname\fR +Retrieves the value of variable \fIvarname\fR, defined in the current +context. +.TP +\fIexpanderName\fR \fBcis\fR \fIcname\fR +Determines whether or not the name of the current context is +\fIcname\fR. +.TP +\fIexpanderName\fR \fBcname\fR +Returns the name of the current context. +.TP +\fIexpanderName\fR \fBcpop\fR \fIcname\fR +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named \fIcname\fR, or an +error results. +.TP +\fIexpanderName\fR \fBctopandclear\fR +Returns the output currently captured in the topmost context and +clears that buffer. This is similar to a combination of \fBcpop\fR +followed by \fBcpush\fR, except that internal state (brackets) is +preserved here. +.TP +\fIexpanderName\fR \fBcpush\fR \fIcname\fR +Pushes a context named \fIcname\fR onto the context stack. The +context must be popped by \fBcpop\fR before expansion ends or an +error results. +.TP +\fIexpanderName\fR \fBcset\fR \fIvarname\fR \fIvalue\fR +Sets variable \fIvarname\fR to \fIvalue\fR in the current context. +.TP +\fIexpanderName\fR \fBcvar\fR \fIvarname\fR +Retrieves the internal variable name of context variable +\fIvarname\fR; this allows the variable to be passed to commands like +\fBlappend\fR. +.TP +\fIexpanderName\fR \fBerrmode\fR \fInewErrmode\fR +Sets the macro expansion error mode to one of \fBnothing\fR, +\fBmacro\fR, \fBerror\fR, or \fBfail\fR; the default value is +\fBfail\fR. The value determines what the expander does if an +error is detected during expansion of a macro. +.RS +.TP +\fBfail\fR +The error propagates normally and can be caught or ignored by the +application. +.TP +\fBerror\fR +The macro expands into a detailed error message, and expansion +continues. +.TP +\fBmacro\fR +The macro expands to itself; that is, it is passed along to the output +unchanged. +.TP +\fBnothing\fR +The macro expands to the empty string, and is effectively ignored. +.RE +.sp +.TP +\fIexpanderName\fR \fBevalcmd\fR ?\fInewEvalCmd\fR? +Returns the current evaluation command, which defaults to +\fBuplevel #0\fR. If specified, \fInewEvalCmd\fR will be saved for +future use and then returned; it must be a Tcl command expecting one +additional argument: the macro to evaluate. +.TP +\fIexpanderName\fR \fBexpand\fR \fIstring\fR ?\fIbrackets\fR? +Expands the input string, replacing embedded macros with their +expanded values, and returns the expanded string. +.sp +If \fIbrackets\fR 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. +.TP +\fIexpanderName\fR \fBlb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the new +bracket, and is returned. +.TP +\fIexpanderName\fR \fBrb\fR ?\fInewbracket\fR? +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 \fInewbracket\fR is specified, it becomes the +new bracket, and is returned. +.TP +\fIexpanderName\fR \fBreset\fR +Resets all expander settings to their initial values. Unusual results +are likely if this command is called from within a call to +\fBexpand\fR. +.TP +\fIexpanderName\fR \fBsetbrackets\fR \fIlbrack rbrack\fR +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 \fB[\fR and +\fB]\fR, but any non-empty string can be used; for example, +\fB<\fR and \fB>\fR or \fB(*\fR and \fB*)\fR or even +\fBHello,\fR and \fBWorld!\fR. +.TP +\fIexpanderName\fR \fBtextcmd\fR ?\fInewTextCmd\fR? +Returns the current command for processing plain text, which defaults +to the empty string, meaning \fIidentity\fR. If specified, +\fInewTextCmd\fR 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. +.sp +\fINote\fR that the combination of "\fBtextcmd\fR \fIplaintext\fR" +is run through the \fIevalcmd\fR for the actual evaluation. In other +words, the \fItextcmd\fR is treated as a special macro implicitly +surrounding all plain text in the template. +.TP +\fIexpanderName\fR \fBwhere\fR +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. +.PP +.SH TUTORIAL +.SS BASICS +To begin, create an expander object: +.PP +.CS + + + % package require expander + 1.2 + % ::expander::expander myexp + ::myexp + % + +.CE +.PP +The created \fB::myexp\fR 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: +.PP +.CS + + + % set greeting "Howdy" + Howdy + % proc place {} {return "World"} + % ::myexp expand {[set greeting], [place]!} + Howdy, World! + % + +.CE +.SS "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, +.PP +.CS + + + % 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! + % + +.CE +.SS "WRITING MACRO COMMANDS" +More typically, \fImacro commands\fR 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: +.PP +.CS + + + % proc bold {} {return "<b>"} + % proc /bold {} {return "</b>"} + % ::myexp expand {Some of this text is in [bold]boldface[/bold]} + Some of this text is in <b>boldface</b> + % + +.CE +.PP +The above definitions of \fBbold\fR and \fB/bold\fR 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. +.SS "CHANGING THE EXPANSION BRACKETS" +By default, embedded macros are enclosed in square brackets, +\fB[\fR and \fB]\fR. If square brackets need to be +included in the output, the input can contain the \fBlb\fR and +\fBrb\fR 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. +.PP +The \fBsetbrackets\fR command changes the brackets permanently. +For example, you can write pseudo-html by change them to \fB<\fR +and \fB>\fR: +.PP +.CS + + + % ::myexp setbrackets < > + % ::myexp expand {<bold>This is boldface</bold>} + <b>This is boldface</b> + +.CE +.PP +Alternatively, you can change the expansion brackets temporarily by +passing the desired brackets to the \fBexpand\fR command: +.PP +.CS + + + % ::myexp setbrackets "\\\\[" "\\\\]" + % ::myexp expand {<bold>This is boldface</bold>} {< >} + <b>This is boldface</b> + % + +.CE +.SS "CUSTOMIZED MACRO EXPANSION" +By default, macros are evaluated using the Tcl \fBuplevel #0\fR +command, so that the embedded code executes in the global context. +The application can provide a different evaluation command using +\fBevalcmd\fR; 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. +.PP +For example, the following code "evaluates" each macro by returning +the macro text itself. +.PP +.CS + + + proc identity {macro} {return $macro} + ::myexp evalcmd identity + +.CE +.SS "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: +.PP +.CS + + + Dr. Pangloss, however, thinks that this is the best of all + possible worlds.[footnote "See Candide, by Voltaire"] + +.CE +.PP +The \fBfootnote\fR 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: +.PP +.CS + + + Dr. Pangloss, however, thinks that this is the best of all + possible worlds.[footnote]See [bookTitle "Candide"], by + [authorsName "Voltaire"], for more information.[/footnote] + +.CE +.PP +Here the footnote text is contained between \fBfootnote\fR and +\fB/footnote\fR 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. +.PP +All macro expansion takes place in a particular context. Here, the +\fBfootnote\fR macro pushes a new context onto the context stack. +Then, all expanded text gets placed in that new context. +\fB/footnote\fR retrieves it by popping the context. Here's a +skeleton implementation of these two macros: +.PP +.CS + + + proc footnote {} { + ::myexp cpush footnote + } + + proc /footnote {} { + set footnoteText [::myexp cpop footnote] + + # Save the footnote text, and return an appropriate footnote + # number and link. + } + +.CE +.PP +The \fBcpush\fR 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, \fBcpop\fR +verifies that the current context has the expected name, pops it off +of the stack, and returns the accumulated text. +.PP +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 +\fBcpush\fR, the first macro can define one or more context +variables; the second macro can retrieve their values any time before +calling \fBcpop\fR. For example, suppose the document must specify +the footnote number explicitly: +.PP +.CS + + + 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. + } + +.CE +.PP +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 \fBcis\fR +or \fBcname\fR. +.SH HISTORY +\fBexpander\fR was written by William H. Duquette; it is a repackaging +of the central algorithm of the expand macro processing tool. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil :: expander\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +\fIhttp://www.wjduquette.com/expand\fR, regexp, split, string +.SH KEYWORDS +string, template processing, text expansion +.SH CATEGORY +Documentation tools +.SH COPYRIGHT +.nf +Copyright (c) William H. Duquette, http://www.wjduquette.com/expand + +.fi ADDED embedded/man/files/modules/textutil/repeat.n Index: embedded/man/files/modules/textutil/repeat.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/repeat.n @@ -0,0 +1,286 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/repeat.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::repeat" n 0.7.1 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::repeat \- Procedures to repeat strings. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::repeat ?0.7?\fR +.sp +\fB::textutil::repeat::strRepeat\fR \fItext\fR \fInum\fR +.sp +\fB::textutil::repeat::blank\fR \fInum\fR +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::repeat\fR provides commands to generate +long strings by repeating a shorter string many times. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::repeat::strRepeat\fR \fItext\fR \fInum\fR +This command returns a string containing the \fItext\fR repeated +\fInum\fR times. The repetitions are joined without characters between +them. A value of \fInum\fR <= 0 causes the command to return an empty +string. +.sp +\fINote\fR: If the Tcl core the package is loaded in provides the +command \fBstring repeat\fR then this command will be implemented in +its terms, for maximum possible speed. Otherwise a fast implementation +in Tcl will be used. +.TP +\fB::textutil::repeat::blank\fR \fInum\fR +A convenience command. Returns a string of \fInum\fR spaces. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +blanks, repetition, string +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/tabify.n Index: embedded/man/files/modules/textutil/tabify.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/tabify.n @@ -0,0 +1,311 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/tabify.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::tabify" n 0.7 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::tabify \- Procedures to (un)tabify strings +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::tabify ?0.7?\fR +.sp +\fB::textutil::tabify::tabify\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::tabify::tabify2\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::tabify::untabify\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::tabify::untabify2\fR \fIstring\fR ?\fInum\fR? +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::tabify\fR provides commands that convert +between tabulation and ordinary whitespace in strings. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::tabify::tabify\fR \fIstring\fR ?\fInum\fR? +Tabify the \fIstring\fR by replacing any substring of \fInum\fR space +chars by a tabulation and return the result as a new string. \fInum\fR +defaults to 8. +.TP +\fB::textutil::tabify::tabify2\fR \fIstring\fR ?\fInum\fR? +Similar to \fB::textutil::tabify\fR this command tabifies the +\fIstring\fR and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +\fInum\fR spaces this command works more like an editor. \fInum\fR +defaults to 8. +.sp +Each line of the text in \fIstring\fR is treated as if there are +tabstops every \fInum\fR columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs. +.TP +\fB::textutil::tabify::untabify\fR \fIstring\fR ?\fInum\fR? +Untabify the \fIstring\fR by replacing any tabulation char by a +substring of \fInum\fR space chars and return the result as a new +string. \fInum\fR defaults to 8. +.TP +\fB::textutil::tabify::untabify2\fR \fIstring\fR ?\fInum\fR? +Untabify the \fIstring\fR by replacing any tabulation char by a +substring of at most \fInum\fR space chars and return the result as a +new string. Unlike \fBtextutil::tabify::untabify\fR each tab is not +replaced by a fixed number of space characters. The command overlays +each line in the \fIstring\fR with tabstops every \fInum\fR columns +instead and replaces tabs with just enough space characters to reach +the next tabstop. This is the complement of the actions taken by +\fB::textutil::tabify::tabify2\fR. \fInum\fR defaults to 8. +.sp +There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +formatting, string, tabstops +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/textutil.n Index: embedded/man/files/modules/textutil/textutil.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/textutil.n @@ -0,0 +1,602 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/textutil.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil" n 0.7.1 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil \- Procedures to manipulate texts and strings. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil ?0.7.1?\fR +.sp +\fB::textutil::adjust\fR \fIstring args\fR +.sp +\fB::textutil::adjust::readPatterns\fR \fIfilename\fR +.sp +\fB::textutil::adjust::listPredefined\fR +.sp +\fB::textutil::adjust::getPredefined\fR \fIfilename\fR +.sp +\fB::textutil::indent\fR \fIstring\fR \fIprefix\fR ?\fIskip\fR? +.sp +\fB::textutil::undent\fR \fIstring\fR +.sp +\fB::textutil::splitn\fR \fIstring\fR ?\fIlen\fR? +.sp +\fB::textutil::splitx\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::tabify\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::tabify2\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::trim\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trimleft\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trimright\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trimPrefix\fR \fIstring\fR \fIprefix\fR +.sp +\fB::textutil::trimEmptyHeading\fR \fIstring\fR +.sp +\fB::textutil::untabify\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::untabify2\fR \fIstring\fR ?\fInum\fR? +.sp +\fB::textutil::strRepeat\fR \fItext num\fR +.sp +\fB::textutil::blank\fR \fInum\fR +.sp +\fB::textutil::chop\fR \fIstring\fR +.sp +\fB::textutil::tail\fR \fIstring\fR +.sp +\fB::textutil::cap\fR \fIstring\fR +.sp +\fB::textutil::uncap\fR \fIstring\fR +.sp +\fB::textutil::longestCommonPrefixList\fR \fIlist\fR +.sp +\fB::textutil::longestCommonPrefix\fR ?\fIstring\fR...? +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil\fR 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 +.TP +\fBtextutil::adjust\fR +.TP +\fBtextutil::repeat\fR +.TP +\fBtextutil::split\fR +.TP +\fBtextutil::string\fR +.TP +\fBtextutil::tabify\fR +.TP +\fBtextutil::trim\fR +.PP +in the namespace \fBtextutil\fR. +.PP +The bundle is \fIdeprecated\fR, 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. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::adjust\fR \fIstring args\fR +Do a justification on the \fIstring\fR according to \fIargs\fR. 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. +.sp +Together with \fB::textutil::indent\fR it is possible to create +properly wrapped paragraphs with arbitrary indentations. +.sp +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 \fIreal\fR +line. Each \fIreal\fR line is placed in a \fIlogical\fR line, which +have exactly a given length (see \fB-length\fR option below). The +\fIreal\fR line may have a lesser length. Again by default, any +trailing spaces are ignored before returning the string (see +\fB-full\fR option below). The following options may be used after the +\fIstring\fR parameter, and change the way the command place a +\fIreal\fR line in a \fIlogical\fR line. +.RS +.TP +-full \fIboolean\fR +If set to \fBfalse\fR, any trailing space chars are deleted before +returning the string. If set to \fBtrue\fR, any trailing space +chars are left in the string. Default to \fBfalse\fR. +.TP +\fB-hyphenate\fR \fIboolean\fR +if set to \fBfalse\fR, no hyphenation will be done. If set to +\fBtrue\fR, the last word of a line is tried to be hyphenated. +Defaults to \fBfalse\fR. Note: hyphenation patterns must be loaded +prior, using the command \fB::textutil::adjust::readPatterns\fR. +.TP +\fB-justify\fR \fBcenter|left|plain|right\fR +Set the justification of the returned string to \fBcenter\fR, +\fBleft\fR, \fBplain\fR or \fBright\fR. By default, it is set to +\fBleft\fR. 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 \fBplain\fR and the number of printable +chars in the last line is less than 90% of the length of a line (see +\fB-length\fR), then this line is justified with the \fBleft\fR +value, avoiding the expansion of this line when it is too small. The +meaning of each value is: +.RS +.TP +\fBcenter\fR +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 \fB-full\fR). +.TP +\fBleft\fR +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 \fB-full\fR). +.TP +\fBplain\fR +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 \fIreal\fR line, between 2 (or more) words. +.TP +\fBright\fR +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 \fB-full\fR option. +.RE +.TP +\fB-length\fR \fIinteger\fR +Set the length of the \fIlogical\fR line in the string to +\fIinteger\fR. \fIinteger\fR must be a positive integer +value. Defaults to \fB72\fR. +.TP +\fB-strictlength\fR \fIboolean\fR +If set to \fBfalse\fR, a line can exceed the specified +\fB-length\fR if a single word is longer than \fB-length\fR. If +set to \fBtrue\fR, words that are longer than \fB-length\fR are +split so that no line exceeds the specified \fB-length\fR. Defaults +to \fBfalse\fR. +.RE +.TP +\fB::textutil::adjust::readPatterns\fR \fIfilename\fR +Loads the internal storage for hyphenation patterns with the contents +of the file \fIfilename\fR. This has to be done prior to calling +command \fB::textutil::adjust\fR with +"\fB-hyphenate\fR \fBtrue\fR", or the hyphenation process will +not work correctly. +.sp +The package comes with a number of predefined pattern files, and the +command \fB::textutil::adjust::listPredefined\fR can be used to find +out their names. +.TP +\fB::textutil::adjust::listPredefined\fR +This command returns a list containing the names of the hyphenation +files coming with this package. +.TP +\fB::textutil::adjust::getPredefined\fR \fIfilename\fR +Use this command to query the package for the full path name of the +hyphenation file \fIfilename\fR coming with the package. Only the +filenames found in the list returned by +\fB::textutil::adjust::listPredefined\fR are legal arguments for this +command. +.TP +\fB::textutil::indent\fR \fIstring\fR \fIprefix\fR ?\fIskip\fR? +Each line in the \fIstring\fR indented by adding the string +\fIprefix\fR at its beginning. The modified string is returned +as the result of the command. +.sp +If \fIskip\fR is specified the first \fIskip\fR lines are left +untouched. The default for \fIskip\fR is \fB0\fR, causing the +modification of all lines. Negative values for \fIskip\fR are treated +like \fB0\fR. In other words, \fIskip\fR > \fB0\fR creates a +hanging indentation. +.sp +Together with \fB::textutil::adjust\fR it is possible to create +properly wrapped paragraphs with arbitrary indentations. +.TP +\fB::textutil::undent\fR \fIstring\fR +The command computes the common prefix for all +lines in \fIstring\fR consisting solely out of whitespace, +removes this from each line and returns the modified string. +.sp +Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove. +.sp +Together with \fB::textutil::adjust\fR it is possible to create +properly wrapped paragraphs with arbitrary indentations. +.TP +\fB::textutil::splitn\fR \fIstring\fR ?\fIlen\fR? +This command splits the given \fIstring\fR into chunks of \fIlen\fR +characters and returns a list containing these chunks. The argument +\fIlen\fR defaults to \fB1\fR 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 \fIstring\fR is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than \fIlen\fR. +.TP +\fB::textutil::splitx\fR \fIstring\fR ?\fIregexp\fR? +Split the \fIstring\fR and return a list. The string is split +according to the regular expression \fIregexp\fR instead of a simple +list of chars. Note that if you add parenthesis into the \fIregexp\fR, +the parentheses part of separator would be added into list as +additional element. If the \fIstring\fR is empty the result is the +empty list, like for \fBsplit\fR. If \fIregexp\fR is empty the +\fIstring\fR is split at every character, like \fBsplit\fR does. +The regular expression \fIregexp\fR defaults to "[\\\\t \\\\r\\\\n]+". +.TP +\fB::textutil::tabify\fR \fIstring\fR ?\fInum\fR? +Tabify the \fIstring\fR by replacing any substring of \fInum\fR space +chars by a tabulation and return the result as a new string. \fInum\fR +defaults to 8. +.TP +\fB::textutil::tabify2\fR \fIstring\fR ?\fInum\fR? +Similar to \fB::textutil::tabify\fR this command tabifies the +\fIstring\fR and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +\fInum\fR spaces this command works more like an editor. \fInum\fR +defaults to 8. +.sp +Each line of the text in \fIstring\fR is treated as if there are +tabstops every \fInum\fR columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs. +.TP +\fB::textutil::trim\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any leading and trailing substring according to +the regular expression \fIregexp\fR and return the result as a new +string. This apply on any \fIline\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trimleft\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any leading substring according to the regular +expression \fIregexp\fR and return the result as a new string. This +apply on any \fIline\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trimright\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any trailing substring according to the regular +expression \fIregexp\fR and return the result as a new string. This +apply on any \fIline\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trimPrefix\fR \fIstring\fR \fIprefix\fR +Removes the \fIprefix\fR from the beginning of \fIstring\fR and +returns the result. The \fIstring\fR is left unchanged if it doesn't +have \fIprefix\fR at its beginning. +.TP +\fB::textutil::trimEmptyHeading\fR \fIstring\fR +Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the \fIstring\fR and removes it. The modified +string is returned as the result of the command. +.TP +\fB::textutil::untabify\fR \fIstring\fR ?\fInum\fR? +Untabify the \fIstring\fR by replacing any tabulation char by a +substring of \fInum\fR space chars and return the result as a new +string. \fInum\fR defaults to 8. +.TP +\fB::textutil::untabify2\fR \fIstring\fR ?\fInum\fR? +Untabify the \fIstring\fR by replacing any tabulation char by a +substring of at most \fInum\fR space chars and return the result as a +new string. Unlike \fBtextutil::untabify\fR each tab is not replaced +by a fixed number of space characters. The command overlays each line +in the \fIstring\fR with tabstops every \fInum\fR columns instead and +replaces tabs with just enough space characters to reach the next +tabstop. This is the complement of the actions taken by +\fB::textutil::tabify2\fR. \fInum\fR defaults to 8. +.sp +There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around. +.TP +\fB::textutil::strRepeat\fR \fItext num\fR +The implementation depends on the core executing the package. Used +\fBstring repeat\fR if it is present, or a fast tcl implementation +if it is not. Returns a string containing the \fItext\fR repeated +\fInum\fR times. The repetitions are joined without characters between +them. A value of \fInum\fR <= 0 causes the command to return an empty +string. +.TP +\fB::textutil::blank\fR \fInum\fR +A convenience command. Returns a string of \fInum\fR spaces. +.TP +\fB::textutil::chop\fR \fIstring\fR +A convenience command. Removes the last character of \fIstring\fR and +returns the shortened string. +.TP +\fB::textutil::tail\fR \fIstring\fR +A convenience command. Removes the first character of \fIstring\fR and +returns the shortened string. +.TP +\fB::textutil::cap\fR \fIstring\fR +Capitalizes the first character of \fIstring\fR and returns the modified string. +.TP +\fB::textutil::uncap\fR \fIstring\fR +The complementary operation to \fB::textutil::cap\fR. Forces the first +character of \fIstring\fR to lower case and returns the modified +string. +.TP +\fB::textutil::longestCommonPrefixList\fR \fIlist\fR +.TP +\fB::textutil::longestCommonPrefix\fR ?\fIstring\fR...? +Computes the longest common prefix for either the \fIstring\fRs given +to the command, or the strings specified in the single \fIlist\fR, and +returns it as the result of the command. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +TeX, formatting, hyphenation, indenting, paragraph, regular expression, string, trimming +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/textutil_split.n Index: embedded/man/files/modules/textutil/textutil_split.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/textutil_split.n @@ -0,0 +1,293 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/textutil_split.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::split" n 0.7 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::split \- Procedures to split texts +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::split ?0.7?\fR +.sp +\fB::textutil::split::splitn\fR \fIstring\fR ?\fIlen\fR? +.sp +\fB::textutil::split::splitx\fR \fIstring\fR ?\fIregexp\fR? +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::split\fR provides commands that split +strings by size and arbitrary regular expressions. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::split::splitn\fR \fIstring\fR ?\fIlen\fR? +This command splits the given \fIstring\fR into chunks of \fIlen\fR +characters and returns a list containing these chunks. The argument +\fIlen\fR defaults to \fB1\fR 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 \fIstring\fR is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than \fIlen\fR. +.TP +\fB::textutil::split::splitx\fR \fIstring\fR ?\fIregexp\fR? +This command splits the \fIstring\fR and return a list. The string is +split according to the regular expression \fIregexp\fR instead of a +simple list of chars. +Note that if you parentheses are added into the \fIregexp\fR, the +parentheses part of separator will be added into the result list as +additional element. If the \fIstring\fR is empty the result is the +empty list, like for \fBsplit\fR. If \fIregexp\fR is empty the +\fIstring\fR is split at every character, like \fBsplit\fR does. +The regular expression \fIregexp\fR defaults to "[\\\\t \\\\r\\\\n]+". +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +regular expression, split, string +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/textutil_string.n Index: embedded/man/files/modules/textutil/textutil_string.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/textutil_string.n @@ -0,0 +1,308 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/textutil_string.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::string" n 0.7 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::string \- Procedures to manipulate texts and strings. +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::string ?0.7?\fR +.sp +\fB::textutil::string::chop\fR \fIstring\fR +.sp +\fB::textutil::string::tail\fR \fIstring\fR +.sp +\fB::textutil::string::cap\fR \fIstring\fR +.sp +\fB::textutil::string::uncap\fR \fIstring\fR +.sp +\fB::textutil::string::longestCommonPrefixList\fR \fIlist\fR +.sp +\fB::textutil::string::longestCommonPrefix\fR ?\fIstring\fR...? +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::string\fR provides miscellaneous string +manipulation commands. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::string::chop\fR \fIstring\fR +A convenience command. Removes the last character of \fIstring\fR and +returns the shortened string. +.TP +\fB::textutil::string::tail\fR \fIstring\fR +A convenience command. Removes the first character of \fIstring\fR and +returns the shortened string. +.TP +\fB::textutil::string::cap\fR \fIstring\fR +Capitalizes the first character of \fIstring\fR and returns the +modified string. +.TP +\fB::textutil::string::uncap\fR \fIstring\fR +The complementary operation to \fB::textutil::string::cap\fR. Forces +the first character of \fIstring\fR to lower case and returns the +modified string. +.TP +\fB::textutil::string::longestCommonPrefixList\fR \fIlist\fR +.TP +\fB::textutil::string::longestCommonPrefix\fR ?\fIstring\fR...? +Computes the longest common prefix for either the \fIstring\fRs given +to the command, or the strings specified in the single \fIlist\fR, and +returns it as the result of the command. +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +capitalize, chop, common prefix, formatting, prefix, string, uncapitalize +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/textutil/trim.n Index: embedded/man/files/modules/textutil/trim.n ================================================================== --- /dev/null +++ embedded/man/files/modules/textutil/trim.n @@ -0,0 +1,316 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/textutil/trim.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "textutil::trim" n 0.7 tcllib "Text and string utilities, macro processing" +.BS +.SH NAME +textutil::trim \- Procedures to trim strings +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtextutil::trim ?0.7?\fR +.sp +\fB::textutil::trim::trim\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trim::trimleft\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trim::trimright\fR \fIstring\fR ?\fIregexp\fR? +.sp +\fB::textutil::trim::trimPrefix\fR \fIstring\fR \fIprefix\fR +.sp +\fB::textutil::trim::trimEmptyHeading\fR \fIstring\fR +.sp +.BE +.SH DESCRIPTION +The package \fBtextutil::trim\fR provides commands that trim +strings using arbitrary regular expressions. +.PP +The complete set of procedures is described below. +.TP +\fB::textutil::trim::trim\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any leading and trailing substring according to +the regular expression \fIregexp\fR and return the result as a new +string. This is done for all \fIlines\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trim::trimleft\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any leading substring according to the regular +expression \fIregexp\fR and return the result as a new string. This +apply on any \fIline\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trim::trimright\fR \fIstring\fR ?\fIregexp\fR? +Remove in \fIstring\fR any trailing substring according to the regular +expression \fIregexp\fR and return the result as a new string. This +apply on any \fIline\fR 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 \fIregexp\fR defaults to "[ \\\\t]+". +.TP +\fB::textutil::trim::trimPrefix\fR \fIstring\fR \fIprefix\fR +Removes the \fIprefix\fR from the beginning of \fIstring\fR and +returns the result. The \fIstring\fR is left unchanged if it doesn't +have \fIprefix\fR at its beginning. +.TP +\fB::textutil::trim::trimEmptyHeading\fR \fIstring\fR +Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the \fIstring\fR and removes it. The modified +string is returned as the result of the command. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItextutil\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +regexp(n), split(n), string(n) +.SH KEYWORDS +prefix, regular expression, string, trimming +.SH CATEGORY +Text processing ADDED embedded/man/files/modules/tie/tie.n Index: embedded/man/files/modules/tie/tie.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tie/tie.n @@ -0,0 +1,682 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tie/tie.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tie" n 1.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +tie \- Array persistence +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBtie ?1.1?\fR +.sp +\fB::tie::tie\fR \fIarrayvarname\fR \fIoptions\fR... \fIdstype\fR \fIdsname\fR... +.sp +\fB::tie::untie\fR \fIarrayvarname\fR ?\fItoken\fR? +.sp +\fB::tie::info\fR \fBties\fR \fIarrayvarname\fR +.sp +\fB::tie::info\fR \fBtypes\fR +.sp +\fB::tie::info\fR \fBtype\fR \fIdstype\fR +.sp +\fB::tie::register\fR \fIdsclasscmd\fR \fBas\fR \fIdstype\fR +.sp +\fBdsclasscmd\fR \fIobjname\fR ?\fIdsname\fR...? +.sp +\fBds\fR \fBdestroy\fR +.sp +\fBds\fR \fBnames\fR +.sp +\fBds\fR \fBsize\fR +.sp +\fBds\fR \fBget\fR +.sp +\fBds\fR \fBset\fR \fIdict\fR +.sp +\fBds\fR \fBunset\fR ?\fIpattern\fR? +.sp +\fBds\fR \fBsetv\fR \fIindex\fR \fIvalue\fR +.sp +\fBds\fR \fBunsetv\fR \fIindex\fR +.sp +\fBds\fR \fBgetv\fR \fIindex\fR +.sp +.BE +.SH DESCRIPTION +The \fBtie\fR 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. +.PP +This, persistence and communication, is accomplished by \fItying\fR) +a Tcl array variable to a \fIdata source\fR. Examples of data +sources are other Tcl arrays and files. +.PP +It should be noted that a single Tcl array variable can be tied to +more than one \fIdata source\fR. 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. +.SH "USING TIES" +.SS "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. +.TP +\fB::tie::tie\fR \fIarrayvarname\fR \fIoptions\fR... \fIdstype\fR \fIdsname\fR... +This command establishes a tie between the Tcl array whose name is +provided by the argument \fIarrayvarname\fR and the +\fIdata source\fR identified by the \fIdstype\fR and its series of +\fIdsname\fR arguments. All changes made to the Tcl array after this +command returns will be saved to the \fIdata source\fR for +safekeeping (or distribution). +.sp +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. +.RS +.TP +varname \fIarrayvarname\fR (in) +The name of the Tcl array variable to connect the new tie to. +.TP +name|command \fIdstype\fR (in) +This argument specifies the type of the \fIdata source\fR we wish +to access. +The \fIdstype\fR can be one of \fBlog\fR, \fBarray\fR, +\fBremotearray\fR, \fBfile\fR, \fBgrowfile\fR, or +\fBdsource\fR; in addition, the programmer can register additional +data source types. +Each \fIdstype\fR is followed by one or more arguments that identify +the \fIdata source\fR to which the array is to be tied. +.TP +string \fIdsname\fR (in) +The series of \fIdsname\fR arguments coming after the \fIdstype\fR +identifies the \fIdata source\fR we wish to connect to, and has to +be appropriate for the chosen type. +.RE +.sp +The command understands a number of additional options which guide the +process of setting up the connection between Tcl array and +\fIdata source\fR. +.sp +.RS +.TP +\fB-open\fR +The Tcl array for the new tie is \fIloaded\fR from the +\fIdata source\fR, and the previously existing contents of the Tcl +array are erased. Care is taken to \fInot\fR erase the previous +contents should the creation of the tie fail. +.sp +This option and the option \fB-save\fR exclude each other. If +neither this nor option \fB-save\fR are specified then this option +is assumed as default. +.TP +\fB-save\fR +The Tcl array for the new tie is \fIsaved\fR to the +\fIdata source\fR, and the previously existing contents of the +\fIdata source\fR are erased. +.sp +This option and the option \fB-open\fR exclude each other. If +neither this nor option \fB-open\fR are specified then option +\fB-open\fR is assumed as default. +.TP +\fB-merge\fR +Using this option prevents the erasure of any previously existing +content and merges the data instead. It can be specified in +conjunction with either \fB-open\fR or \fB-save\fR. They +determine how data existing in both Tcl array and +\fIdata source\fR, i.e duplicates, are dealt with. +.sp +When used with \fB-open\fR data in the \fIdata source\fR has +precedence. +In other words, for duplicates the data in the \fIdata source\fR is +loaded into the Tcl array. +.sp +When used with \fB-save\fR data in the Tcl array has precedence. In +other words, for duplicates the data in the Tcl array is saved into +the \fIdata source\fR. +.RE +.sp +.TP +\fB::tie::untie\fR \fIarrayvarname\fR ?\fItoken\fR? +This command dissolves one or more ties associated with the Tcl array +named by \fIarrayvarname\fR. If no \fItoken\fR 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. +.sp +It should be noted that while severing a tie will destroy management +information internal to the package the \fIdata source\fR which was +handled by the tie will not be touched, only closed. +.sp +After the command returns none of changes made to the array will be +saved to the \fIdata source\fR anymore. +.sp +The result of the command is an empty string. +.RS +.TP +varname \fIarrayname\fR (in) +The name of a Tcl array variable which may have ties. +.TP +handle \fItoken\fR (in) +A handle representing a specific tie. This argument is optional. +.RE +.sp +.TP +\fB::tie::info\fR \fBties\fR \fIarrayvarname\fR +This command returns a list of ties associated with the Tcl array +variable named by \fIarrayvarname\fR. The result list will be empty if +the variable has no ties associated with it. +.TP +\fB::tie::info\fR \fBtypes\fR +This command returns a dictionary of registered types, and the class +commands they are associated with. +.TP +\fB::tie::info\fR \fBtype\fR \fIdstype\fR +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. +.PP +.SS "STANDARD DATA SOURCE TYPES" +This package provides the six following types as examples and standard +data sources. +.TP +\fBlog\fR +This \fIdata source\fR does not maintain any actual data, nor +persistence. It does not accept any identifying arguments. All changes +are simply logged to \fBstdout\fR. +.TP +\fBarray\fR +This \fIdata source\fR 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. +.TP +\fBremotearray\fR +This \fIdata source\fR is similar to \fBarray\fR. The difference +is that the Tcl array to which we are mirroring is not directly +accessible, but through a \fBsend\fR-like command. +.sp +It accepts three identifying arguments, the name of the other Tcl +array, the command prefix for the \fBsend\fR-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. +.sp +\fBsend\fR-like means that the command prefix has to have \fBsend\fR +syntax and semantics. I.e. it is a channel over which we can send +arbitrary commands to some other entity. +The remote array \fIdata source\fR however uses only the commands +\fBset\fR, \fBunset\fR, \fBarray exists\fR, \fBarray names\fR, \fBarray set\fR, and +\fBarray get\fR to retrieve and set values in the remote array. +.sp +The command prefix and the entity id are separate to allow the data +source to use options like \fB-async\fR when assembling the actual +commands. +.sp +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: +.RS +.TP +\fBsend\fR \fItkname\fR +The Tcl array is in a remote interpreter and is accessed via Tk's X +communication. +.TP +\fBcomm::comm send\fR \fIhostportid\fR +The Tcl array is in a remote interpreter and is accessed through a +socket. +.TP +\fBthread::send\fR \fIthreadid\fR +The Tcl array is in a remote interpreter in a different thread of this +process. +.RE +.sp +.TP +\fBfile\fR +This \fIdata source\fR 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 \fIdata source\fR 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. +.sp +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. +.sp +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. +.TP +\fBgrowfile\fR +This \fIdata source\fR is like \fBfile\fR 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. +.sp +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. +.TP +\fBdsource\fR +This \fIdata source\fR uses an explicitly specified +\fIdata source object\fR as the source for the persistent +data. It accepts a single identifying argument, the command prefix, +i.e. object command. +.sp +To use this type it is necessary to know how the framework manages +ties and what \fBdata source objects\fR are. +.sp +All changes are delegated to the specified object. +.PP +.SH "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. +.SS "DATA SOURCE OBJECTS" +All ties are represented internally by an in-memory object which +mediates between the tie framework and the specific +\fIdata source\fR, like an array, file, etc. +This is the \fIdata source object\fR. +.PP +Its class, the \fBdata source class\fR is \fInot\fR generic, +but specific to the type of the \fIdata source\fR. Writing a new +\fIdata source\fR requires us to write such a class, and then +registering it with the framework as a new type. +.PP +The following subsections describe the various APIs a +\fBdata source class\fR and the objects it generates will have +to follow to be compatible with the tie framework. +.PP +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 \fIdata source\fR for this type is a +\fIdata source object\fR 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 \fIdata source object\fRs, and these objects will +survive the removal of the ties using them as well. +.SS "REGISTERING A NEW DATA SOURCE CLASS" +After a \fBdata source class\fR has been written it is necessary +to register it as a new type with the framework. +.TP +\fB::tie::register\fR \fIdsclasscmd\fR \fBas\fR \fIdstype\fR +Using this command causes the tie framework to remember the class +command \fIdsclasscmd\fR of a \fBdata source class\fR under the +type name \fIdstype\fR. +.sp +After the call the argument \fIdstype\fR of the basic user command +\fB::tie::tie\fR will accept \fIdstype\fR as a type name and translate +it internally to the appropriate class command for the creation of +\fBdata source objects\fR for the new \fIdata source\fR. +.PP +.SS "DATA SOURCE CLASS" +Each data source class is represented by a single command, also called +the \fIclass command\fR, or \fIobject creation command\fR. Its +syntax is +.TP +\fBdsclasscmd\fR \fIobjname\fR ?\fIdsname\fR...? +The first argument of the class command is the name of the +\fIdata source object\fR to create. +The framework itself will always supply the string \fB%AUTO%\fR, to +signal that the class command has to generate not only the object, but +the object name as well. +.sp +This is followed by a series of arguments identifying the data source +the new object is for. These are the same \fIdsname\fR arguments which +are given to the basic user command \fB::tie::tie\fR. Their actual +meaning is dependent on the \fIdata source class\fR. +.sp +The result of the class command has to be the fully-qualified name of +the new \fIdata source object\fR, i.e. the name of the +\fIobject command\fR. +The interface this command has to follow is described in the section +\fBDATA SOURCE OBJECT API\fR +.PP +.PP +.SS "DATA SOURCE OBJECT API" +Please read the section \fBDATA SOURCE CLASS\fR first, to know +how to generate new \fIobject commands\fR. +.PP +Each \fIobject command\fR for a \fIdata source\fR 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 \fBarray\fR command. +.PP +.TP +\fBds\fR \fBdestroy\fR +This method is called when the object \fBds\fR is destroyed. It now +has to release all its internal resources associated with the external +data source. +.TP +\fBds\fR \fBnames\fR +This command has to return a list containing the names of all keys +found in the \fIdata source\fR the object talks to. This is +equivalent to \fBarray names\fR. +.TP +\fBds\fR \fBsize\fR +This command has to return an integer number specifying the number of +keys found in the \fIdata source\fR the object talks to. This is +equivalent to \fBarray size\fR. +.TP +\fBds\fR \fBget\fR +This command has to return a dictionary containing the data found in +the \fIdata source\fR the object talks to. This is equivalent to +\fBarray get\fR. +.TP +\fBds\fR \fBset\fR \fIdict\fR +This command takes a dictionary and adds its contents to the data +source the object talks to. This is equivalent to \fBarray set\fR. +.TP +\fBds\fR \fBunset\fR ?\fIpattern\fR? +This command takes a pattern and removes all elements whose keys +matching it from the \fIdata source\fR. If no pattern is specified +it defaults to \fB*\fR, causing the removal of all elements. This +is nearly equivalent to \fBarray unset\fR. +.TP +\fBds\fR \fBsetv\fR \fIindex\fR \fIvalue\fR +This command has to save the \fIvalue\fR in the \fIdata source\fR +the object talks to, under the key \fIindex\fR. +.sp +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. +.TP +\fBds\fR \fBunsetv\fR \fIindex\fR +This command has to remove the value under the key \fIindex\fR from +the \fIdata source\fR the object talks to. +.sp +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. +.TP +\fBds\fR \fBgetv\fR \fIindex\fR +This command has to return the value for the key \fIindex\fR in the +\fIdata source\fR the object talks to. +.PP +And here a small table comparing the \fIdata source\fR methods to +the regular Tcl commands for accessing an array. +.PP +.CS + + + 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 + ----------- ----------- + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItie\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +array, database, file, metakit, persistence, tie, untie +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2004-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/tie/tie_std.n Index: embedded/man/files/modules/tie/tie_std.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tie/tie_std.n @@ -0,0 +1,285 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tie/tie_std.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tie" n 1.1 tcllib "Tcl Data Structures" +.BS +.SH NAME +tie \- Array persistence, standard data sources +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBtie::std::log ?1.1?\fR +.sp +package require \fBtie::std::array ?1.1?\fR +.sp +package require \fBtie::std::rarray ?1.1?\fR +.sp +package require \fBtie::std::file ?1.1?\fR +.sp +package require \fBtie::std::growfile ?1.1?\fR +.sp +package require \fBtie::std::dsource ?1.1?\fR +.sp +.BE +.SH DESCRIPTION +The packages listed as requirements for this document are internal +packages providing the standard data sources of package \fBtie\fR, +as described in section \fISTANDARD DATA SOURCE TYPES\fR of +\fBtie\fR's documentation. +.PP +They are automatically loaded and registered by \fBtie\fR 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the packages it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItie\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +array, database, file, metakit, persistence, tie, untie +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/tiff/tiff.n Index: embedded/man/files/modules/tiff/tiff.n ================================================================== --- /dev/null +++ embedded/man/files/modules/tiff/tiff.n @@ -0,0 +1,458 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/tiff/tiff.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2005-2006, Aaron Faupell <afaupell@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tiff" n 0.2.1 tcllib "TIFF image manipulation" +.BS +.SH NAME +tiff \- TIFF reading, writing, and querying and manipulation of meta data +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBtiff ?0.2.1?\fR +.sp +\fB::tiff::isTIFF\fR \fIfile\fR +.sp +\fB::tiff::byteOrder\fR \fIfile\fR +.sp +\fB::tiff::numImages\fR \fIfile\fR +.sp +\fB::tiff::dimensions\fR \fIfile\fR ?image? +.sp +\fB::tiff::imageInfo\fR \fIfile\fR ?image? +.sp +\fB::tiff::entries\fR \fIfile\fR ?image? +.sp +\fB::tiff::getEntry\fR \fIfile\fR \fIentry\fR ?image? +.sp +\fB::tiff::addEntry\fR \fIfile\fR \fIentry\fR ?image? +.sp +\fB::tiff::deleteEntry\fR \fIfile\fR \fIentry\fR ?image? +.sp +\fB::tiff::getImage\fR \fIfile\fR ?image? +.sp +\fB::tiff::writeImage\fR \fIimage\fR \fIfile\fR ?entry? +.sp +\fB::tiff::nametotag\fR \fInames\fR +.sp +\fB::tiff::tagtoname\fR \fItags\fR +.sp +\fB::tiff::debug\fR \fIfile\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides commands to query, modify, read, and write TIFF images. +TIFF stands for \fITagged Image File Format\fR and is a standard +for lossless storage of photographical images and associated metadata. +It is specified at \fIhttp://partners.adobe.com/public/developer/tiff/index.html\fR. +.PP +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 +\fIhttp://www.awaresystems.be/imaging/tiff/tifftags.html\fR +.SH COMMANDS +.TP +\fB::tiff::isTIFF\fR \fIfile\fR +Returns a boolean value indicating if \fIfile\fR is a +TIFF image. +.TP +\fB::tiff::byteOrder\fR \fIfile\fR +Returns either \fBbig\fR or \fBlittle\fR. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::numImages\fR \fIfile\fR +Returns the number of images in \fIfile\fR. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::dimensions\fR \fIfile\fR ?image? +Returns the dimensions of image number ?image? in \fIfile\fR as a list of the +horizontal and vertical pixel count. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::imageInfo\fR \fIfile\fR ?image? +Returns a dictionary with keys \fBImageWidth\fR, \fBImageLength\fR, +\fBBitsPerSample\fR, \fBCompression\fR, \fBPhotometricInterpretation\fR, +\fBImageDescription\fR, \fBOrientation\fR, \fBXResolution\fR, +\fBYResolution\fR, \fBResolutionUnit\fR, \fBDateTime\fR, \fBArtist\fR, +and \fBHostComputer\fR. The values are the associated properties of +the TIFF ?image? in \fIfile\fR. Values may be empty if the associated tag is not +present in the file. +.CS + + + 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 {} + +.CE +.IP +There is nothing special about these tags, this is simply a convience procedure which calls +\fBgetEntry\fR with common entries. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::entries\fR \fIfile\fR ?image? +Returns a list of all entries in the given \fIfile\fR and ?image? +in hexadecimal format. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::getEntry\fR \fIfile\fR \fIentry\fR ?image? +Returns the value of \fIentry\fR from image ?image? in the TIFF \fIfile\fR. +\fIentry\fR may be a list of multiple entries. If an entry does not exist, an +empty string is returned +.CS + + + set data [::tiff::getEntry photo.tif {0131 0132}] + puts "file was written at [lindex $data 0] with software [lindex $data 1]" + +.CE +.IP +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::addEntry\fR \fIfile\fR \fIentry\fR ?image? +Adds the specified entries to the image named by ?image? (default 0), or optionally \fBall\fR. +\fIentry\fR must be a list where each element is a list of tag, type, and value. If a tag already +exists, it is overwritten. +.CS + + + ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}} + +.CE +.IP +The data types are defined as follows +.RS +.TP +\fB1\fR +BYTE (8 bit unsigned integer) +.TP +\fB2\fR +ASCII +.TP +\fB3\fR +SHORT (16 bit unsigned integer) +.TP +\fB4\fR +LONG (32 bit unsigned integer) +.TP +\fB5\fR +RATIONAL +.TP +\fB6\fR +SBYTE (8 bit signed byte) +.TP +\fB7\fR +UNDEFINED (uninterpreted binary data) +.TP +\fB8\fR +SSHORT (signed 16 bit integer) +.TP +\fB9\fR +SLONG (signed 32 bit integer) +.TP +\fB10\fR +SRATIONAL +.TP +\fB11\fR +FLOAT (32 bit floating point number) +.TP +\fB12\fR +DOUBLE (64 bit floating point number) +.RE +.IP +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::deleteEntry\fR \fIfile\fR \fIentry\fR ?image? +Deletes the specified entries from the image named by ?image? (default 0), or optionally \fBall\fR. +Throws an error if \fIfile\fR is not a TIFF image. +.TP +\fB::tiff::getImage\fR \fIfile\fR ?image? +Returns the name of a Tk image containing the image at index ?image? from \fIfile\fR +Throws an error if \fIfile\fR is not a TIFF image, or if image is an unsupported format. +Supported formats are uncompressed 24 bit RGB and uncompressed 8 bit palette. +.TP +\fB::tiff::writeImage\fR \fIimage\fR \fIfile\fR ?entry? +Writes the contents of the Tk image \fIimage\fR to a tiff file \fIfile\fR. 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 \fBtiff::addEntry\fR +.TP +\fB::tiff::nametotag\fR \fInames\fR +Returns a list with \fInames\fR 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. +.TP +\fB::tiff::tagtoname\fR \fItags\fR +Returns a list with \fItags\fR translated from 4 digit to string format. If a tag does +not have a defined name it is passed through unchanged. +.TP +\fB::tiff::debug\fR \fIfile\fR +Prints everything we know about the given file in a nice format. +.PP +.SH 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. +.SH LIMITATIONS +.IP [1] +Cannot write exif ifd +.IP [2] +Reading limited to uncompressed 8 bit rgb and 8 bit palletized images +.IP [3] +Writing limited to uncompressed 8 bit rgb +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItiff\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +image, tif, tiff +.SH CATEGORY +File formats +.SH COPYRIGHT +.nf +Copyright (c) 2005-2006, Aaron Faupell <afaupell@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/connect.n Index: embedded/man/files/modules/transfer/connect.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/connect.n @@ -0,0 +1,441 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/connect.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::connect" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::connect \- Connection setup +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBtransfer::connect ?0.2?\fR +.sp +\fBtransfer::connect\fR \fIobjectName\fR ?\fIoptions\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBconnect\fR \fIcommand\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fIactive\fR (the object initiates the +connection) and \fIpassive\fR (the object receives the connection). +.PP +Of the two objects in a connecting pair one has to be configured for +\fIactive\fR mode, and the other then has to be configured for +\fIpassive\fR mode. This establishes which of the two partners +connects to whom (the \fIactive\fR to the other), or, who is waiting +on whom (the \fIpassive\fR 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. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fBtransfer::connect\fR \fIobjectName\fR ?\fIoptions\fR...? +This command creates a new connection object with an associated Tcl +command whose name is \fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::connect\fR command have the +following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +This method destroys the object. +This is safe to do for an \fIactive\fR object when a connection has +been started, as the completion callback is synchronous. +For a \fIpassive\fR 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. +.TP +\fIobjectName\fR \fBconnect\fR \fIcommand\fR +This method starts the connection setup per the configuration of the +object. When the connection is established the callback \fIcommand\fR +will be invoked with one additional argument, the channel handle of +the socket over which data can be transfered. +.sp +The detailed behaviour of the method depends on the configured +mode. +.RS +.TP +\fIactive\fR +The connection setup is done synchronously. The object waits until the +connection is established. The method returns the empty string as its +result. +.TP +\fIpassive\fR +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. +.sp +This is necessary as the object might have been configured for port +\fB0\fR, allowing the operating system to choose the actual port it +will listen on. +.sp +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 \fB-socketcmd\fR and section +\fBSecure connections\fR for information on how to do this. +.RE +.PP +.SS OPTIONS +Connection objects support the set of options listed below. +.TP +\fB-mode\fR \fImode\fR +This option specifies the mode the object is in. It is optional and +defaults to \fBactive\fR mode. The two possible modes are: +.RS +.TP +\fBactive\fR +In this mode the two options \fB-host\fR and \fB-port\fR 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. +.TP +\fBpassive\fR +In this mode the option \fB-host\fR has no relevance and is ignored +should it be configured. +The only option the object needs is \fB-port\fR, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner. +.RE +.TP +\fB-host\fR \fIhostname-or-ipaddr\fR +This option specifies the host to connect to in \fIactive\fR mode, +either by name or ip-address. An object configured for \fIpassive\fR +mode ignores this option. +.TP +\fB-port\fR \fIint\fR +For \fIactive\fR mode this option specifies the port the object is +expected to connect to. For \fIpassive\fR mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to \fB0\fR, which allows the OS to choose +the actual port to listen on. +.TP +\fB-socketcmd\fR \fIcommand\fR +This option allows the user to specify which command to use to open a +socket. The default is to use the builtin \fB::socket\fR. Any +compatible with that command is allowed. +.sp +The envisioned main use is the specfication of \fBtls::socket\fR. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the \fBtls\fR package. +.sp +See also section \fBSecure connections\fR. +.TP +\fB-encoding\fR encodingname +.TP +\fB-eofchar\fR eofspec +.TP +\fB-translation\fR transspec +These options are the same as are recognized by the builtin command +\fBfconfigure\fR. 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 \fBconnect\fR). +.PP +.SH "SECURE CONNECTIONS" +One way to secure connections made by objects of this package is to +require the package \fBtls\fR and then configure the option +\fB-socketcmd\fR to force the use of command \fBtls::socket\fR to +open the socket. +.CS + + + # 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 ... + ... + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +active, channel, connection, passive, secure, ssl, tls, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/copyops.n Index: embedded/man/files/modules/transfer/copyops.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/copyops.n @@ -0,0 +1,392 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/copyops.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::copy" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::copy \- Data transfer foundation +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBtransfer::copy ?0.2?\fR +.sp +\fBtransfer::copy::do\fR \fBchan\fR|\fBstring\fR \fIdata\fR \fIoutchannel\fR ?\fIoptions\fR...? +.sp +\fBtransfer::copy::chan\fR \fIchannel\fR \fIoutchannel\fR ?\fIoptions\fR...? +.sp +\fBtransfer::copy::string\fR \fIstring\fR \fIoutchannel\fR ?\fIoptions\fR...? +.sp +\fBtransfer::copy::doChan\fR \fIchannel\fR \fIoutchannel\fR \fIoptvar\fR +.sp +\fBtransfer::copy::doString\fR \fIstring\fR \fIoutchannel\fR \fIoptvar\fR +.sp +\fBtransfer::copy::options\fR \fIoutchannel\fR \fIoptionlist\fR \fIoptvar\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBfcopy\fR, making the use of these +facilities simpler than the builtin. +.SH API +.TP +\fBtransfer::copy::do\fR \fBchan\fR|\fBstring\fR \fIdata\fR \fIoutchannel\fR ?\fIoptions\fR...? +This command transfers the information in \fIdata\fR to the +\fIoutchannel\fR, according to the \fIoptions\fR. The type of the +information in \fIdata\fR is determined by the first argument. +.sp +The options available to this command are the same as are available to +the command \fBtransfer::copy::options\fR, and explained there. +.RS +.TP +\fBchan\fR +The argument \fIdata\fR contains the handle of a channel and the +actual infomration to transfer is read from that channel. +.TP +\fBstring\fR +The argument \fIdata\fR contains a string and this is the information +to be transfered. +.RE +.TP +\fBtransfer::copy::chan\fR \fIchannel\fR \fIoutchannel\fR ?\fIoptions\fR...? +This command is a shorter and more direct form for the command +\fBtransfer::copy::do chan\fR. +.TP +\fBtransfer::copy::string\fR \fIstring\fR \fIoutchannel\fR ?\fIoptions\fR...? +This command is a shorter and more direct form for the command +\fBtransfer::copy::do string\fR. +.TP +\fBtransfer::copy::doChan\fR \fIchannel\fR \fIoutchannel\fR \fIoptvar\fR +This command is an alternate form of \fBtransfer::copy::chan\fR which +reads its options out of the array variable named by \fIoptvar\fR +instead of from a variable length argument list. +.TP +\fBtransfer::copy::doString\fR \fIstring\fR \fIoutchannel\fR \fIoptvar\fR +This command is an alternate form of \fBtransfer::copy::string\fR which +reads its options out of the array variable named by \fIoptvar\fR +instead of from a variable length argument list. +.TP +\fBtransfer::copy::options\fR \fIoutchannel\fR \fIoptionlist\fR \fIoptvar\fR +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 \fIoutchannel\fR, +then processes the list of options in \fIoptionlist\fR, at last stores +the results in the array variable named by \fIoptvar\fR. 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. +.sp +The recognized options are: +.RS +.TP +\fB-blocksize\fR \fIint\fR +This option specifies the size of the chunks to transfer in one +operation. It is optional and defaults to the value of +\fB-buffersize\fR as configured for the output channel. +.sp +If specified its value has to be an integer number greater than zero. +.TP +\fB-command\fR \fIcommandprefix\fR +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. +.sp +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. +.TP +\fB-progress\fR \fIcommandprefix\fR +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. +.sp +Its value has to be a command prefix, see above, \fB-command\fR 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. +.TP +\fB-size\fR \fIint\fR +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. +.sp +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. +.TP +\fB-encoding\fR \fIencodingname\fR +.TP +\fB-eofchar\fR \fIeofspec\fR +.TP +\fB-translation\fR \fItransspec\fR +These options are the same as are recognized by the builtin command +\fBfconfigure\fR 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. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/ddest.n Index: embedded/man/files/modules/transfer/ddest.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/ddest.n @@ -0,0 +1,375 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/ddest.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::data::destination" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::data::destination \- Data destination +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBtransfer::data::destination ?0.2?\fR +.sp +\fBtransfer::data::destination\fR \fIobjectName\fR ?\fIoptions\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBput\fR \fIchunk\fR +.sp +\fIobjectName\fR \fBdone\fR +.sp +\fIobjectName\fR \fBvalid\fR \fImsgvar\fR +.sp +\fIobjectName\fR \fBreceive\fR \fIchannel\fR \fIdone\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH API +.TP +\fBtransfer::data::destination\fR \fIobjectName\fR ?\fIoptions\fR...? +This command creates a new data destination object with an associated +Tcl command whose name is \fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::data::destination\fR command +have the following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +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. +.TP +\fIobjectName\fR \fBput\fR \fIchunk\fR +The main receptor method. Saves the received \fIchunk\fR of data into +the configured destination. It has to be called for each piece of data +received. +.TP +\fIobjectName\fR \fBdone\fR +The secondary receptor method. Finalizes the receiver. It has to be +called when the receiving channel signals EOF. Afterward neither +itself nor method \fBput\fR can be called anymore. +.TP +\fIobjectName\fR \fBvalid\fR \fImsgvar\fR +This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is \fBTrue\fR if the +object is valid, and \fBFalse\fR otherwise. In the latter case the +variable whose name is stored in \fImsgvar\fR is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched. +.TP +\fIobjectName\fR \fBreceive\fR \fIchannel\fR \fIdone\fR +This method initiates the reception of data from the specified +\fIchannel\fR. The received data will be stored into the configured +destination, via calls to the methods \fBput\fR and \fBdone\fR. +When the reception completes the command prefix \fIdone\fR is invoked, +with the number of received characters appended to it as the sole +additional argument. +.PP +.SS 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. +.TP +\fB-channel\fR \fIhandle\fR +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. +.TP +\fB-file\fR \fIpath\fR +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. +.TP +\fB-variable\fR \fIvarname\fR +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. +.TP +\fB-progress\fR \fIcommand\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, data destination, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/dsource.n Index: embedded/man/files/modules/transfer/dsource.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/dsource.n @@ -0,0 +1,413 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/dsource.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::data::source" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::data::source \- Data source +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBtransfer::copy ?0.2?\fR +.sp +package require \fBtransfer::data::source ?0.2?\fR +.sp +\fBtransfer::data::source\fR \fIobjectName\fR ?\fIoptions\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBtype\fR +.sp +\fIobjectName\fR \fBdata\fR +.sp +\fIobjectName\fR \fBsize\fR +.sp +\fIobjectName\fR \fBvalid\fR \fImsgvar\fR +.sp +\fIobjectName\fR \fBtransmit\fR \fIchannel\fR \fIblocksize\fR \fIdone\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 +\fBtransfer::copy\fR. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fBtransfer::data::source\fR \fIobjectName\fR ?\fIoptions\fR...? +This command creates a new data source object with an associated Tcl +command whose name is \fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::data::source\fR command have +the following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +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. +.TP +\fIobjectName\fR \fBtype\fR +This method returns a string describing the type of the data the +object is refering to. The possible values and their meanings are: +.RS +.TP +\fBundefined\fR +No data was specified at all, or it was specified incompletely. The +object does not know the type. +.TP +\fBstring\fR +The data to transfer is contained in a string. +.TP +\fBchannel\fR +The data to transfer is contained in a channel. +.RE +.TP +\fIobjectName\fR \fBdata\fR +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 \fBundefined\fR. For type +\fBstring\fR the returned result is the data itself, whereas for +type \fBchannel\fR the returned result is the handle of the channel +containing the data. +.TP +\fIobjectName\fR \fBsize\fR +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 \fBundefined\fR. Return of +a negative value signals that the object is unable to determine an +absolute size upfront (like for data in a channel). +.TP +\fIobjectName\fR \fBvalid\fR \fImsgvar\fR +This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is \fBTrue\fR if the +object is valid, and \fBFalse\fR otherwise. In the latter case the +variable whose name is stored in \fImsgvar\fR is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched. +.TP +\fIobjectName\fR \fBtransmit\fR \fIchannel\fR \fIblocksize\fR \fIdone\fR +This method initiates a transfer of the referenced data to the +specified \fIchannel\fR. +When the transfer completes the command prefix \fIdone\fR is invoked, +per the rules for the option \fB-command\fR of command +\fBtransfer::copy::do\fR in the package \fBtransfer::copy\fR. +The \fIblocksize\fR specifies the size of the chunks to transfer in +one go. See the option \fB-blocksize\fR of command +\fBtransfer::copy::do\fR in the package \fBtransfer::copy\fR. +.PP +.SS 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. +.TP +\fB-string\fR \fItext\fR +This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question. +.TP +\fB-channel\fR \fIhandle\fR +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. +.TP +\fB-file\fR \fIpath\fR +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. +.TP +\fB-variable\fR \fIvarname\fR +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. +.TP +\fB-size\fR \fIint\fR +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. +.TP +\fB-progress\fR \fIcommand\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, data source, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/receiver.n Index: embedded/man/files/modules/transfer/receiver.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/receiver.n @@ -0,0 +1,490 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/receiver.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::receiver" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::receiver \- Data source +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBtransfer::data::destination ?0.2?\fR +.sp +package require \fBtransfer::connect ?0.2?\fR +.sp +package require \fBtransfer::receiver ?0.2?\fR +.sp +\fBtransfer::receiver\fR \fIobject\fR ?\fIoptions\fR...? +.sp +\fBtransfer::receiver\fR \fBstream channel\fR \fIchan\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +.sp +\fBtransfer::receiver\fR \fBstream file\fR \fIpath\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBstart\fR +.sp +\fIobjectName\fR \fBbusy\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBtransfer::data::destination\fR and +\fBtransfer::connect\fR. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fBtransfer::receiver\fR \fIobject\fR ?\fIoptions\fR...? +This command creates a new receiver object with an associated Tcl +command whose name is \fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.TP +\fBtransfer::receiver\fR \fBstream channel\fR \fIchan\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +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 \fIchan\fR, starting at the current seek location. The channel +is configured to use binary translation and encoding for the transfer. +The channel is \fInot\fR closed when the transfer has completed. This +is left to the completion callback. +.sp +If both \fIhost\fR and \fIport\fR are provided an \fBactive\fR +connection to the data source is made. If only a \fIport\fR is +specified (with \fIhost\fR the empty string) then a \fBpassive\fR +connection is made instead, i.e. the receiver then waits for a +conneciton by the transmitter. +.sp +Any arguments after the port are treated as options and are used to +configure the internal receiver object. +See the section \fBOptions\fR for a list of the supported options +and their meaning. +\fINote\fR however that the signature of the command prefix specified +for the \fB-command\fR 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. +.sp +The result returned by the command is the empty string +if it was set to make an \fIactive\fR connection, and the port the +internal receiver object is listening on otherwise, i.e when it is +configured to connect \fIpassive\fRly. +See also the package \fBtransfer::connect\fR and the description +of the method \fBconnect\fR for where this behaviour comes from. +.TP +\fBtransfer::receiver\fR \fBstream file\fR \fIpath\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +This method is like \fBstream channel\fR, except that the +received data is written to the file \fIpath\fR, replacing any prior +content. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::receiver\fR command have the +following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +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. +.TP +\fIobjectName\fR \fBstart\fR +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. +.sp +The result returned by the method is the empty string +for an object configured to make an \fIactive\fR connection, and the port the +object is listening on otherwise, i.e when it is +configured to connect \fIpassive\fRly. +See also the package \fBtransfer::connect\fR and the description +of the method \fBconnect\fR for where this behaviour comes from. +.TP +\fIobjectName\fR \fBbusy\fR +This method returns a boolean value telling us whether a reception +is in progress (\fBTrue\fR), or not (\fBFalse\fR). +.PP +.SS 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 +\fBtransfer::data::destination\fR and \fBtransfer::connect\fR. +.TP +\fB-command\fR \fIcmdprefix\fR +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 \fBtransfer::copy::do\fR provided +by the package \fBtransfer::copy\fR. +.TP +\fB-mode\fR \fImode\fR +This option specifies the mode the object is in. It is optional and +defaults to \fBactive\fR mode. The two possible modes are: +.RS +.TP +\fBactive\fR +In this mode the two options \fB-host\fR and \fB-port\fR 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. +.TP +\fBpassive\fR +In this mode the option \fB-host\fR has no relevance and is ignored +should it be configured. +The only option the object needs is \fB-port\fR, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner. +.RE +.TP +\fB-host\fR \fIhostname-or-ipaddr\fR +This option specifies the host to connect to in \fIactive\fR mode, +either by name or ip-address. An object configured for \fIpassive\fR +mode ignores this option. +.TP +\fB-port\fR \fIint\fR +For \fIactive\fR mode this option specifies the port the object is +expected to connect to. For \fIpassive\fR mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to \fB0\fR, which allows the OS to choose +the actual port to listen on. +.TP +\fB-socketcmd\fR \fIcommand\fR +This option allows the user to specify which command to use to open a +socket. The default is to use the builtin \fB::socket\fR. Any +compatible with that command is allowed. +.sp +The envisioned main use is the specfication of \fBtls::socket\fR. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the \fBtls\fR package. +.sp +See also section \fBSecure connections\fR. +.TP +\fB-encoding\fR encodingname +.TP +\fB-eofchar\fR eofspec +.TP +\fB-translation\fR transspec +These options are the same as are recognized by the builtin command +\fBfconfigure\fR. 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 \fBconnect\fR). +.TP +\fB-channel\fR \fIhandle\fR +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. +.TP +\fB-file\fR \fIpath\fR +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. +.TP +\fB-variable\fR \fIvarname\fR +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. +.TP +\fB-progress\fR \fIcommand\fR +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. +.PP +.SH "SECURE CONNECTIONS" +One way to secure connections made by objects of this package is to +require the package \fBtls\fR and then configure the option +\fB-socketcmd\fR to force the use of command \fBtls::socket\fR to +open the socket. +.CS + + + # 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 ... + ... + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, data destination, receiver, secure, ssl, tls, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/tqueue.n Index: embedded/man/files/modules/transfer/tqueue.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/tqueue.n @@ -0,0 +1,398 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/tqueue.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::copy::queue" n 0.1 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::copy::queue \- Queued transfers +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBstruct::queue ?1.4?\fR +.sp +package require \fBtransfer::copy ?0.2?\fR +.sp +package require \fBtransfer::copy::queue ?0.1?\fR +.sp +\fBtransfer::copy::queue\fR \fIobjectName\fR \fIoutchannel\fR ?\fIoptions\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBbusy\fR +.sp +\fIobjectName\fR \fBpending\fR +.sp +\fIobjectName\fR \fBput\fR \fIrequest\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +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. +.PP +\fINOTE\fR: +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. +.PP +All transfer requests are of the form +.PP +.CS + + + {type data options...} + +.CE +.PP +where \fItype\fR is in {\fBchan\fR, \fBstring\fR}, and \fIdata\fR +specifies the information to transfer. +For \fBchan\fR the data is the handle of the channel containing the +actual information to transfer, whereas for \fBstring\fR \fIdata\fR +contains directly the information to transfer. +The \fIoptions\fR are a list of them and their values, and are the +same as are accepted by the low-level copy operations of the package +\fBtransfer::copy\fR. +Note how just prepending the request with \fBtransfer::copy::do\fR and +inserting a channel handle in between \fIdata\fR and \fIoptions\fR +easily transforms it from a pure data structure into a command whose +evaluation will perform the request. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fBtransfer::copy::queue\fR \fIobjectName\fR \fIoutchannel\fR ?\fIoptions\fR...? +This command creates a new queue object for the management of the +channel \fIoutchannel\fR, with an associated Tcl command whose name is +\fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::copy::queue\fR command have +the following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +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. +.TP +\fIobjectName\fR \fBbusy\fR +This method returns a boolean value telling us if the object is +currently serving a request (i.e. \fIbusy\fR, value \fBTrue\fR), or +not (i.e. \fIidle\fR, value \fBFalse\fR). +.TP +\fIobjectName\fR \fBpending\fR +This method returns the number of requests currently waiting in the +queue for their execution. A request currently served is not counted +as waiting. +.TP +\fIobjectName\fR \fBput\fR \fIrequest\fR +This method enters the transfer \fIrequest\fR into the object's queue +of waiting requests. +If the object is \fIidle\fR it will become \fIbusy\fR, immediately +servicing the request. Otherwise servicing the new request will be +defered until all preceding requests have been served. +.PP +.SH OPTIONS +The only option known is \fB-on-status-change\fR. 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 +\fBpending\fR and \fBbusy\fR, in this order. This allows any +user to easily know, for example, when the object has processed all +outstanding requests. +.SH 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. +.PP +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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, queue, transfer +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/transfer/transmitter.n Index: embedded/man/files/modules/transfer/transmitter.n ================================================================== --- /dev/null +++ embedded/man/files/modules/transfer/transmitter.n @@ -0,0 +1,500 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/transfer/transmitter.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "transfer::transmitter" n 0.2 tcllib "Data transfer facilities" +.BS +.SH NAME +transfer::transmitter \- Data source +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBsnit ?1.0?\fR +.sp +package require \fBtransfer::copy ?0.2?\fR +.sp +package require \fBtransfer::data::source ?0.2?\fR +.sp +package require \fBtransfer::connect ?0.2?\fR +.sp +package require \fBtransfer::transmitter ?0.2?\fR +.sp +\fBtransfer::transmitter\fR \fIobjectName\fR ?\fIoptions\fR...? +.sp +\fBtransfer::transmitter\fR \fBstream channel\fR \fIchan\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +.sp +\fBtransfer::transmitter\fR \fBstream file\fR \fIpath\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +.sp +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +\fIobjectName\fR \fBstart\fR +.sp +\fIobjectName\fR \fBbusy\fR +.sp +.BE +.SH DESCRIPTION +.PP +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 \fBtransfer::data::source\fR and +\fBtransfer::connect\fR. +.SH API +.SS "PACKAGE COMMANDS" +.TP +\fBtransfer::transmitter\fR \fIobjectName\fR ?\fIoptions\fR...? +This command creates a new transmitter object with an associated Tcl +command whose name is \fIobjectName\fR. +This \fIobject\fR command is explained in full detail in the sections +\fBObject command\fR and \fBObject methods\fR. The set of +supported \fIoptions\fR is explained in section \fBOptions\fR. +.sp +The object command will be created under the current namespace if the +\fIobjectName\fR 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. +.TP +\fBtransfer::transmitter\fR \fBstream channel\fR \fIchan\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +This method creates a fire-and-forget transfer for the data contained +in the channel \fIchan\fR, 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. +.sp +If both \fIhost\fR and \fIport\fR are provided an \fBactive\fR +connection to the destination is made. If only a \fIport\fR is +specified (with \fIhost\fR the empty string) then a \fBpassive\fR +connection is made instead. +.sp +Any arguments after the port are treated as options and are used to +configure the internal transmitter object. +See the section \fBOptions\fR for a list of the supported options +and their meaning. +\fINote\fR however that the signature of the command prefix specified +for the \fB-command\fR 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. +.sp +The result returned by the command is the empty string +if it was set to make an \fIactive\fR connection, and the port the +internal transmitter object is listening on otherwise, i.e when it is +configured to connect \fIpassive\fRly. +See also the package \fBtransfer::connect\fR and the description +of the method \fBconnect\fR for where this behaviour comes from. +.TP +\fBtransfer::transmitter\fR \fBstream file\fR \fIpath\fR \fIhost\fR \fIport\fR ?\fIarg\fR...? +This method is like \fBstream channel\fR, except that the data +contained in the file \fIpath\fR is transfered. +.PP +.SS "OBJECT COMMAND" +All objects created by the \fB::transfer::transmitter\fR command have +the following general form: +.TP +\fIobjectName\fR \fBmethod\fR ?\fIarg arg ...\fR? +The method \fBmethod\fR and its \fIarg\fR'uments determine the +exact behavior of the command. +See section \fBObject methods\fR for the detailed +specifications. +.PP +.SS "OBJECT METHODS" +.TP +\fIobjectName\fR \fBdestroy\fR +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. +.TP +\fIobjectName\fR \fBstart\fR +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. +.sp +The result returned by the method is the empty string +for an object configured to make an \fIactive\fR connection, and the port the +object is listening on otherwise, i.e when it is +configured to connect \fIpassive\fRly. +See also the package \fBtransfer::connect\fR and the description +of the method \fBconnect\fR for where this behaviour comes from. +.TP +\fIobjectName\fR \fBbusy\fR +This method returns a boolean value telling us whether a transmission +is in progress (\fBTrue\fR), or not (\fBFalse\fR). +.PP +.SS 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 +\fBtransfer::data::source\fR and \fBtransfer::connect\fR. +.TP +\fB-blocksize\fR \fIint\fR +This option specifies the size of the chunks to be transmitted in one +block. Usage is optional, its default value is \fB1024\fR. +.TP +\fB-command\fR \fIcmdprefix\fR +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 \fBtransfer::copy::do\fR provided +by the package \fBtransfer::copy\fR. +.TP +\fB-mode\fR \fImode\fR +This option specifies the mode the object is in. It is optional and +defaults to \fBactive\fR mode. The two possible modes are: +.RS +.TP +\fBactive\fR +In this mode the two options \fB-host\fR and \fB-port\fR 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. +.TP +\fBpassive\fR +In this mode the option \fB-host\fR has no relevance and is ignored +should it be configured. +The only option the object needs is \fB-port\fR, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner. +.RE +.TP +\fB-host\fR \fIhostname-or-ipaddr\fR +This option specifies the host to connect to in \fIactive\fR mode, +either by name or ip-address. An object configured for \fIpassive\fR +mode ignores this option. +.TP +\fB-port\fR \fIint\fR +For \fIactive\fR mode this option specifies the port the object is +expected to connect to. For \fIpassive\fR mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to \fB0\fR, which allows the OS to choose +the actual port to listen on. +.TP +\fB-socketcmd\fR \fIcommand\fR +This option allows the user to specify which command to use to open a +socket. The default is to use the builtin \fB::socket\fR. Any +compatible with that command is allowed. +.sp +The envisioned main use is the specfication of \fBtls::socket\fR. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the \fBtls\fR package. +.sp +See also section \fBSecure connections\fR. +.TP +\fB-encoding\fR encodingname +.TP +\fB-eofchar\fR eofspec +.TP +\fB-translation\fR transspec +These options are the same as are recognized by the builtin command +\fBfconfigure\fR. 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 \fBconnect\fR). +.TP +\fB-string\fR \fItext\fR +This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question. +.TP +\fB-channel\fR \fIhandle\fR +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. +.TP +\fB-file\fR \fIpath\fR +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. +.TP +\fB-variable\fR \fIvarname\fR +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. +.TP +\fB-size\fR \fIint\fR +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. +.TP +\fB-progress\fR \fIcommand\fR +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. +.PP +.SH "SECURE CONNECTIONS" +One way to secure connections made by objects of this package is to +require the package \fBtls\fR and then configure the option +\fB-socketcmd\fR to force the use of command \fBtls::socket\fR to +open the socket. +.CS + + + # 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 ... + ... + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItransfer\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel, copy, data source, secure, ssl, tls, transfer, transmitter +.SH CATEGORY +Transfer module +.SH COPYRIGHT +.nf +Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/treeql/treeql.n Index: embedded/man/files/modules/treeql/treeql.n ================================================================== --- /dev/null +++ embedded/man/files/modules/treeql/treeql.n @@ -0,0 +1,851 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/treeql/treeql.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Colin McCormack <coldstore@users.sourceforge.net> +'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "treeql" n 1.3.1 tcllib "Tree Query Language" +.BS +.SH NAME +treeql \- Query tree objects +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBsnit \fR +.sp +package require \fBstruct::list \fR +.sp +package require \fBstruct::set \fR +.sp +package require \fBtreeql ?1.3.1?\fR +.sp +\fBtreeql\fR \fIobjectname\fR \fB-tree\fR \fItree\fR ?\fB-query\fR \fIquery\fR? ?\fB-nodes\fR \fInodes\fR? ?\fIargs\fR...? +.sp +\fIqo\fR \fBquery\fR \fIargs\fR... +.sp +\fIqo\fR \fBresult\fR +.sp +\fIqo\fR \fBdiscard\fR +.sp +.BE +.SH DESCRIPTION +.PP +This package provides objects which can be used to query and transform +tree objects following the API of tree objects created by the package +\fBstruct::tree\fR. +.PP +The tree query and manipulation language used here, TreeQL, is +inspired by Cost (See section \fBReferences\fR for more +information). +.PP +\fBtreeql\fR, 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. +.SH API +.SS "TREEQL CLASS API" +The command \fBtreeql\fR is a \fBsnit\fR::type which implements +the Treeql Query Language. This means that it follows the API for +class commands as specified by the package \fBsnit\fR. +Its general syntax is +.TP +\fBtreeql\fR \fIobjectname\fR \fB-tree\fR \fItree\fR ?\fB-query\fR \fIquery\fR? ?\fB-nodes\fR \fInodes\fR? ?\fIargs\fR...? +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 +\fBTreeQL OBJECT API\fR +.sp +Each query object is associated with a single \fItree\fR object. This +is the object all queries will be run against. +.sp +If the option \fB-nodes\fR 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. +.sp +If the option \fB-query\fR was specified then its argument will be +interpreted as an object, the \fIparent query\fR of this query. It +defaults to the object itself. All queries will be interpreted in the +environment of this object. +.sp +Any arguments coming after the options are treated as a query and run +immediately, after the \fInode set\fR has been initialized. This +uses the same syntax for the query as the method \fBquery\fR. +.sp +The operations of the TreeQL available for this are explained in the +section about \fBThe Tree Query Language\fR. This section also +explains the term \fInode set\fR used above. +.PP +.SS "TREEQL OBJECT API" +As \fBtreeql\fR has been implemented in \fBsnit\fR all the +standard methods of \fBsnit\fR-based classes are available to the +user and therefore not listed here. Please read the documentation for +\fBsnit\fR for what they are and what functionality they provide +.PP +The methods provided by the package \fBtreeql\fR itself are listed +and explained below. +.TP +\fIqo\fR \fBquery\fR \fIargs\fR... +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 \fInode set\fR currently +known to the object to perform its actions. +In other words, the \fInode set\fR is \fInot\fR 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 \fInode set\fR after the last +operator of the query has been executed. +.sp +\fINote\fR that uncaught errors will leave the \fInode set\fR of +the object in an intermediate state, per the TreeQL operators which +were executed successfully before the error occurred. +.sp +The above means in detail that: +.RS +.IP [1] +The first argument is interpreted as the name of a query operator, the +number of arguments required by that operator is then determined, and +taken from the immediately following arguments. +.sp +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. +.IP [2] +The operator is applied to the current node set, yielding a new node +set, and/or manipulating the tree object the query object is connected +to. +.IP [3] +The arguments used (i.e. operator name and arguments) are removed from +the list of method arguments, and then the whole process is repeated +from step [1], until the list of arguments is empty or an error +occurred. +.RE +.sp +.CS + + + # 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 + +.CE +.sp +The operators of the TreeQL language available for this are explained +in the section about \fBThe Tree Query Language\fR. This section +also explains the term \fInode set\fR used above. +.TP +\fIqo\fR \fBresult\fR +This method returns a list containing the current node set. +.TP +\fIqo\fR \fBdiscard\fR +This method returns the current node set (like method +\fBresult\fR), but also destroys the query object (\fIqo\fR). +This is useful when constructing and using sub-queries (%AUTO% objects +immediately destroyed after use). +.PP +.SH "THE TREE QUERY LANGUAGE" +This and the following sections specify the Tree Query Language used +by the query objects of this package in detail. +.PP +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. +.PP +.IP [1] +\fBTreeQL Concepts\fR +.IP [2] +\fBStructural generators\fR +.IP [3] +\fBAttribute Filters\fR +.IP [4] +\fBAttribute Mutators\fR +.IP [5] +\fBAttribute String Accessors\fR +.IP [6] +\fBSub-queries\fR +.IP [7] +\fBNode Set Operators\fR +.IP [8] +\fBNode Set Iterators\fR +.IP [9] +\fBTyped node support\fR +.PP +.PP +.SS "TREEQL CONCEPTS" +The main concept which has to be understood is that of the +\fInode set\fR. +Each query object maintains exactly one such \fInode set\fR, 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 \fIset\fR is a bit of a misnomer, because +.IP [1] +A node (handle) can occur in the structure more than once, and +.IP [2] +the order of nodes in the structure is important as well. +Whenever an operator processes all nodes in the node set it will do so +in the order they occur in the structure. +.PP +.PP +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}. +.SS "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. +.PP +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 \fInot\fR processed by the operator +as well and do not affect the iteration. +.PP +When describing an operator the variable \fBN\fR will be used to refer +to any node in the node set. +.TP +\fBancestors\fR +Replaces the current node set with the ancestors for all nodes \fBN\fR +in the node set, should \fBN\fR 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 \fBN\fR to root, in this +order (root last), for all nodes \fBN\fR in the node set. This +includes the root, but not the node itself. +.TP +\fBrootpath\fR +Replaces the current node set with the ancestors for all nodes \fBN\fR +in the node set, should \fBN\fR have a parent. In other words, nodes +without a parent do not contribute to the new node set. +In contrast to the operator \fBancestors\fR the nodes are added in +reverse order however, i.e. the root node first. +.TP +\fBparent\fR +Replaces the current node set with the parent of node \fBN\fR, for all +nodes \fBN\fR in the node set, should \fBN\fR have a parent. In other +words, nodes without a parent do not contribute to the new node set. +.TP +\fBchildren\fR +Replaces the current node set with the immediate children of node +\fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR have +children. In other words, nodes without children do not contribute to +the new node set. +.TP +\fBleft\fR +Replaces the current node set with the previous/left sibling for all +nodes \fBN\fR in the node set, should \fBN\fR have siblings to the +left. In other words, nodes without left siblings do not contribute to +the new node set. +.TP +\fBright\fR +Replaces the current node set with the next/right sibling for all +nodes \fBN\fR in the node set, should \fBN\fR have siblings to the +right. In other words, nodes without right siblings do not contribute +to the new node set. +.TP +\fBprev\fR +Replaces the current node set with all previous/left siblings of node +\fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR 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). +.TP +\fBesib\fR +Replaces the current node set with all previous/left siblings of node +\fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR 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). +.sp +The method name is a shorthand for \fIEarlier SIBling\fR. +.TP +\fBnext\fR +Replaces the current node set with all next/right siblings of node +\fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR 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). +.TP +\fBroot\fR +Replaces the current node set with a node set containing a single +node, the root of the tree. +.TP +\fBtree\fR +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). +.TP +\fBdescendants\fR +Replaces the current node set with the nodes in all subtrees rooted at +node \fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR +have children. In other words, nodes without children do not +contribute to the new node set. +.sp +This is like the operator \fBchildren\fR, but covers the children +of children as well, i.e. all the \fIproper descendants\fR. "Rooted +at \fBN\fR" means that \fBN\fR itself is not added to the new set, +which is also implied by \fIproper descendants\fR. +.TP +\fBsubtree\fR +Like operator \fBdescendants\fR, but includes the node \fBN\fR. In +other words: +.sp +Replaces the current node set with the nodes of the subtree of node +\fBN\fR, for all nodes \fBN\fR in the node set, should \fBN\fR have +children. In other words, nodes without children do not contribute to +the new node set. I.e this is like the operator \fBchildren\fR, but +covers the children of children, etc. as well. "Of \fBN\fR" means that +\fBN\fR itself is added to the new set. +.TP +\fBforward\fR +Replaces the current node set with the nodes in the subtrees rooted at +the right siblings of node \fBN\fR, for all nodes \fBN\fR in the node +set, should \fBN\fR have right siblings, and they children. In other +words, nodes without right siblings, and them without children are +ignored. +.sp +This is equivalent to the operator sequence +.CS + +next descendants +.CE +.TP +\fBlater\fR +This is an alias for the operator \fBforward\fR. +.TP +\fBbackward\fR +Replaces the current node set with the nodes in the flattened previous +subtrees, in reverse tree order. +.sp +This is nearly equivalent to the operator sequence +.CS + +prev descendants +.CE +.IP +The only difference is that this uses the nodes in reverse order. +.TP +\fBearlier\fR +Replaces the current node set with the nodes in the flattened previous +subtrees, in tree order. +.sp +This is equivalent to the operator sequence +.CS + +prev subtree +.CE +.PP +.SS "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. +.TP +\fBhasatt\fR \fIattr\fR +Reduces the node set to nodes which have an attribute named +\fIattr\fR. +.TP +\fBwithatt\fR \fIattr\fR \fIvalue\fR +Reduces the node set to nodes which have an attribute named +\fIattr\fR, and where the value of that attribute is equal to +\fIvalue\fR (The "==" operator is \fBstring equal -nocase\fR). +.TP +\fBwithatt!\fR \fIattr\fR \fIval\fR +This is the same as \fBwithatt\fR, but all nodes in the node set +have to have the attribute, and the "==" operator is +\fBstring equal\fR, i.e. no \fB-nocase\fR. +The operator will fail with an error if they don't have the attribute. +.TP +\fBattof\fR \fIattr\fR \fIvals\fR +Reduces the node set to nodes which which have an attribute named +\fIattr\fR and where the value of that attribute is contained in the +list \fIvals\fR 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, \fIbut not\fR for the elements of +\fIvals\fR. +.TP +\fBattmatch\fR \fIattr\fR \fImatch\fR +Same as \fBwithatt\fR, but \fBstring match\fR is used as the "==" +operator, and \fImatch\fR is the pattern checked for. +.sp +\fINote\fR that \fImatch\fR is a interpreted as a partial argument +\fIlist\fR for \fBstring match\fR. This means that it is +interpreted as a list containing the pattern, and the pattern element +can be preceded by options understand by \fBstring match\fR, like +\fB-nocase\fR. +This is especially important should the pattern contain spaces. It has +to be wrapped into a list for correct interpretation by this operator +.PP +.SS "ATTRIBUTE MUTATORS" +These operators change node attributes within the underlying tree. In +other words, all these operators have \fIside effects\fR. +.TP +\fBset\fR \fIattr\fR \fIval\fR +Sets the attribute \fIattr\fR to the value \fIval\fR, for all nodes +\fBN\fR in the node set. +The operator will fail if a node does not have an attribute named +\fIattr\fR. The tree will be left in a partially modified state. +.TP +\fBunset\fR \fIattr\fR +Unsets the attribute \fIattr\fR, for all nodes \fBN\fR in the node +set. +The operator will fail if a node does not have an attribute named +\fIattr\fR. The tree will be left in a partially modified state. +.PP +.SS "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. +.PP +In other words, they redefine the semantics of the node set stored by +the query object to contain non-node data after their completion. +.PP +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. +.TP +\fBstring\fR \fIop\fR \fIattr\fR +Applies the string operator \fIop\fR to the attribute named +\fIattr\fR, for all nodes \fBN\fR in the node set, collects the +results of that application and places them into the node set. +.sp +The operator will fail if a node does not have an attribute named +\fIattr\fR. +.sp +The argument \fIop\fR is interpreted as partial argument list for the +builtin command \fBstring\fR. Its first word has to be any of the +sub-commands understood by \fBstring\fR. This has to be followed by +all arguments required for the subcommand, except the last. that last +argument is supplied by the attribute value. +.TP +\fBget\fR \fIpattern\fR +For all nodes \fBN\fR in the node set it determines all their +attributes with names matching the glob \fIpattern\fR, then the values +of these attributes, at last it replaces the node set with the list of +these attribute values. +.TP +\fBattlist\fR +This is a convenience definition for the operator +\fBgetvals *\fR. In other words, it replaces the node set with a +list of the attribute values for all attributes for all nodes \fBN\fR +in the node set. +.TP +\fBattrs\fR \fIglob\fR +Replaces the current node set with a list of attribute lists, one +attribute list per for all nodes \fBN\fR in the node set. +.TP +\fBattval\fR \fIattname\fR +Reduces the current node set with the operator \fBhasatt\fR, and +then replaces it with a list containing the values of the attribute +named \fIattname\fR for all nodes \fBN\fR in the node set. +.PP +.SS SUB-QUERIES +Sub-queries yield node sets which are then used to augment, reduce or +replace the current node set. +.TP +\fBandq\fR \fIquery\fR +Replaces the node set with the set-intersection of the node set +generated by the sub-query \fIquery\fR and itself. +.sp +The execution of the sub-query uses the current node set as its own +initial node set. +.TP +\fBorq\fR \fIquery\fR +Replaces the node set with the set-union of the node set generated by +the sub-query \fIquery\fR and itself. Duplicate nodes are removed. +.sp +The execution of the sub-query uses the current node set as its own +initial node set. +.TP +\fBnotq\fR \fIquery\fR +Replaces the node set with the set of nodes generated by the sub-query +\fIquery\fR 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. +.sp +The execution of the sub-query uses the current node set as its own +initial node set. +.PP +.SS "NODE SET OPERATORS" +These operators change the node set directly, without referring to the +tree. +.TP +\fBunique\fR +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. +.TP +\fBselect\fR +Replaces the current node set with a node set containing only the +first node from the current node set +.TP +\fBtransform\fR \fIquery\fR \fIvar\fR \fIbody\fR +First it interprets the sub-query \fIquery\fR, 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 \fIvar\fR, and executing the script +\fIbody\fR. +The collected results of these executions is made the new node set, +replacing the current one. +.sp +The script \fIbody\fR is executed in the context of the caller. +.TP +\fBmap\fR \fIvar\fR \fIbody\fR +Iterates over the current node set, binding the handle of each node to +the variable named in \fIvar\fR, and executing the script \fIbody\fR. +The collected results of these executions is made the new node set, +replacing the current one. +.sp +The script \fIbody\fR is executed in the context of the caller. +.TP +\fBquote\fR \fIval\fR +Appends the literal value \fIval\fR to the current node set. +.TP +\fBreplace\fR \fIval\fR +Replaces the current node set with the literal list value \fIval\fR. +.PP +.SS "NODE SET ITERATORS" +.TP +\fBforeach\fR \fIquery\fR \fIvar\fR \fIbody\fR +Interprets the sub-query \fIquery\fR, then performs the equivalent of +operator \fBover\fR 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 \fIbody\fR. +.sp +The script \fIbody\fR is executed in the context of the caller. +.TP +\fBwith\fR \fIquery\fR \fIbody\fR +Interprets the \fIquery\fR, then runs the script \fIbody\fR 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. +.sp +The script \fIbody\fR is executed in the context of the caller. +.TP +\fBover\fR \fIvar\fR \fIbody\fR +Executes the script \fIbody\fR for each node in the node set, with the +variable named by \fIvar\fR bound to the name of the current node. +The script \fIbody\fR is executed in the context of the caller. +.sp +This is like the builtin \fBforeach\fR, with the node set as the +source of the list to iterate over. +.sp +The results of executing the \fIbody\fR are ignored. +.TP +\fBdelete\fR +Deletes all the nodes contained in the current node set from the tree. +.PP +.SS "TYPED NODE SUPPORT" +These filters and accessors assume the existence of an attribute +called \fB@type\fR, and are short-hand forms useful for cost-like +tree query, html tree editing, and so on. +.TP +\fBnodetype\fR +Returns the node type of nodes. +Attribute string accessor. This is equivalent to +.CS + +get @type +.CE +.TP +\fBoftype\fR \fIt\fR +Reduces the node set to nodes whose type is equal to \fIt\fR, with +letter case ignored. +.TP +\fBnottype\fR \fIt\fR +Reduces the node set to nodes whose type is not equal to \fIt\fR, with +letter case ignored. +.TP +\fBoftypes\fR \fIattrs\fR +Reduces set to nodes whose @type is an element in the list \fIattrs\fR +of types. The value of @type is used as a glob pattern, and letter +case is relevant. +.PP +.SH EXAMPLES +... TODO ... +.SH REFERENCES +.IP [1] +\fICOST\fR [http://wiki.tcl.tk/COST] on the Tcler's Wiki. +.IP [2] +\fITreeQL\fR [http://wiki.tcl.tk/treeql] on the Tcler's Wiki. Discuss +this package there. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItreeql\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +Cost, DOM, TreeQL, XPath, XSLT, structured queries, tree, tree query language +.SH CATEGORY +Data structures +.SH COPYRIGHT +.nf +Copyright (c) 2004 Colin McCormack <coldstore@users.sourceforge.net> +Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/try/tcllib_try.n Index: embedded/man/files/modules/try/tcllib_try.n ================================================================== --- /dev/null +++ embedded/man/files/modules/try/tcllib_try.n @@ -0,0 +1,366 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/try/tcllib_try.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Donal K. Fellows, BSD licensed +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "try" n 1 tcllib "Forward compatibility implementation of [try]" +.BS +.SH NAME +try \- try - Trap and process errors and exceptions +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBtry ?1?\fR +.sp +\fB::try\fR \fIbody\fR ?\fIhandler...\fR? ?\fBfinally\fR \fIscript\fR? +.sp +.BE +.SH DESCRIPTION +.PP +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. +.TP +\fB::try\fR \fIbody\fR ?\fIhandler...\fR? ?\fBfinally\fR \fIscript\fR? +This command executes the script \fIbody\fR 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 \fBfinally\fR clause is present, the +\fIscript\fR it includes will be run and the result of the handler (or +the \fIbody\fR if no handler matched) is allowed to continue to +propagate. Note that the \fBfinally\fR clause is processed even if +an error occurs and irrespective of which, if any, \fIhandler\fR is +used. +.sp +The \fIhandler\fR clauses are each expressed as several words, +and must have one of the following forms: +.RS +.TP +\fBon\fR \fIcode variableList script\fR +This clause matches if the evaluation of \fIbody\fR completed with the +exception code \fIcode\fR. The \fIcode\fR may be expressed as an +integer or one of the following literal words: +\fBok\fR, \fBerror\fR, \fBreturn\fR, \fBbreak\fR, or +\fBcontinue\fR. Those literals correspond to the integers 0 through +4 respectively. +.TP +\fBtrap\fR \fIpattern variableList script\fR +This clause matches if the evaluation of \fIbody\fR resulted in an +error and the prefix of the \fB-errorcode\fR from the interpreter's +status dictionary is equal to the \fIpattern\fR. The number of prefix +words taken from the \fB-errorcode\fR is equal to the list-length +of \fIpattern\fR, and inter-word spaces are normalized in both the +\fB-errorcode\fR and \fIpattern\fR before comparison. +.sp +The \fIvariableList\fR word in each \fIhandler\fR 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 \fIbody\fR (from the main \fBtry\fR) 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 \fIbody\fR will be placed. +.sp +The \fIscript\fR word of each \fIhandler\fR is also always +interpreted the same: as a Tcl script to evaluate if the clause is +matched. If \fIscript\fR is a literal \fB-\fR and the \fIhandler\fR +is not the last one, the \fIscript\fR of the following \fIhandler\fR +is invoked instead (just like with the \fBswitch\fR command). +.sp +Note that \fIhandler\fR clauses are matched against in order, +and that the first matching one is always selected. +At most one \fIhandler\fR clause will selected. +As a consequence, an \fBon error\fR will mask any subsequent +\fBtrap\fR in the \fBtry\fR. Also note that \fBon error\fR is +equivalent to \fBtrap {}\fR. +.sp +If an exception (i.e. any non-\fBok\fR result) occurs during +the evaluation of either the \fIhandler\fR or the \fBfinally\fR +clause, the original exception's status dictionary will be added to +the new exception's status dictionary under the \fB-during\fR key. +.RE +.PP +.SH EXAMPLES +Ensure that a file is closed no matter what: +.PP +.CS + + +set f [open /some/file/name a] +\fBtry\fR { + puts \\$f "some message" + # ... +} \fBfinally\fR { + close \\$f +} + +.CE +.PP +Handle different reasons for a file to not be openable for reading: +.PP +.CS + + +\fBtry\fR { + set f [open /some/file/name] +} \fBtrap\fR {POSIX EISDIR} {} { + puts "failed to open /some/file/name: it's a directory" +} \fBtrap\fR {POSIX ENOENT} {} { + puts "failed to open /some/file/name: it doesn't exist" +} + +.CE +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fItry\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +catch(n), error(n), return(n), throw(n) +.SH KEYWORDS +cleanup, error, exception, final, resource management +.SH CATEGORY +Utility +.SH COPYRIGHT +.nf +Copyright (c) 2008 Donal K. Fellows, BSD licensed + +.fi ADDED embedded/man/files/modules/uev/uevent.n Index: embedded/man/files/modules/uev/uevent.n ================================================================== --- /dev/null +++ embedded/man/files/modules/uev/uevent.n @@ -0,0 +1,436 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/uev/uevent.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uevent" n 0.3.1 tcllib "User events" +.BS +.SH NAME +uevent \- User events +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBuevent ?0.3.1?\fR +.sp +package require \fBlogger \fR +.sp +\fB::uevent::bind\fR \fItag\fR \fIevent\fR \fIcommand\fR +.sp +\fBcommand\fR \fItag\fR \fIevent\fR \fIdetails\fR +.sp +\fB::uevent::unbind\fR \fItoken\fR +.sp +\fB::uevent::generate\fR \fItag\fR \fIevent\fR ?\fIdetails\fR? +.sp +\fB::uevent::list\fR +.sp +\fB::uevent::list\fR \fItag\fR +.sp +\fB::uevent::list\fR \fItag\fR \fIevent\fR +.sp +\fB::uevent::watch::tag::add\fR \fIpattern\fR \fIcommand\fR +.sp +\fB{*}command\fR \fBbound\fR \fItag\fR +.sp +\fB{*}command\fR \fBunbound\fR \fItag\fR +.sp +\fB::uevent::watch::tag::remove\fR \fItoken\fR +.sp +\fB::uevent::watch::event::add\fR \fItag_pattern\fR \fIevent_pattern\fR \fIcommand\fR +.sp +\fB{*}command\fR \fBbound\fR \fItag\fR \fIevent\fR +.sp +\fB{*}command\fR \fBunbound\fR \fItag\fR \fIevent\fR +.sp +\fB::uevent::watch::event::remove\fR \fItoken\fR +.sp +.BE +.SH 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. +.PP +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. +.PP +Here we can, by assuming that each object in question is represented +by its own tag. Which is possible as we allow arbitrary tags. +.PP +More differences: +.IP [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. +.IP [2] +This package triggers all bound commands for a tag/event combination, +and they are independent of each other. A bound command cannot force +the event processing core to abort the processing of command coming +after it. +.PP +.SH 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. +.TP +\fB::uevent::bind\fR \fItag\fR \fIevent\fR \fIcommand\fR +Using this command registers the \fIcommand\fR prefix to be triggered +when the \fIevent\fR occurs for the \fItag\fR. The result of the +command is an opaque token representing the binding. Note that if the +same combination of <\fItag\fR,\fIevent\fR,\fIcommand\fR> is used +multiple times the same token is returned by every call. +.sp +The signature of the \fIcommand\fR prefix is +.RS +.TP +\fBcommand\fR \fItag\fR \fIevent\fR \fIdetails\fR +.RE +.sp +where \fIdetails\fR 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. +.TP +\fB::uevent::unbind\fR \fItoken\fR +This command releases the event binding represented by the +\fItoken\fR. The token has to be the result of a call to +\fB::uevent::bind\fR. The result of the command is the empty string. +.TP +\fB::uevent::generate\fR \fItag\fR \fIevent\fR ?\fIdetails\fR? +This command generates an \fIevent\fR for the \fItag\fR, triggering +all commands bound to that combination. The \fIdetails\fR 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. +.sp +Note that all bound commands are triggered, independently of each +other. The event handlers cannot assume a specific order. They are +also \fInot\fR 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. +.sp +Generating an event for an unknown tag, or for a +<\fItag\fR,\fIevent\fR> combination which has no commands bound to it +is allowed, such calls will be ignored. +.TP +\fB::uevent::list\fR +In this form the command returns a list containing the names of all +tags which have events with commands bound to them. +.TP +\fB::uevent::list\fR \fItag\fR +In this format the command returns a list containing the names of all +events for the \fItag\fR 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. +.TP +\fB::uevent::list\fR \fItag\fR \fIevent\fR +In this format the command returns a list containing all commands +bound to the \fIevent\fR for the \fItag\fR. Specifying an unknown tag +or unknown event, will cause the command to throw an error. +.TP +\fB::uevent::watch::tag::add\fR \fIpattern\fR \fIcommand\fR +This command sets up a sort of reverse events. Events generated, +i.e. the \fIcommand\fR prefix invoked, when observers bind to and +unbind from specific tags. +.sp +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. +.sp +The signature of the \fIcommand\fR prefix is +.RS +.TP +\fB{*}command\fR \fBbound\fR \fItag\fR +.TP +\fB{*}command\fR \fBunbound\fR \fItag\fR +.RE +.sp +The result of the command is a token representing the watcher. +.TP +\fB::uevent::watch::tag::remove\fR \fItoken\fR +This command removes a watcher for (un)bind events on tags. +.sp +The result of the command is the empty string. +.TP +\fB::uevent::watch::event::add\fR \fItag_pattern\fR \fIevent_pattern\fR \fIcommand\fR +This command sets up a sort of reverse events. Events generated, +i.e. the \fIcommand\fR prefix invoked, when observers bind to and +unbind from specific combinations of tags and events. +.sp +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. +.sp +The signature of the \fIcommand\fR prefix is +.RS +.TP +\fB{*}command\fR \fBbound\fR \fItag\fR \fIevent\fR +.TP +\fB{*}command\fR \fBunbound\fR \fItag\fR \fIevent\fR +.RE +.sp +The result of the command is a token representing the watcher. +.TP +\fB::uevent::watch::event::remove\fR \fItoken\fR +This command removes a watcher for (un)bind events on tag/event +combinations. +.sp +The result of the command is the empty string. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIuevent\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +hook(n) +.SH KEYWORDS +bind, event, generate event, hook, unbind +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/uev/uevent_onidle.n Index: embedded/man/files/modules/uev/uevent_onidle.n ================================================================== --- /dev/null +++ embedded/man/files/modules/uev/uevent_onidle.n @@ -0,0 +1,301 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/uev/uevent_onidle.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uevent::onidle" n 0.1 tcllib "User events" +.BS +.SH NAME +uevent::onidle \- Request merging and deferal to idle time +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBuevent::onidle ?0.1?\fR +.sp +package require \fBlogger \fR +.sp +\fB::uevent::onidle\fR \fIobjectName\fR \fIcommandprefix\fR +.sp +\fIobjectName\fR \fBrequest\fR +.sp +.BE +.SH 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. +.SH API +The package exports a class, \fBuevent::onidle\fR, as specified +below. +.TP +\fB::uevent::onidle\fR \fIobjectName\fR \fIcommandprefix\fR +The command creates a new \fIonidle\fR object with an associated +global Tcl command whose name is \fIobjectName\fR. This command may +be used to invoke various operations on the object. +.sp +The \fIcommandprefix\fR is the action to perform when the event loop +is idle and the user asked for it using the method \fBrequest\fR +(See below). +.PP +The object commands created by the class commands above have +the form: +.TP +\fIobjectName\fR \fBrequest\fR +This method requests the execution of the command prefix specified +during the construction of \fIobjectName\fR the next time the event +loop is idle. Multiple requests are merged and cause only one +execution of the command prefix. +.PP +.SH 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. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIuevent\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +callback, deferal, event, idle, merge, on-idle +.SH COPYRIGHT +.nf +Copyright (c) 2008 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/units/units.n Index: embedded/man/files/modules/units/units.n ================================================================== --- /dev/null +++ embedded/man/files/modules/units/units.n @@ -0,0 +1,608 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/units/units.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2000-2005 Mayo Foundation +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "units" n 1.2 tcllib "Convert and manipulate quantities with units" +.BS +.SH NAME +units \- unit conversion +.SH SYNOPSIS +package require \fBTcl 8.1\fR +.sp +package require \fBunits ?2.1?\fR +.sp +\fB::units::convert\fR \fIvalue\fR \fItargetUnits\fR +.sp +\fB::units::reduce\fR \fIunitString\fR +.sp +\fB::units::new\fR \fIname\fR \fIbaseUnits\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +The units conversion facility is also able to convert between +compatible units. If, for example, a application is expecting a value +in \fIohms\fR (Resistance), and the user specifies units of +\fImilliwebers/femtocoulomb\fR, the conversion routine will +handle it appropriately. An error will be generated if an incorrect +conversion is attempted. +.PP +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. +.PP +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 \fIinch\fR as \fI2.54 cm\fR. +.SH COMMANDS +.TP +\fB::units::convert\fR \fIvalue\fR \fItargetUnits\fR +Converts the \fIvalue\fR string into a floating point number, scaled to the +specified \fItargetUnits\fR. The \fIvalue\fR string may contain a +number and units. If units are specified, then they must be +compatible with the \fItargetUnits\fR. If units are not specified +for the \fIvalue\fR, then it will be scaled to the target units. For +example, +.CS + + +% ::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 + +.CE +.TP +\fB::units::reduce\fR \fIunitString\fR +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 +\fIunitString\fR is invalid. +.CS + + +% ::units::reduce pascal +1000.0 gram / meter second second + +.CE +.TP +\fB::units::new\fR \fIname\fR \fIbaseUnits\fR +Creates a new unit conversion with the specified name. The new unit +\fIname\fR must be only alphabetic (upper or lower case) letters. +The \fIbaseUnits\fR 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 \fI-primitive\fR 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. +.CS + + +% ::units::new furlong "220 yards" +% ::units::new fortnight "14 days" +% ::units::convert 100m/s furlongs/fortnight +601288.475303 + +.CE +.PP +.SH "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. +.IP \(bu +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. +.IP \(bu +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 \fIm-kg/s^2\fR are pleasantly +readable. +.IP \(bu +The forward-slash seperator ("/") indicates that following subunits are +in the denominator. There can be at most one forward-slash separator. +.IP \(bu +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.) +.IP \(bu +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.) +.PP +.SS "EXAMPLE VALID UNIT STRINGS" +.CS + + +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 + +.CE +.SH "SI UNITS" +.PP +The standard SI units are predefined according to \fINIST Special +Publication 330\fR. 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. +.SS "SI BASE UNITS" +.CS + + +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 + +.CE +.SS "SI DERIVED UNITS WITH SPECIAL NAMES" +.CS + + +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 + +.CE +.PP +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. +.PP +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. +.PP +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 \fISpecial Publication +330\fR. +.SS "SI PREFIXES" +.CS + + +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 + +.CE +.PP +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. +.PP +Many non-SI units are commonly used in applications. Appendix B.8 of +\fINIST Special Publication 811\fR 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 \fBnew\fR +command, but some well known and often used conversions are included +in this package. +.SS "NON-SI UNITS" +.CS + + +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 + +.CE +.SS "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 +\fIlength\fR values properly reduced to \fImeters\fR, or +that all \fIvelocity\fR values properly reduced to +\fImeters/second\fR. +.PP +A C implementation of this package has been created to work in +conjunction with the Simplified Wrapper Interface Generator +(\fIhttp://www.swig.org/\fR). 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., \fItypedef float Length\fR), 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. +.PP +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 \fINIST Publication +330\fR. The quantity \fIarea\fR, for example, could be +defined as units properly reducing to \fImeter^2\fR, although +the utility of defining a unit named \fIsquare meter\fR is +arguable. +.SH 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 \fINIST Special Publication 330: The International System of +Units (SI)\fR and \fINIST Special Publication 811: Guide for +the Use of the International System of Units (SI)\fR. Both of +these publications are available (as of December 2000) from +\fIhttp://physics.nist.gov/cuu/Reference/contents.html\fR +.PP +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 \fIhttp://www.gnu.org/software/units/\fR +.SH AUTHORS +Robert W. Techentin +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIunits\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +angle, constants, conversion, distance, radians, unit +.SH COPYRIGHT +.nf +Copyright (c) 2000-2005 Mayo Foundation + +.fi ADDED embedded/man/files/modules/uri/uri.n Index: embedded/man/files/modules/uri/uri.n ================================================================== --- /dev/null +++ embedded/man/files/modules/uri/uri.n @@ -0,0 +1,404 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/uri/uri.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uri" n 1.2.2 tcllib "Tcl Uniform Resource Identifier Management" +.BS +.SH NAME +uri \- URI utilities +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBuri ?1.2.2?\fR +.sp +\fBuri::split\fR \fIurl\fR ?\fIdefaultscheme\fR? +.sp +\fBuri::join\fR ?\fIkey\fR \fIvalue\fR?... +.sp +\fBuri::resolve\fR \fIbase\fR \fIurl\fR +.sp +\fBuri::isrelative\fR \fIurl\fR +.sp +\fBuri::geturl\fR \fIurl\fR ?\fIoptions\fR...? +.sp +\fBuri::canonicalize\fR \fIuri\fR +.sp +\fBuri::register\fR \fIschemeList\fR \fIscript\fR +.sp +.BE +.SH DESCRIPTION +This package contains two parts. First it provides regular expressions +for a number of url/uri schemes. Second it provides a number of +commands for manipulating urls/uris and fetching data specified by +them. For the latter this package analyses the requested url/uri and +then dispatches it to the appropriate package (http, ftp, ...) for +actual fetching. +.PP +The package currently does not conform to +RFC 2396 (\fIhttp://www.rfc-editor.org/rfc/rfc2396.txt\fR), +but quite likely should be. Patches and other help are welcome. +.SH COMMANDS +.TP +\fBuri::split\fR \fIurl\fR ?\fIdefaultscheme\fR? +\fBuri::split\fR takes an \fIurl\fR, decodes it and then returns a +list of key/value pairs suitable for \fBarray set\fR containing the +constituents of the \fIurl\fR. If the scheme is missing from the url +it defaults to the value of \fIdefaultscheme\fR if it was specified, +or \fIhttp\fR else. Currently only the schemes \fIhttp\fR, +\fIftp\fR, \fImailto\fR, \fIurn\fR, \fInews\fR, \fIldap\fR and +\fIfile\fR are supported by the package itself. +See section \fBEXTENDING\fR on how to expand that range. +.sp +The set of constituents of an url (= the set of keys in the returned +dictionary) is dependent on the scheme of the url. The only key which +is therefore always present is \fBscheme\fR. For the following +schemes the constituents and their keys are known: +.RS +.TP +ftp +\fBuser\fR, \fBpwd\fR, \fBhost\fR, \fBport\fR, +\fBpath\fR, \fBtype\fR +.TP +http(s) +\fBuser\fR, \fBpwd\fR, \fBhost\fR, \fBport\fR, +\fBpath\fR, \fBquery\fR, \fBfragment\fR. The fragment +is optional. +.TP +file +\fBpath\fR, \fBhost\fR. The host is optional. +.TP +mailto +\fBuser\fR, \fBhost\fR. The host is optional. +.TP +news +Either \fBmessage-id\fR or \fBnewsgroup-name\fR. +.RE +.sp +.TP +\fBuri::join\fR ?\fIkey\fR \fIvalue\fR?... +\fBuri::join\fR takes a list of key/value pairs (generated by +\fBuri::split\fR, for example) and returns the canonical url they +represent. Currently only the schemes \fIhttp\fR, \fIftp\fR, +\fImailto\fR, \fIurn\fR, \fInews\fR, \fIldap\fR and \fIfile\fR +are supported. See section \fBEXTENDING\fR on how to expand that +range. +.TP +\fBuri::resolve\fR \fIbase\fR \fIurl\fR +\fBuri::resolve\fR resolves the specified \fIurl\fR relative to +\fIbase\fR. In other words: A non-relative \fIurl\fR is returned +unchanged, whereas for a relative \fIurl\fR the missing parts are +taken from \fIbase\fR and prepended to it. The result of this +operation is returned. For an empty \fIurl\fR the result is +\fIbase\fR. +.TP +\fBuri::isrelative\fR \fIurl\fR +\fBuri::isrelative\fR determines whether the specified \fIurl\fR is +absolute or relative. +.TP +\fBuri::geturl\fR \fIurl\fR ?\fIoptions\fR...? +\fBuri::geturl\fR decodes the specified \fIurl\fR and then dispatches +the request to the package appropriate for the scheme found in the +url. The command assumes that the package to handle the given scheme +either has the same name as the scheme itself (including possible +capitalization) followed by \fB::geturl\fR, or, in case of this +failing, has the same name as the scheme itself (including possible +capitalization). It further assumes that whatever package was loaded +provides a \fBgeturl\fR-command in the namespace of the same name as +the package itself. This command is called with the given \fIurl\fR +and all given \fIoptions\fR. Currently \fBgeturl\fR does not handle +any options itself. +.sp +\fINote:\fR \fIfile\fR-urls are an exception to the rule +described above. They are handled internally. +.sp +It is not possible to specify results of the command. They depend on +the \fBgeturl\fR-command for the scheme the request was dispatched to. +.TP +\fBuri::canonicalize\fR \fIuri\fR +\fBuri::canonicalize\fR returns the canonical form of a URI. The +canonical form of a URI is one where relative path specifications, +ie. . and .., have been resolved. +.TP +\fBuri::register\fR \fIschemeList\fR \fIscript\fR +\fBuri::register\fR registers the first element of \fIschemeList\fR as +a new scheme and the remaining elements as aliases for this scheme. It +creates the namespace for the scheme and executes the \fIscript\fR in +the new namespace. The script has to declare variables containing the +regular expressions relevant to the scheme. At least the variable +\fBschemepart\fR has to be declared as that one is used to extend +the variables keeping track of the registered schemes. +.PP +.SH SCHEMES +In addition to the commands mentioned above this package provides +regular expression to recognize urls for a number of url schemes. +.PP +For each supported scheme a namespace of the same name as the scheme +itself is provided inside of the namespace \fIuri\fR containing the +variable \fBurl\fR whose contents are a regular expression to +recognize urls of that scheme. Additional variables may contain +regular expressions for parts of urls for that scheme. +.PP +The variable \fBuri::schemes\fR contains a list of all supported +schemes. Currently these are \fIftp\fR, \fIldap\fR, \fIfile\fR, +\fIhttp\fR, \fIgopher\fR, \fImailto\fR, \fInews\fR, +\fIwais\fR and \fIprospero\fR. +.SH EXTENDING +Extending the range of schemes supported by \fBuri::split\fR and +\fBuri::join\fR is easy because both commands do not handle the +request by themselves but dispatch it to another command in the +\fIuri\fR namespace using the scheme of the url as criterion. +.PP +\fBuri::split\fR and \fBuri::join\fR +call \fBSplit[string totitle <scheme>]\fR +and \fBJoin[string totitle <scheme>]\fR respectively. +.SH CREDITS +.PP +Original code (regular expressions) by Andreas Kupries. +Modularisation by Steve Ball, also the split/join/resolve +functionality. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIuri\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +fetching information, file, ftp, gopher, http, ldap, mailto, news, prospero, rfc 2255, rfc 2396, uri, url, wais, www +.SH CATEGORY +Networking ADDED embedded/man/files/modules/uri/urn-scheme.n Index: embedded/man/files/modules/uri/urn-scheme.n ================================================================== --- /dev/null +++ embedded/man/files/modules/uri/urn-scheme.n @@ -0,0 +1,283 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/uri/urn-scheme.n' by tcllib/doctools with format 'nroff' +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uri_urn" n 1.1.2 tcllib "Tcl Uniform Resource Identifier Management" +.BS +.SH NAME +uri_urn \- URI utilities, URN scheme +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBuri::urn ?1.1.2?\fR +.sp +\fBuri::urn::quote\fR \fIurl\fR +.sp +\fBuri::urn::unquote\fR \fIurl\fR +.sp +.BE +.SH DESCRIPTION +This package provides two commands to quote and unquote the disallowed +characters for url using the \fIurn\fR scheme, registers the scheme +with the package \fBuri\fR, and provides internal helpers which +will be automatically used by the commands \fBuri::split\fR and +\fBuri::join\fR of package \fBuri\fR to handle urls using the +\fIurn\fR scheme. +.SH COMMANDS +.TP +\fBuri::urn::quote\fR \fIurl\fR +This command quotes the characters disallowed by the \fIurn\fR scheme +(per RFC 2141 sec2.2) in the \fIurl\fR and returns the modified url as +its result. +.TP +\fBuri::urn::unquote\fR \fIurl\fR +This commands performs the reverse of \fB::uri::urn::quote\fR. It +takes an \fIurn\fR url, removes the quoting from all disallowed +characters, and returns the modified urls as its result. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIuri\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +rfc 2141, uri, url, urn +.SH CATEGORY +Networking ADDED embedded/man/files/modules/uuid/uuid.n Index: embedded/man/files/modules/uuid/uuid.n ================================================================== --- /dev/null +++ embedded/man/files/modules/uuid/uuid.n @@ -0,0 +1,299 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/uuid/uuid.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "uuid" n 1.0.2 tcllib "uuid" +.BS +.SH NAME +uuid \- UUID generation and comparison +.SH SYNOPSIS +package require \fBTcl 8.2\fR +.sp +package require \fBuuid ?1.0.2?\fR +.sp +\fB::uuid::uuid generate\fR +.sp +\fB::uuid::uuid equal\fR \fIid1\fR \fIid2\fR +.sp +.BE +.SH DESCRIPTION +.PP +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. +.SH COMMANDS +.TP +\fB::uuid::uuid generate\fR +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. +.TP +\fB::uuid::uuid equal\fR \fIid1\fR \fIid2\fR +Compares two uuids and returns true if both arguments are the same uuid. +.PP +.SH EXAMPLES +.CS + + +% uuid::uuid generate +b12dc22c-5c36-41d2-57da-e29d0ef5839c + +.CE +.SH REFERENCES +.IP [1] +Paul J. Leach, "UUIDs and GUIDs", February 1998. +(\fIhttp://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt\fR) +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIuuid\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +GUID, UUID +.SH CATEGORY +Hashes, checksums, and encryption +.SH COPYRIGHT +.nf +Copyright (c) 2004, Pat Thoyts <patthoyts@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/cat.n Index: embedded/man/files/modules/virtchannel_base/cat.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/cat.n @@ -0,0 +1,295 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/cat.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::cat" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::cat \- Concatenation channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::core ?1?\fR +.sp +package require \fBtcl::chan::cat ?1?\fR +.sp +\fB::tcl::chan::cat\fR \fIchan\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::cat\fR 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 cahnnel is the concatentation of the +contents of all the sub-ordinate channels. +.PP +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. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::core\fR framework. +.PP +Event handling is delegated to the currently active sub-channel. +.SH API +.TP +\fB::tcl::chan::cat\fR \fIchan\fR... +This command creates the concatenation channel using all the provided +channels, and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +concatenation channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/facade.n Index: embedded/man/files/modules/virtchannel_base/facade.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/facade.n @@ -0,0 +1,319 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/facade.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::facade" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::facade \- Facade channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBlogger \fR +.sp +package require \fBtcl::chan::core ?1?\fR +.sp +package require \fBtcl::chan::facade ?1?\fR +.sp +\fB::tcl::chan::facade\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::facade\fR package provides a command creating +facades to other channels. These are channels which own a single +subordinate channel and delegate all operations to. +.PP +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. +.PP +Therefore this channel, usable with Tcl 8.5, and having access +to everything going on for a channel. +.PP +The intercepted actions on channel are logged through package +\fBlogger\fR. +.PP +Beyond that facades provide the following additional channel +configuration options: +.TP +\fB-self\fR +The TclOO object handling the facade. +.TP +\fB-fd\fR +The handle of the subordinate, i.e. wrapped channel. +.TP +\fB-used\fR +The last time the wrapped channel was read from or written to by +the facade, as per \fBclock milliseconds\fR. A value of \fB0\fR +indicates that the subordinate channel was not accessed at all, yet. +.TP +\fB-created\fR +The time the facade was created, as per \fBclock milliseconds\fR. +.TP +\fB-user\fR +A free-form value identifying the user of the facade and its +wrapped channel. +.PP +Of these only option \fB-user\fR is writable. +.SH API +.TP +\fB::tcl::chan::facade\fR \fIchan\fR +This command creates the facade channel around the provided +channel \fIchan\fR, and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +concatenation channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/fifo.n Index: embedded/man/files/modules/virtchannel_base/fifo.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/fifo.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/fifo.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::fifo" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::fifo \- In-memory fifo channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::fifo ?1?\fR +.sp +\fB::tcl::chan::fifo\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::fifo\fR package provides a command creating +channels which live purely in memory. Access is fifo-like, i.e. things +are read out of the channel in the order they were written to it. +This is equivalent to the fifo channels provided by the package +\fBMmechan\fR, except that this is written in pure Tcl, not C. On +the other hand, \fBMemchan\fR is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and \fBTclOO\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::fifo\fR +This command creates a new fifo channel and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +fifo, in-memory channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/fifo2.n Index: embedded/man/files/modules/virtchannel_base/fifo2.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/fifo2.n @@ -0,0 +1,295 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/fifo2.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::fifo2" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::fifo2 \- In-memory interconnected fifo channels +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::halfpipe ?1?\fR +.sp +package require \fBtcl::chan::fifo2 ?1?\fR +.sp +\fB::tcl::chan::fifo2\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::fifo2\fR 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 +\fBMmechan\fR, except that this is written in pure Tcl, not C. On +the other hand, \fBMemchan\fR is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and \fBTclOO\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::fifo2\fR +This command creates a new connected pair of fifo channels and returns +their handles, as a list containing two elements. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +connected fifos, fifo, in-memory channel, inter-thread communication, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/halfpipe.n Index: embedded/man/files/modules/virtchannel_base/halfpipe.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/halfpipe.n @@ -0,0 +1,321 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/halfpipe.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::halfpipe" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::halfpipe \- In-memory channel, half of a fifo2 +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::halfpipe ?1?\fR +.sp +package require \fBtcl::chan::halfpipe ?1?\fR +.sp +\fB::tcl::chan::halfpipe\fR ?\fB-option\fR \fIvalue\fR...? +.sp +\fIobjectCmd\fR \fBput\fR \fIbytes\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::halfpipe\fR package provides a command creating +one half of a \fBtcl::chan::fifo2\fR 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. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::halfpipe\fR ?\fB-option\fR \fIvalue\fR...? +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 \fBOptions\fR 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 +\fBput\fR method for adding data to the channel. +.sp +Two halfpipes with a bit of glue logic in the callbacks make +for one \fBtcl::chan::fifo2\fR. +.TP +\fIobjectCmd\fR \fBput\fR \fIbytes\fR +This method of the channel handler object puts the data \fIbytes\fR +into the channel so that it can be read from it. +.PP +.SH OPTIONS +.TP +\fB-close-command\fR 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. +.TP +\fB-write-command\fR 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. +.TP +\fB-empty-command\fR 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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +callbacks, fifo, in-memory channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/memchan.n Index: embedded/man/files/modules/virtchannel_base/memchan.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/memchan.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/memchan.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::memchan" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::memchan \- In-memory channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::memchan ?1?\fR +.sp +\fB::tcl::chan::memchan\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::memchan\fR 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 \fBMemchan\fR, except that this is written in pure Tcl, +not C. On the other hand, \fBMemchan\fR is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +\fBTclOO\fR. +.PP +Packages related to this are \fBtcl::chan::string\fR and +\fBtcl::chan::variable\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::memchan\fR +This command creates a new memchan channel and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +in-memory channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/null.n Index: embedded/man/files/modules/virtchannel_base/null.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/null.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/null.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::null" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::null \- Null channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::null ?1?\fR +.sp +\fB::tcl::chan::null\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::null\fR 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 \fBMemchan\fR, except that this is written in pure Tcl, +not C. On the other hand, \fBMemchan\fR is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +\fBTclOO\fR. +.PP +Packages related to this are \fBtcl::chan::zero\fR and +\fBtcl::chan::nullzero\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::null\fR +This command creates a new null channel and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +/dev/null, null, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/nullzero.n Index: embedded/man/files/modules/virtchannel_base/nullzero.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/nullzero.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/nullzero.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::nullzero" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::nullzero \- Null/Zero channel combination +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::nullzero ?1?\fR +.sp +\fB::tcl::chan::nullzero\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::nullzero\fR 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. +.PP +Packages related to this are \fBtcl::chan::null\fR and +\fBtcl::chan::zero\fR. +.PP +The internal \fBTclOO\fR class implementing the channel handler +is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::nullzero\fR +This command creates a new nullzero channel and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +/dev/null, /dev/zero, null, reflected channel, tip 219, virtual channel, zero +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/random.n Index: embedded/man/files/modules/virtchannel_base/random.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/random.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/random.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::random" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::random \- Random channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::random ?1?\fR +.sp +\fB::tcl::chan::random\fR \fIseed\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::random\fR 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 \fBMemchan\fR, except +that this is written in pure Tcl, not C, and uses a much simpler +generator as well. On the other hand, \fBMemchan\fR is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::random\fR \fIseed\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +/dev/random, random, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/randseed.n Index: embedded/man/files/modules/virtchannel_base/randseed.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/randseed.n @@ -0,0 +1,287 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/randseed.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::randseed" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::randseed \- Utilities for random channels +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::randseed ?1?\fR +.sp +\fB::tcl::randomseed\fR +.sp +\fB::tcl::combine\fR \fIseed1\fR \fIseed2\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::randseed\fR package provides a a few utility commands to help with the seeding of \fBtcl::chan::random\fR channels. +.SH API +.TP +\fB::tcl::randomseed\fR +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. +.TP +\fB::tcl::combine\fR \fIseed1\fR \fIseed2\fR +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +/dev/random, merge, random, reflected channel, seed, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/std.n Index: embedded/man/files/modules/virtchannel_base/std.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/std.n @@ -0,0 +1,289 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/std.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::std" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::std \- Standard I/O, unification of stdin and stdout +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::core ?1?\fR +.sp +package require \fBtcl::chan::std ?1?\fR +.sp +\fB::tcl::chan::std\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::std\fR 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. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::core\fR framework. +.SH API +.TP +\fB::tcl::chan::std\fR +This command creates the std channel and returns its handle. +.sp +The channel is created only once, on the first call, and all +future calls simply return this handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +reflected channel, standard io, stdin, stdout, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2011 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/string.n Index: embedded/man/files/modules/virtchannel_base/string.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/string.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/string.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::string" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::string \- Read-only in-memory channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::string ?1?\fR +.sp +\fB::tcl::chan::string\fR \fIcontent\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::string\fR 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 \fBtcl::chan::memchan\fR +they are read-only however, their content is provided at the time of +construction and immutable afterward. +.PP +Packages related to this are \fBtcl::chan::memchan\fR and +\fBtcl::chan::variable\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::string\fR \fIcontent\fR +This command creates a new string channel and returns its handle. The +channel provides random read-only access to the \fIcontent\fR string. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +in-memory channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/textwindow.n Index: embedded/man/files/modules/virtchannel_base/textwindow.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/textwindow.n @@ -0,0 +1,286 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/textwindow.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::textwindow" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::textwindow \- Textwindow channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::textwindow ?1?\fR +.sp +\fB::tcl::chan::textwindow\fR \fIwidget\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::textwindow\fR package provides a command creating +write-only channels connected to text widgets. Anything written to the +channel is printed into the associated widget. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::textwindow\fR \fIwidget\fR +This command creates a new textwindow channel and returns its handle. +Data written to this channel will appear in the associated \fIwidget\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +Tk, reflected channel, text widget, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/variable.n Index: embedded/man/files/modules/virtchannel_base/variable.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/variable.n @@ -0,0 +1,293 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/variable.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::variable" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::variable \- In-memory channel using variable for storage +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::variable ?1?\fR +.sp +\fB::tcl::chan::variable\fR \fIvarname\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::variable\fR 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 \fBtcl::chan::memchan\fR +the data is not hidden in the channel however, but stored in an +associated variable, specified at the time of construction. +.PP +Packages related to this are \fBtcl::chan::memchan\fR and +\fBtcl::chan::string\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::variable\fR \fIvarname\fR +This command creates a new variable channel and returns its handle. +The content of the channel is stored in the associated namespace +variable \fIvarname\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +in-memory channel, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_base/zero.n Index: embedded/man/files/modules/virtchannel_base/zero.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_base/zero.n @@ -0,0 +1,292 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_base/zero.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::zero" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::zero \- Zero channel +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +package require \fBtcl::chan::zero ?1?\fR +.sp +\fB::tcl::chan::zero\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::zero\fR 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 \fBMemchan\fR, except that this is written +in pure Tcl, not C. On the other hand, \fBMemchan\fR is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO. +.PP +Packages related to this are \fBtcl::chan::null\fR and +\fBtcl::chan::nullzero\fR. +.PP +The internal \fBTclOO\fR class implementing the channel +handler is a sub-class of the \fBtcl::chan::events\fR framework. +.SH API +.TP +\fB::tcl::chan::zero\fR +This command creates a new zero channel and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +/dev/zero, reflected channel, tip 219, virtual channel, zero +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_core/core.n Index: embedded/man/files/modules/virtchannel_core/core.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_core/core.n @@ -0,0 +1,318 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_core/core.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::core" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::core \- Basic reflected/virtual channel support +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::core ?1?\fR +.sp +\fB::tcl::chan::core\fR \fIobjectName\fR +.sp +\fIobjectName\fR \fBinitialize\fR \fIthechannel\fR \fImode\fR +.sp +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::core\fR package provides a \fBTclOO\fR +class implementing common behaviour needed by virtually every +reflected or virtual channel (initialization, finalization). +.PP +This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class. +.SH "CLASS API" +.TP +\fB::tcl::chan::core\fR \fIobjectName\fR +This command creates a new channel core object with an associated +global Tcl command whose name is \fIobjectName\fR. This command may +be used to invoke various operations on the object, as described in +the section for the \fBInstance API\fR. +.PP +.SH "INSTANCE API" +The API of channel core instances provides only two methods, both +corresponding to channel handler commands (For reference see +\fITIP 219\fR [http:/tip.tcl.tk/219]). They expect to be called +from whichever object instance the channel core was made a part of. +.TP +\fIobjectName\fR \fBinitialize\fR \fIthechannel\fR \fImode\fR +This method implements standard behaviour for the \fBinitialize\fR +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. +.sp +It further remembers the channel handle in an instance variable +for access by sub-classes. +.TP +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +This method implements standard behaviour for the \fBfinalize\fR +method of channel handlers. It simply destroys itself. +.TP +\fIobjectName\fR \fBdestroy\fR +Destroying the channel core instance closes the channel it was +initialized for, see the method \fBinitialize\fR. When destroyed +from within a call of \fBfinalize\fR this does not happen, under +the assumption that the channel is being destroyed by Tcl. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_core/events.n Index: embedded/man/files/modules/virtchannel_core/events.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_core/events.n @@ -0,0 +1,327 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_core/events.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::chan::events" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::chan::events \- Event support for reflected/virtual channels +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::chan::core ?1?\fR +.sp +package require \fBtcl::chan::events ?1?\fR +.sp +\fB::tcl::chan::events\fR \fIobjectName\fR +.sp +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +.sp +\fIobjectName\fR \fBwatch\fR \fIthechannel\fR \fIeventmask\fR +.sp +\fIobjectName\fR \fBallow\fR \fIeventname\fR... +.sp +\fIobjectName\fR \fBdisallow\fR \fIeventname\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::chan::events\fR package provides a \fBTclOO\fR +class implementing common behaviour needed by virtually every +reflected or virtual channel supporting event driven IO. It is a +sub-class of \fBtcl::chan::core\fR, inheriting all of its behaviour. +.PP +This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class. +.SH "CLASS API" +.TP +\fB::tcl::chan::events\fR \fIobjectName\fR +This command creates a new channel event core object with an associated +global Tcl command whose name is \fIobjectName\fR. This command may +be used to invoke various operations on the object, as described in +the section for the \fBInstance API\fR. +.PP +.SH "INSTANCE API" +The API of channel event core instances provides only four methods, two +corresponding to channel handler commands (For reference see +\fITIP 219\fR [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. +.TP +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +This method implements standard behaviour for the \fBfinalize\fR +method of channel handlers. It overrides the behaviour inherited from +\fBtcl::chan::core\fR and additionally disables any and all event +generation before destroying itself. +.TP +\fIobjectName\fR \fBwatch\fR \fIthechannel\fR \fIeventmask\fR +This method implements standard behaviour for the \fBwatch\fR +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. +.TP +\fIobjectName\fR \fBallow\fR \fIeventname\fR... +.TP +\fIobjectName\fR \fBdisallow\fR \fIeventname\fR... +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 \fBwatch\fR method the event core is +able to determine which events it should (not) generate and act +accordingly. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +event management, reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_core/transformcore.n Index: embedded/man/files/modules/virtchannel_core/transformcore.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_core/transformcore.n @@ -0,0 +1,318 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_core/transformcore.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::core" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::core \- Basic reflected/virtual channel transform support +.SH SYNOPSIS +package require \fBTcl 8.5\fR +.sp +package require \fBTclOO \fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +\fB::tcl::transform::core\fR \fIobjectName\fR +.sp +\fIobjectName\fR \fBinitialize\fR \fIthechannel\fR \fImode\fR +.sp +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +.sp +\fIobjectName\fR \fBdestroy\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::core\fR package provides a \fBTclOO\fR +class implementing common behaviour needed by virtually every +reflected or virtual channel transformation (initialization, finalization). +.PP +This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class. +.SH "CLASS API" +.TP +\fB::tcl::transform::core\fR \fIobjectName\fR +This command creates a new transform core object with an associated +global Tcl command whose name is \fIobjectName\fR. This command may +be used to invoke various operations on the object, as described in +the section for the \fBInstance API\fR. +.PP +.SH "INSTANCE API" +The API of transform core instances provides only two methods, both +corresponding to transform handler commands (For reference see +\fITIP 230\fR [http:/tip.tcl.tk/230]). They expect to be called +from whichever object instance the transform core was made a part of. +.TP +\fIobjectName\fR \fBinitialize\fR \fIthechannel\fR \fImode\fR +This method implements standard behaviour for the \fBinitialize\fR +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. +.sp +It further remembers the channel handle in an instance variable +for access by sub-classes. +.TP +\fIobjectName\fR \fBfinalize\fR \fIthechannel\fR +This method implements standard behaviour for the \fBfinalize\fR +method of channel handlers. It simply destroys itself. +.TP +\fIobjectName\fR \fBdestroy\fR +Destroying the transform core instance closes the channel and transform +it was initialized for, see the method \fBinitialize\fR. When destroyed +from within a call of \fBfinalize\fR this does not happen, under +the assumption that the channel and transform are being destroyed by Tcl. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +reflected channel, tip 219, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/adler32.n Index: embedded/man/files/modules/virtchannel_transform/adler32.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/adler32.n @@ -0,0 +1,312 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/adler32.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::adler32" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::adler32 \- Adler32 transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::adler32 ?1?\fR +.sp +\fB::tcl::transform::adler32\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::adler32\fR package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like \fBtcl::transform::identity\fR), 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. +.PP +Related transformations in this module are +\fBtcl::transform::counter\fR, +\fBtcl::transform::crc32\fR, +\fBtcl::transform::identity\fR, and +\fBtcl::transform::observe\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::adler32\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +This command creates an adler32 checksumming transformation on top of +the channel \fIchan\fR and returns its handle. The accepted options are +.RS +.TP +\fB-read-variable\fR 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. +.sp +If not specified, or the empty string, the checksum of the read +direction is not saved. +.TP +\fB-write-variable\fR 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. +.sp +If not specified, or the empty string, the checksum of the +write direction is not saved. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +adler32, channel transformation, checksum, reflected channel, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/base64.n Index: embedded/man/files/modules/virtchannel_transform/base64.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/base64.n @@ -0,0 +1,288 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/base64.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::base64" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::base64 \- Base64 encoding transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::base64 ?1?\fR +.sp +\fB::tcl::transform::base64\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::base64\fR package provides a command +creating a channel transformation which base64 encodes data written to +it, and decodes the data read from it. +.PP +A related transformations in this module is +\fBtcl::transform::hex\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::base64\fR \fIchan\fR +This command creates a base64 transformation on top of the channel +\fIchan\fR and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +base64, channel transformation, reflected channel, tip 230, tip 317, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/counter.n Index: embedded/man/files/modules/virtchannel_transform/counter.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/counter.n @@ -0,0 +1,311 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/counter.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::counter" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::counter \- Counter transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::counter ?1?\fR +.sp +\fB::tcl::transform::counter\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::counterr\fR package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like \fBtcl::transform::identity\fR), but +additionally counts the bytes it has seen for each direction and +stores these counts in Tcl variables specified at construction time. +.PP +Related transformations in this module are +\fBtcl::transform::adler32\fR, +\fBtcl::transform::crc32\fR, +\fBtcl::transform::identity\fR, and +\fBtcl::transform::observe\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::counter\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +This command creates a counter transformation on top of the channel +\fIchan\fR and returns its handle. The accepted options are +.RS +.TP +\fB-read-variable\fR 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. +.sp +If not specified, or the empty string, the counter of the read +direction is not saved. +.TP +\fB-write-variable\fR 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. +.sp +If not specified, or the empty string, the counter of the +write direction is not saved. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, counter, reflected channel, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/crc32.n Index: embedded/man/files/modules/virtchannel_transform/crc32.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/crc32.n @@ -0,0 +1,312 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/crc32.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::crc32" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::crc32 \- Crc32 transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::crc32 ?1?\fR +.sp +\fB::tcl::transform::crc32\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::crc32\fR package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like \fBtcl::transform::identity\fR), 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. +.PP +Related transformations in this module are +\fBtcl::transform::adler32\fR, +\fBtcl::transform::counter\fR, +\fBtcl::transform::identity\fR, and +\fBtcl::transform::observe\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::crc32\fR \fIchan\fR \fB-option\fR \fIvalue\fR... +This command creates a crc32 checksumming transformation on top of +the channel \fIchan\fR and returns its handle. The accepted options are +.RS +.TP +\fB-read-variable\fR 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. +.sp +If not specified, or the empty string, the checksum of the read +direction is not saved. +.TP +\fB-write-variable\fR 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. +.sp +If not specified, or the empty string, the checksum of the +write direction is not saved. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, checksum, crc32, reflected channel, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/hex.n Index: embedded/man/files/modules/virtchannel_transform/hex.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/hex.n @@ -0,0 +1,288 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/hex.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::hex" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::hex \- Hexadecimal encoding transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::hex ?1?\fR +.sp +\fB::tcl::transform::hex\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::hex\fR package provides a command creating +a channel transformation which hex encodes data written to it, and +decodes the data read from it. +.PP +A related transformations in this module is +\fBtcl::transform::base64\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::hex\fR \fIchan\fR +This command creates a hex transformation on top of the channel +\fIchan\fR and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, hexadecimal, reflected channel, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/identity.n Index: embedded/man/files/modules/virtchannel_transform/identity.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/identity.n @@ -0,0 +1,295 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/identity.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::identity" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::identity \- Identity transformation +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::identity ?1?\fR +.sp +\fB::tcl::transform::identity\fR \fIchan\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::identity\fR 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. +.PP +The transformations in this module which derived from +identity's code are +\fBtcl::transform::adler32\fR, +\fBtcl::transform::counter\fR, +\fBtcl::transform::crc32\fR, and +\fBtcl::transform::observe\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::identity\fR \fIchan\fR +This command creates an identity transformation on top of the channel +\fIchan\fR and returns its handle. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, identity, reflected channel, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/limitsize.n Index: embedded/man/files/modules/virtchannel_transform/limitsize.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/limitsize.n @@ -0,0 +1,290 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/limitsize.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::limitsize" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::limitsize \- limiting input +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::limitsize ?1?\fR +.sp +\fB::tcl::transform::limitsize\fR \fIchan\fR \fImax\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::limitsize\fR 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. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::limitsize\fR \fIchan\fR \fImax\fR +This command creates a size limiting transformation on top of the +channel \fIchan\fR and returns its handle. +.sp +\fImax\fR 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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, limitsize, reflected channel, size limit, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/observe.n Index: embedded/man/files/modules/virtchannel_transform/observe.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/observe.n @@ -0,0 +1,294 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/observe.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::observe" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::observe \- Observer transformation, stream copy +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::observe ?1?\fR +.sp +\fB::tcl::transform::observe\fR \fIchan\fR \fIlogw\fR \fIlogr\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::observer\fR package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like \fBtcl::transform::identity\fR), but +additionally copies the data it has seen for each direction into +channels specified at construction time. +.PP +Related transformations in this module are +\fBtcl::transform::adler32\fR, +\fBtcl::transform::counter\fR, +\fBtcl::transform::crc32\fR, and +\fBtcl::transform::identity\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::observe\fR \fIchan\fR \fIlogw\fR \fIlogr\fR +This command creates an observer transformation on top of the channel +\fIchan\fR and returns its handle. The channel handles \fIlogr\fR and +\fIlogw\fR are there the data is copied to. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, observer, reflected channel, stream copy, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/otp.n Index: embedded/man/files/modules/virtchannel_transform/otp.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/otp.n @@ -0,0 +1,293 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/otp.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::otp" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::otp \- Encryption via one-time pad +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::otp ?1?\fR +.sp +\fB::tcl::transform::otp\fR \fIchan\fR \fIkeychanw\fR \fIkeychanr\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::otp\fR package provides a command creating +a channel transformation which uses externally provided one-time pads +to perform encryption (on writing) and decryption (on reading). +.PP +A related transformations in this module is +\fBtcl::transform::rot\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::otp\fR \fIchan\fR \fIkeychanw\fR \fIkeychanr\fR +This command creates a one-time pad based encryption transformation on +top of the channel \fIchan\fR and returns its handle. +.sp +The two channels \fIkeychanw\fR and \fIkeychanr\fR 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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, cipher, decryption, encryption, one time pad, otp, reflected channel, tip 230, transformation, virtual channel, xor +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/rot.n Index: embedded/man/files/modules/virtchannel_transform/rot.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/rot.n @@ -0,0 +1,297 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/rot.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::rot" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::rot \- rot-encryption +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::rot ?1?\fR +.sp +\fB::tcl::transform::rot\fR \fIchan\fR \fIkey\fR +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::rot\fR 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. +.PP +A related transformations in this module is +\fBtcl::transform::otp\fR. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::rot\fR \fIchan\fR \fIkey\fR +This command creates a rot encryption transformation on top of the +channel \fIchan\fR and returns its handle. +.sp +The "\fIkey\fR" specifies how far characters are rotated in the +alphabet, and is wrapped to the range "0...25". +.sp +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. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +caesar cipher, channel transformation, cipher, decryption, encryption, reflected channel, rot, rot13, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/spacer.n Index: embedded/man/files/modules/virtchannel_transform/spacer.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/spacer.n @@ -0,0 +1,290 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/spacer.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::spacer" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::spacer \- Space insertation and removal +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::spacer ?1?\fR +.sp +\fB::tcl::transform::spacer\fR \fIchan\fR \fIn\fR ?\fIspace\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::spacer\fR 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. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::spacer\fR \fIchan\fR \fIn\fR ?\fIspace\fR? +This command creates a spacer transformation on top of the channel +\fIchan\fR and returns its handle. +.sp +The \fIspace\fR character sequence will be added every \fIn\fR +bytes of data written, and on the read side the same is done in +reverse, removing the spacing. If \fIspace\fR is not specified it +defaults to a single space character (ASCII 32). +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, reflected channel, spacing, tip 230, transformation, virtual channel +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/virtchannel_transform/zlib.n Index: embedded/man/files/modules/virtchannel_transform/zlib.n ================================================================== --- /dev/null +++ embedded/man/files/modules/virtchannel_transform/zlib.n @@ -0,0 +1,288 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/virtchannel_transform/zlib.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "tcl::transform::zlib" n 1 tcllib "Reflected/virtual channel support" +.BS +.SH NAME +tcl::transform::zlib \- zlib (de)compression +.SH SYNOPSIS +package require \fBTcl 8.6\fR +.sp +package require \fBtcl::transform::core ?1?\fR +.sp +package require \fBtcl::transform::zlib ?1?\fR +.sp +\fB::tcl::transform::zlib\fR \fIchan\fR ?\fIlevel\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fBtcl::transform::zlib\fR package provides a command creating +a channel transformation which zlib compresses the written data, and +decompresses on reading. +.PP +The internal \fBTclOO\fR class implementing the transform +handler is a sub-class of the \fBtcl::transform::core\fR +framework. +.SH API +.TP +\fB::tcl::transform::zlib\fR \fIchan\fR ?\fIlevel\fR? +This command creates a zlib compressor transformation on top of the +channel \fIchan\fR and returns its handle. +.sp +The \fIlevel\fR specifies how much effort is put into the +compression, from \fB0\fR to \fB9\fR, and defaults to \fB4\fR. +.PP +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIvirtchannel\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +channel transformation, compression, decompression, reflected channel, tip 230, tip 234, transformation, virtual channel, zlib +.SH CATEGORY +Channels +.SH COPYRIGHT +.nf +Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/wip/wip.n Index: embedded/man/files/modules/wip/wip.n ================================================================== --- /dev/null +++ embedded/man/files/modules/wip/wip.n @@ -0,0 +1,608 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/wip/wip.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "wip" n 2.2 tcllib "Word Interpreter" +.BS +.SH NAME +wip \- Word Interpreter +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBwip ?2.2?\fR +.sp +package require \fBsnit ?1.3?\fR +.sp +package require \fBstruct::set \fR +.sp +\fB::wip\fR \fIwipName\fR \fIengine\fR \fIarg\fR... +.sp +\fBdef\fR \fIname\fR +.sp +\fBdef\fR \fIname\fR \fImethod_prefix\fR +.sp +\fBwipName\fR \fIoption\fR ?\fIarg arg ...\fR? +.sp +\fBwip::dsl\fR ?\fIsuffix\fR? +.sp +\fIwipName\fR \fBdef\fR \fIname\fR ?\fImethod_prefix\fR? +.sp +\fIwipName\fR \fBdefl\fR \fInames\fR +.sp +\fIwipName\fR \fBdefd\fR \fIdict\fR +.sp +\fIwipName\fR \fBdeflva\fR \fIname\fR... +.sp +\fIwipName\fR \fBdefdva\fR (\fIname\fR \fImethod_prefix\fR)... +.sp +\fIwipName\fR \fBundefl\fR \fInames\fR +.sp +\fIwipName\fR \fBundefva\fR \fIname\fR... +.sp +\fIwipName\fR \fBunknown\fR \fIcmdprefix\fR +.sp +\fIwipName\fR \fBrunl\fR \fIwordlist\fR +.sp +\fIwipName\fR \fBrun\fR \fIword\fR... +.sp +\fIwipName\fR \fBrun_next\fR +.sp +\fIwipName\fR \fBrun_next_while\fR \fIacceptable\fR +.sp +\fIwipName\fR \fBrun_next_until\fR \fIrejected\fR +.sp +\fIwipName\fR \fBrun_next_if\fR \fIacceptable\fR +.sp +\fIwipName\fR \fBrun_next_ifnot\fR \fIrejected\fR +.sp +\fIwipName\fR \fBnext\fR +.sp +\fIwipName\fR \fBpeek\fR +.sp +\fIwipName\fR \fBpeekall\fR +.sp +\fIwipName\fR \fBinsertl\fR \fIat\fR \fIwordlist\fR +.sp +\fIwipName\fR \fBreplacel\fR \fIwordlist\fR +.sp +\fIwipName\fR \fBpushl\fR \fIwordlist\fR +.sp +\fIwipName\fR \fBaddl\fR \fIwordlist\fR +.sp +\fIwipName\fR \fBinsert\fR \fIat\fR \fIword\fR... +.sp +\fIwipName\fR \fBreplace\fR \fIword\fR... +.sp +\fIwipName\fR \fBpush\fR \fIword\fR... +.sp +\fIwipName\fR \fBadd\fR \fIword\fR... +.sp +.BE +.SH DESCRIPTION +.PP +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. +.PP +The idea is derived from Colin McCormack's \fBtreeql\fR 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. +.SH "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). +.PP +At the time a language command is defined the word interpreter will +use \fBsnit\fR'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 \fIarity\fR. Variable-argument +methods (i.e. with the last argument named \fIargs\fR) are \fInot\fR +allowed and will cause the word interpreter to throw an error at +definition time. +.PP +Note that while I said \fBsnit\fR's abilities the engine object +can be written in any way, as long as it understands the method +\fBinfo args\fR, which takes a method name and returns the list +of arguments for that method. +.PP +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 \fIarity\fR 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. +.PP +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. +.IP [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. +.IP [2] +Another possibility is the use of method \fBrun_next\fR and its +variants to execute commands coming after the current command, +changing the order of execution. +.IP [3] +Execution can be further changed by use of the program accessor +methods which allow a command implementation to modify the remaining +list of words (insert, replace, prepend, append words) without +executing them immediately. +.IP [4] +At last the basic \fBrun\fR methods save and restore an existing +list of words when used, enabling recursive use from within command +implementations. +.PP +.SH "CLASS API" +The main command of the package is: +.TP +\fB::wip\fR \fIwipName\fR \fIengine\fR \fIarg\fR... +The command creates a new word interpreter object with an associated +global Tcl command whose name is \fIwipName\fR. If however the string +\fB%AUTO%\fR was used as object name the package will generate its +own unique name for the object. +.sp +The \fIengine\fR is the object the word interpreter will dispatch all +recognized commands to, and the \fIarg\fRuments are a word list which +defines an initial mapping from language words to engine methods. +.sp +The recognized language of this word list is +.RS +.TP +\fBdef\fR \fIname\fR +Defines \fIname\fR as command of the language, to be mapped to a +method of the \fIengine\fR having the same name. +.TP +\fBdef\fR \fIname\fR \fImethod_prefix\fR +Defines \fIname\fR as command of the language, to be mapped to the +method of the \fIengine\fR named in the \fImethod_prefix\fR. +.RE +.sp +The returned command may be used to invoke various operations on the +object. It has the following general form: +.RS +.TP +\fBwipName\fR \fIoption\fR ?\fIarg arg ...\fR? +\fIOption\fR and the \fIarg\fRs determine the exact behavior of the +command. +.RE +.PP +The package additionally exports the command: +.TP +\fBwip::dsl\fR ?\fIsuffix\fR? +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. +.sp +It installs a component named \fIwip\fR, and a method +\fBwip_setup\fR 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. +.sp +\fINote\fR that this does and cannot install the language to +interpret, i.e. the mapping from words to engine methods. +.sp +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_\fB$suffix\fR', the setup command becomes +\'wip_\fB$suffix\fR_setup' and all the procedures also get the suffix +\'_\fB$suffix\fR'. +.PP +.SH "OBJECT API" +The following commands are possible for word interpreter objects: +.TP +\fIwipName\fR \fBdef\fR \fIname\fR ?\fImethod_prefix\fR? +Defines a language command \fIname\fR and maps it to the method named +in the engine's \fImethod_prefix\fR. If the \fImethod_prefix\fR name +is not specified it is simply the name of the language command. +.TP +\fIwipName\fR \fBdefl\fR \fInames\fR +Defines a series of language commands, specified through the list of +\fInames\fR, all of which are mapped to engine methods of the same +name. +.TP +\fIwipName\fR \fBdefd\fR \fIdict\fR +Defines a series of language commands, specified through the +dictionary \fIdict\fR of names and method prefixes. +.TP +\fIwipName\fR \fBdeflva\fR \fIname\fR... +As method \fBdefl\fR, however the list of names is specified +through multiple arguments. +.TP +\fIwipName\fR \fBdefdva\fR (\fIname\fR \fImethod_prefix\fR)... +As method \fBdefd\fR, however the dictionary of names and method +prefixes is specified through multiple arguments. +.TP +\fIwipName\fR \fBundefl\fR \fInames\fR +Removes the named series of language commands from the mapping. +.TP +\fIwipName\fR \fBundefva\fR \fIname\fR... +As method \fBundefl\fR, however the list of names is specified +through multiple arguments. +.TP +\fIwipName\fR \fBunknown\fR \fIcmdprefix\fR +Sets the handler for unknown words to \fIcmdprefix\fR. 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. +.TP +\fIwipName\fR \fBrunl\fR \fIwordlist\fR +Treats the list of words in \fIwordlist\fR 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. +.sp +The \fIwordlist\fR is stored in the object for access by the other +\fIrun\fR-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. +.TP +\fIwipName\fR \fBrun\fR \fIword\fR... +As method \fBrunl\fR, however the list of words to execute is +specified through multiple arguments. +.TP +\fIwipName\fR \fBrun_next\fR +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. +.sp +Exposed for use within command implementations. +The methods \fBrun\fR and \fBrunl\fR use it to execute words +until their word list is exhausted. +.TP +\fIwipName\fR \fBrun_next_while\fR \fIacceptable\fR +Low-level method. Invokes the method \fBrun_next\fR as long as the +next word is in the set of \fIacceptable\fR words, and the program is +not empty. The result of the command executed last is returned as the +result of this command. +.sp +Exposed for use within command implementations to change the order of +execution. +.TP +\fIwipName\fR \fBrun_next_until\fR \fIrejected\fR +Low-level method. Invokes the method \fBrun_next\fR until the next +word is in the set of \fIrejected\fR words, and the program is not +empty. The result of the command executed last is returned as the +result of this command. +.sp +Exposed for use within command implementations to change the order of +execution. +.TP +\fIwipName\fR \fBrun_next_if\fR \fIacceptable\fR +Low-level method. Invokes the method \fBrun_next\fR if the next +word is in the set of \fIacceptable\fR words, and the program is not +empty. The result of the command executed last is returned as the +result of this command. +.sp +Exposed for use within command implementations to change the order of +execution. +.TP +\fIwipName\fR \fBrun_next_ifnot\fR \fIrejected\fR +Low-level method. Invokes the method \fBrun_next\fR if the next +word is not in the set of \fIrejected\fR words, and the program is not +empty. The result of the command executed last is returned as the +result of this command. +.sp +Exposed for use within command implementations to change the order of +execution. +.TP +\fIwipName\fR \fBnext\fR +Returns the next word in the programm. The word is also removed. +.TP +\fIwipName\fR \fBpeek\fR +Returns the next word in the programm without removing it +.TP +\fIwipName\fR \fBpeekall\fR +Returns the remaining programm in toto. +.TP +\fIwipName\fR \fBinsertl\fR \fIat\fR \fIwordlist\fR +Basic programm accessor method. Inserts the specified \fIwordlist\fR +into the program, just before the word at position \fIat\fR. Positions +are counted from \fBzero\fR. +.TP +\fIwipName\fR \fBreplacel\fR \fIwordlist\fR +Basic programm accessor method. Replaces the whole stored program with +the specified \fIwordlist\fR. +.TP +\fIwipName\fR \fBpushl\fR \fIwordlist\fR +Program accessor method. The specified \fIwordlist\fR is added to the +front of the remaining program. Equivalent to +.sp +.CS + +$wip insertl 0 $wordlist +.CE +.TP +\fIwipName\fR \fBaddl\fR \fIwordlist\fR +Program accessor method. The specified \fIwordlist\fR is appended at +the end of the remaining program. Equivalent to +.sp +.CS + +$wip insertl end $wordlist +.CE +.TP +\fIwipName\fR \fBinsert\fR \fIat\fR \fIword\fR... +Like method \fBinsertl\fR, except the words are specified through +multiple arguments. +.TP +\fIwipName\fR \fBreplace\fR \fIword\fR... +Like method \fBsetl\fR, except the words are specified through +multiple arguments. +.TP +\fIwipName\fR \fBpush\fR \fIword\fR... +Like method \fBpushl\fR, except the words are specified through +multiple arguments. +.TP +\fIwipName\fR \fBadd\fR \fIword\fR... +Like method \fBaddl\fR, except the words are specified through +multiple arguments. +.PP +.SH EXAMPLES +No examples yet. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIwip\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH KEYWORDS +interpreter, list, word +.SH CATEGORY +Programming tools +.SH COPYRIGHT +.nf +Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/yaml/huddle.n Index: embedded/man/files/modules/yaml/huddle.n ================================================================== --- /dev/null +++ embedded/man/files/modules/yaml/huddle.n @@ -0,0 +1,828 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/yaml/huddle.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "huddle" n 0.1.5 tcllib "HUDDLE" +.BS +.SH NAME +huddle \- Create and manipulate huddle object +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fBhuddle ?0.1.5?\fR +.sp +\fBhuddle create\fR \fIkey\fR \fIvalue\fR ?\fIkey value ...\fR? +.sp +\fBhuddle list\fR ?\fIvalue value ...\fR? +.sp +\fBhuddle get\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +.sp +\fBhuddle gets\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +.sp +\fBhuddle set\fR \fIobjectVar\fR \fIkey\fR ?\fIkey ...\fR? \fIvalue\fR +.sp +\fBhuddle remove\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +.sp +\fBhuddle combine\fR \fIobject1\fR \fIobject2\fR ?\fIobject3 ...\fR? +.sp +\fBhuddle equal\fR \fIobject1\fR \fIobject2\fR +.sp +\fBhuddle append\fR \fIobjectVar\fR \fIkey\fR \fIvalue\fR ?\fIkey value ...\fR? +.sp +\fBhuddle append\fR \fIobjectVar\fR \fIvalue\fR ?\fIvalue ...\fR? +.sp +\fBhuddle keys\fR \fIobject\fR +.sp +\fBhuddle llength\fR \fIobject\fR +.sp +\fBhuddle type\fR \fIobject\fR ?\fIkey key...\fR? +.sp +\fBhuddle strip\fR \fIobject\fR +.sp +\fBhuddle jsondump\fR \fIobject\fR ?\fIoffset\fR? ?\fInewline\fR? ?\fIbegin_offset\fR? +.sp +\fBhuddle compile\fR \fIspec\fR \fIdata\fR +.sp +\fBhuddle isHuddle\fR \fIobject\fR +.sp +\fBhuddle checkHuddle\fR \fIobject\fR +.sp +\fBhuddle to_node\fR \fIobject\fR ?\fItag\fR? +.sp +\fBhuddle wrap\fR \fItag\fR \fIsrc\fR +.sp +\fBhuddle call\fR \fItag\fR \fIcommand\fR \fIargs\fR +.sp +\fBhuddle addType\fR \fIcallback\fR +.sp +\fBcallback\fR \fIcommand\fR ?\fIargs\fR? +.sp +\fBsetting\fR +.sp +\fBget_sub\fR \fIsrc\fR \fIkey\fR +.sp +\fBstrip\fR \fIsrc\fR +.sp +\fBset\fR \fIsrc\fR \fIkey\fR \fIvalue\fR +.sp +\fBremove\fR \fIsrc\fR \fIkey\fR \fIvalue\fR +.sp +.BE +.SH DESCRIPTION +.PP +Huddle provides a generic Tcl-based serialization/intermediary format. +Currently, each node is wrapped in a tag with simple type information. +.PP +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. +.PP +In that manner huddle can serve as a common intermediary format. +.CS + + +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. + +.CE +.PP +The \fBhuddle\fR package returns +data as a Tcl \fBdict\fR. Either the \fBdict\fR package or Tcl 8.5 is +required for use. +.SH COMMANDS +.TP +\fBhuddle create\fR \fIkey\fR \fIvalue\fR ?\fIkey value ...\fR? +Create a huddle object as a dict. It can contain other huddle objects. +.TP +\fBhuddle list\fR ?\fIvalue value ...\fR? +Create a huddle object as a list. It can contain other huddle objects. +.TP +\fBhuddle get\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +Almost the same as \fBdict get\fR. +Get a sub-object from the huddle object. +\fIkey\fR can be used to huddle-list's index. +.TP +\fBhuddle gets\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +Get a sub-object from the huddle object, stripped. +.TP +\fBhuddle set\fR \fIobjectVar\fR \fIkey\fR ?\fIkey ...\fR? \fIvalue\fR +Almost the same as \fBdict set\fR. +Set a sub-object from the huddle object. +\fIkey\fR can be used to huddle-list's index. +.TP +\fBhuddle remove\fR \fIobject\fR \fIkey\fR ?\fIkey ...\fR? +Almost the same as \fBdict remove\fR. +Remove a sub-object from the huddle object. +\fIkey\fR can be used to huddle-list's index. +.TP +\fBhuddle combine\fR \fIobject1\fR \fIobject2\fR ?\fIobject3 ...\fR? +Merging huddle objects given. +.CS + + +% 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}}} + +.CE +.TP +\fBhuddle equal\fR \fIobject1\fR \fIobject2\fR +Comparing two huddle objects recursively. +When to equal, returns 1, otherwise 0. +.CS + + +% 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 + +.CE +.TP +\fBhuddle append\fR \fIobjectVar\fR \fIkey\fR \fIvalue\fR ?\fIkey value ...\fR? +.TP +\fBhuddle append\fR \fIobjectVar\fR \fIvalue\fR ?\fIvalue ...\fR? +Appending child elements. When for dicts, giving key/value. When for lists, giving values. +.CS + + +% 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}}} + +.CE +.TP +\fBhuddle keys\fR \fIobject\fR +The same as \fBdict keys\fR. +.TP +\fBhuddle llength\fR \fIobject\fR +The same as \fBllength\fR. +.TP +\fBhuddle type\fR \fIobject\fR ?\fIkey key...\fR? +Return the element type of specified by keys. +if ?key? is not given, returns the type of root node. +.sp +.RS +.TP +\fB\fBstring\fR\fR +the node is a tcl's string. +.TP +\fB\fBdict\fR\fR +the node is a dict. +.TP +\fB\fBlist\fR\fR +the node is a list. +.RE +.CS + + +% 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 + +.CE +.TP +\fBhuddle strip\fR \fIobject\fR +Stripped all tags. Converted to normal Tcl's list/dict. +.TP +\fBhuddle jsondump\fR \fIobject\fR ?\fIoffset\fR? ?\fInewline\fR? ?\fIbegin_offset\fR? +dump a json-stream from the huddle-object. +.sp +.RS +.TP +\fB\fBoffset\fR ""\fR +begin offset as spaces " ". +.RE +.CS + +# 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"}} + +.CE +.TP +\fBhuddle compile\fR \fIspec\fR \fIdata\fR +construct a huddle object from plain old tcl values. +\fIspec\fR is defined as follows: +.RS +.TP +\fBstring\fR +data is simply a string +.TP +\fBlist\fR +data is a tcl list of strings +.TP +\fBdict\fR +data is a tcl dict of strings +.TP +list list +data is a tcl list of lists +.TP +list dict +data is a tcl list of dicts +.TP +dict xx list +data is a tcl dict where the value of key xx is a tcl list +.TP +dict * list +data is a tcl dict of lists +\fIdata\fR is plain old tcl values +.RE +.CS + +% 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}}}}}}} + +.CE +.TP +\fBhuddle isHuddle\fR \fIobject\fR +if \fIobject\fR is a huddle, returns 1. the other, returns 0. +.TP +\fBhuddle checkHuddle\fR \fIobject\fR +if \fIobject\fR is not a huddle, rises an error. +.TP +\fBhuddle to_node\fR \fIobject\fR ?\fItag\fR? +for type-callbacks. +.sp +if \fIobject\fR is a huddle, returns root-node. the other, returns \fB[list s $object]\fR. +.CS + + +% 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} + +.CE +.TP +\fBhuddle wrap\fR \fItag\fR \fIsrc\fR +for type-callbacks. +.sp +Create a huddle object from \fIsrc\fR with specified \fItag\fR. +.CS + + +% huddle wrap "" str +HUDDLE str +% huddle wrap s str +HUDDLE {s str} + +.CE +.TP +\fBhuddle call\fR \fItag\fR \fIcommand\fR \fIargs\fR +for type-callbacks. +.sp +devolving \fIcommand\fR to default \fItag\fR-callback +.TP +\fBhuddle addType\fR \fIcallback\fR +add a user-specified-type/tag to the huddle library. +To see "Additional Type". +.sp +.RS +.TP +\fBcallback\fR +callback function name for additional type. +.RE +.PP +.SH "TYPE CALLBACK" +.PP +The definition of callback for user-type. +.TP +\fBcallback\fR \fIcommand\fR ?\fIargs\fR? +.RS +.TP +\fBcommand\fR +huddle subcomand which is needed to reply by the callback. +.TP +\fBargs\fR +arguments of subcommand. The number of list of arguments is different for each subcommand. +.RE +.PP +.PP +The callback procedure shuould reply the following subcommands. +.TP +\fBsetting\fR +only returns a fixed dict of the type infomation for setting the user-tag. +.RS +.TP +\fBtype\fR typename +typename of the type +.TP +\fBmethod\fR {method1 method2 method3 ...} +method list as huddle subcommand. Then, you can call \fB[huddle method1 ...]\fR +.TP +\fBtag\fR {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". +.RE +.TP +\fBget_sub\fR \fIsrc\fR \fIkey\fR +returns a sub node specified by \fIkey\fR. +.RS +.TP +\fBsrc\fR +a node content in huddle object. +.RE +.TP +\fBstrip\fR \fIsrc\fR +returns stripped node contents. if the type has child nodes, every node must be stripped. +.TP +\fBset\fR \fIsrc\fR \fIkey\fR \fIvalue\fR +sets a sub-node from the tagged-content, and returns self. +.TP +\fBremove\fR \fIsrc\fR \fIkey\fR \fIvalue\fR +removes a sub-node from the tagged-content, and returns self. +.PP +.PP +\fBstrip\fR must be defined at all types. +\fBget_sub\fR must be defined at container types. +\fBset/remove\fR shuould be defined, if you call them. +.CS + + +# 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" + } + } +} + +.CE +.CS + + +# 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] + } + } +} + +.CE +.SH "HOW TO ADD TYPE" +.PP +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 \fIcommand\fR and ?\fIargs\fR?. It has some switch-sections. +.PP +And, addType subcommand will called. +.CS + + +huddle addType my_dict_setting + +.CE +.SH "WORKING SAMPLE" +.CS + + +# 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" +] + +.CE +.SH LIMITATIONS +.PP +now printing. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIhuddle\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +yaml +.SH KEYWORDS +data exchange, exchange format, huddle, json, parsing, text processing, yaml +.SH COPYRIGHT +.nf +Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net> + +.fi ADDED embedded/man/files/modules/yaml/yaml.n Index: embedded/man/files/modules/yaml/yaml.n ================================================================== --- /dev/null +++ embedded/man/files/modules/yaml/yaml.n @@ -0,0 +1,440 @@ +'\" +'\" Generated from file '/net/nas/data/andreask/Dev/Tcllib/tcllib/embedded/man/files/modules/yaml/yaml.n' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net> +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "yaml" n 0.3.6 tcllib "YAML processing" +.BS +.SH NAME +yaml \- YAML Format Encoder/Decoder +.SH SYNOPSIS +package require \fBTcl 8.4\fR +.sp +package require \fByaml ?0.3.6?\fR +.sp +\fB::yaml::yaml2dict\fR ?\fIoptions\fR? \fItxt\fR +.sp +\fB::yaml::yaml2huddle\fR ?\fIoptions\fR? \fItxt\fR +.sp +\fB::yaml::setOption\fR ?\fIoptions\fR? +.sp +\fB::yaml::dict2yaml\fR \fIdict\fR ?\fIindent\fR? ?\fIwordwrap\fR? +.sp +\fB::yaml::list2yaml\fR \fIlist\fR ?\fIindent\fR? ?\fIwordwrap\fR? +.sp +\fB::yaml::huddle2yaml\fR \fIhuddle\fR ?\fIindent\fR? ?\fIwordwrap\fR? +.sp +.BE +.SH DESCRIPTION +.PP +The \fByaml\fR package provides a simple Tcl-only library for parsing the +YAML \fIhttp://www.yaml.org/\fR data exchange format as specified in +\fIhttp://www.yaml.org/spec/1.1/\fR. +.PP +The \fByaml\fR package returns +data as a Tcl \fBdict\fR. Either the \fBdict\fR package or Tcl 8.5 is +required for use. +.SH COMMANDS +.TP +\fB::yaml::yaml2dict\fR ?\fIoptions\fR? \fItxt\fR +.TP +\fB::yaml::yaml2huddle\fR ?\fIoptions\fR? \fItxt\fR +Parse yaml formatted text \fItxt\fR into a Tcl dict/huddle and return the value. +.RS +.TP +\fB\fB-file\fR\fR +\fItxt\fR is a filename of YAML-stream. +.TP +\fB\fB-stream\fR\fR +\fItxt\fR is just a YAML-stream. +.TP +\fB\fB-types\fR \fIlist\fR\fR +The \fIlist\fR is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...) +.CS + + -types {timestamp integer null true false} +.CE +.IP +In this case, if a string matched "timestamp", converted to the TCL internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183) +.TP +\fB\fB-m:true\fR \fIparam\fR\fR +The \fIparam\fR is two elements of list for the value of true, and considered strings. +.CS + + -m:true {1 {true on + yes y}} +.CE +.IP +In this case, the string "yes" found in YAML Stream, automatically converted 1. +.TP +\fB\fB-m:false\fR \fIparam\fR\fR +The \fIparam\fR is two elements of list for the value of false, and considered strings. +.CS + + -m:false {0 {false off - no n}} +.CE +.TP +\fB\fB-m:null\fR \fIparam\fR\fR +The \fIparam\fR is two elements of list for the value of null, and considered strings. +.CS + + -m:null {"" {null nil "" ~}} +.CE +.TP +\fB\fB-validate\fR\fR +Experiment,old: Output stream contains YAML's-tag, each node. +.CS + +% puts [::yaml::load -validate {[aaa, bbb]}] +=> +!!seq {{!!str aaa} {!!str bbb}} + +.CE +.RE +.TP +\fB::yaml::setOption\fR ?\fIoptions\fR? +Change implicit options for the library. +Now, the params are the same as \fB::yaml::yaml2dict\fR. +Arguments of\fB::yaml::yaml2dict\fR is more priority than this setting. +.TP +\fB::yaml::dict2yaml\fR \fIdict\fR ?\fIindent\fR? ?\fIwordwrap\fR? +.TP +\fB::yaml::list2yaml\fR \fIlist\fR ?\fIindent\fR? ?\fIwordwrap\fR? +.TP +\fB::yaml::huddle2yaml\fR \fIhuddle\fR ?\fIindent\fR? ?\fIwordwrap\fR? +Convert a dict/list/huddle object into YAML stream. +.RS +.TP +indent +spaces indent of each block node. +currently default is 2. +.TP +wordwrap +word wrap for YAML stream. +currently default is 40. +.RE +.PP +.PP +.SH EXAMPLES +.PP +An example of a yaml stream converted to Tcl. A yaml stream is returned as a +single item with multiple elements. +.PP +.CS + +{ +--- !<tag:clarkevans.com,2002:invoice> +invoice: 34843 +date : 2001-01-23 +bill-to: &id001 + given : Chris + family : Dumars + address: + lines: | + 458 Walkman Dr. + Suite #292 + city : Royal Oak + state : MI + postal : 48046 +ship-to: *id001 +product: + - sku : BL394D + quantity : 4 + description : Basketball + price : 450.00 + - sku : BL4438H + quantity : 1 + description : Super Hoop + price : 2392.00 +tax : 251.42 +total: 4443.52 +comments: + Late afternoon is best. + Backup contact is Nancy + Billsmer @ 338-4338. +} +=> +invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr. +Suite #292 +} city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr. +Suite #292 +} city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.} +.CE +.PP +An example of a yaml object converted to Tcl. A yaml object is returned as a +multi-element list (a dict). +.PP +.CS + +{ +--- +- [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}} + +.CE +.SH LIMITATIONS +.PP +tag parser not implemented. currentry, tags are merely ignored. +.PP +Only Anchor => Aliases ordering. back alias-referring is not supported. +.PP +Too many braces, or too few braces. +.PP +Not enough character set of line feeds. Please use only "\\n" as line breaks. +.SH "BUGS, IDEAS, FEEDBACK" +This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category \fIyaml\fR of the +\fITcllib SF Trackers\fR [http://sourceforge.net/tracker/?group_id=12883]. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +.SH "SEE ALSO" +base64, huddle, json +.SH KEYWORDS +data exchange, huddle, parsing, text processing, yaml +.SH COPYRIGHT +.nf +Copyright (c) 2008 KATO Kanryu <kanryu6@users.sourceforge.net> + +.fi ADDED embedded/man/index.n Index: embedded/man/index.n ================================================================== --- /dev/null +++ embedded/man/index.n @@ -0,0 +1,10443 @@ +'\" +'\" Generated by tcllib/doctools/idx with format 'nroff' +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "Keyword Index" n +.BS +.SH INDEX +tcllib +.RS +.ddt +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +.dtx +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +/dev/null +.RS +.TP +\fBfiles/modules/virtchannel_base/null.n\fR +tcl::chan::null +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.RE +/dev/random +.RS +.TP +\fBfiles/modules/virtchannel_base/random.n\fR +tcl::chan::random +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.RE +/dev/zero +.RS +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.TP +\fBfiles/modules/virtchannel_base/zero.n\fR +tcl::chan::zero +.RE +3DES +.RS +.TP +\fBfiles/modules/des/des.n\fR +des +.RE +abstract syntax tree +.RS +.TP +\fBfiles/modules/grammar_me/me_util.n\fR +grammar::me::util +.TP +\fBfiles/modules/grammar_me/me_ast.n\fR +grammar::me_ast +.RE +acceptance +.RS +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.RE +acceptor +.RS +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.RE +active +.RS +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.RE +adaptors +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +adjacency list +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +adjacency matrix +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +adjacent +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +adjusting +.RS +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +adler32 +.RS +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.RE +aes +.RS +.TP +\fBfiles/modules/aes/aes.n\fR +aes +.RE +after +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +alias +.RS +.TP +\fBfiles/modules/interp/tcllib_interp.n\fR +interp +.RE +amazon +.RS +.TP +\fBfiles/modules/amazon-s3/S3.n\fR +S3 +.RE +ambiguous +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.RE +angle +.RS +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +anonymous procedure +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.RE +ansi +.RS +.TP +\fBfiles/modules/term/ansi_cattr.n\fR +term::ansi::code::attr +.TP +\fBfiles/modules/term/ansi_cctrl.n\fR +term::ansi::code::ctrl +.TP +\fBfiles/modules/term/ansi_cmacros.n\fR +term::ansi::code::macros +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +appender +.RS +.TP +\fBfiles/modules/log/loggerAppender.n\fR +logger::appender +.TP +\fBfiles/modules/log/loggerUtils.n\fR +logger::utils +.RE +application +.RS +.TP +\fBfiles/apps/nns.n\fR +nns +.TP +\fBfiles/apps/nnsd.n\fR +nnsd +.TP +\fBfiles/apps/nnslog.n\fR +nnslog +.RE +approximation algorithm +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +arc +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +arcfour +.RS +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.RE +archive +.RS +.TP +\fBfiles/modules/tar/tar.n\fR +tar +.RE +argument integrity +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_procedure.n\fR +tepam::procedure +.RE +argument processing +.RS +.TP +\fBfiles/modules/cmdline/cmdline.n\fR +cmdline +.RE +argument validation +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_procedure.n\fR +tepam::procedure +.RE +arguments +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_procedure.n\fR +tepam::procedure +.RE +argv +.RS +.TP +\fBfiles/modules/cmdline/cmdline.n\fR +cmdline +.RE +argv0 +.RS +.TP +\fBfiles/modules/cmdline/cmdline.n\fR +cmdline +.RE +array +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +articulation point +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +ascii85 +.RS +.TP +\fBfiles/modules/base64/ascii85.n\fR +ascii85 +.RE +asn +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +assembler +.RS +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.RE +assert +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.RE +assign +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +AST +.RS +.TP +\fBfiles/modules/grammar_me/me_ast.n\fR +grammar::me_ast +.RE +asynchronous +.RS +.TP +\fBfiles/modules/cache/async.n\fR +cache::async +.RE +attribute control +.RS +.TP +\fBfiles/modules/term/ansi_cattr.n\fR +term::ansi::code::attr +.TP +\fBfiles/modules/term/ansi_cctrl.n\fR +term::ansi::code::ctrl +.RE +augmenting network +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +augmenting path +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +authentication +.RS +.TP +\fBfiles/modules/http/autoproxy.n\fR +autoproxy +.TP +\fBfiles/modules/sasl/sasl.n\fR +SASL +.RE +automatic +.RS +.TP +\fBfiles/modules/nns/nns_auto.n\fR +nameserv::auto +.RE +automaton +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.RE +aycock +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.RE +base32 +.RS +.TP +\fBfiles/modules/base32/base32.n\fR +base32 +.TP +\fBfiles/modules/base32/base32core.n\fR +base32::core +.TP +\fBfiles/modules/base32/base32hex.n\fR +base32::hex +.RE +base64 +.RS +.TP +\fBfiles/modules/base64/base64.n\fR +base64 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.RE +bee +.RS +.TP +\fBfiles/modules/bee/bee.n\fR +bee +.RE +bench language +.RS +.TP +\fBfiles/modules/bench/bench_intro.n\fR +bench_intro +.TP +\fBfiles/modules/bench/bench_lang_intro.n\fR +bench_lang_intro +.TP +\fBfiles/modules/bench/bench_lang_spec.n\fR +bench_lang_spec +.RE +benchmark +.RS +.TP +\fBfiles/modules/bench/bench.n\fR +bench +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wcsv.n\fR +bench::out::csv +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.TP +\fBfiles/modules/bench/bench_intro.n\fR +bench_intro +.TP +\fBfiles/modules/bench/bench_lang_intro.n\fR +bench_lang_intro +.TP +\fBfiles/modules/bench/bench_lang_spec.n\fR +bench_lang_spec +.RE +ber +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +Bessel functions +.RS +.TP +\fBfiles/modules/math/special.n\fR +math::special +.RE +bfs +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +bibliography +.RS +.TP +\fBfiles/modules/bibtex/bibtex.n\fR +bibtex +.RE +bibtex +.RS +.TP +\fBfiles/modules/bibtex/bibtex.n\fR +bibtex +.RE +bignums +.RS +.TP +\fBfiles/modules/math/bignum.n\fR +math::bignum +.RE +bind +.RS +.TP +\fBfiles/modules/uev/uevent.n\fR +uevent +.RE +bipartite +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +BitTorrent +.RS +.TP +\fBfiles/modules/bee/bee.n\fR +bee +.RE +bittorrent +.RS +.TP +\fBfiles/modules/bee/bee.n\fR +bee +.RE +blanks +.RS +.TP +\fBfiles/modules/textutil/repeat.n\fR +textutil::repeat +.RE +block cipher +.RS +.TP +\fBfiles/modules/aes/aes.n\fR +aes +.TP +\fBfiles/modules/blowfish/blowfish.n\fR +blowfish +.TP +\fBfiles/modules/des/des.n\fR +des +.RE +blocking flow +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +blowfish +.RS +.TP +\fBfiles/modules/blowfish/blowfish.n\fR +blowfish +.RE +breadth-first +.RS +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +bridge +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +BWidget +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +C +.RS +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.RE +C++ +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.TP +\fBfiles/modules/stooop/stooop.n\fR +stooop +.RE +cache +.RS +.TP +\fBfiles/modules/cache/async.n\fR +cache::async +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.RE +caesar cipher +.RS +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +calculus +.RS +.TP +\fBfiles/modules/math/calculus.n\fR +math::calculus +.RE +callback +.RS +.TP +\fBfiles/modules/cache/async.n\fR +cache::async +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +callbacks +.RS +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.RE +capitalize +.RS +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.RE +cardinality +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +cat +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.RE +catalog package +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +catalogue +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +cer +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +CFG +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.RE +CFL +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.RE +CGI +.RS +.TP +\fBfiles/modules/ncgi/ncgi.n\fR +ncgi +.RE +cgraph +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graph1.n\fR +struct::graph_v1 +.RE +changelog +.RS +.TP +\fBfiles/modules/doctools/changelog.n\fR +doctools::changelog +.TP +\fBfiles/modules/doctools/cvs.n\fR +doctools::cvs +.RE +channel +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.TP +\fBfiles/modules/transfer/copyops.n\fR +transfer::copy +.TP +\fBfiles/modules/transfer/tqueue.n\fR +transfer::copy::queue +.TP +\fBfiles/modules/transfer/ddest.n\fR +transfer::data::destination +.TP +\fBfiles/modules/transfer/dsource.n\fR +transfer::data::source +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +channel transformation +.RS +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +character input +.RS +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.RE +character output +.RS +.TP +\fBfiles/modules/term/ansi_send.n\fR +term::ansi::send +.TP +\fBfiles/modules/term/term_send.n\fR +term::send +.RE +chat +.RS +.TP +\fBfiles/modules/irc/irc.n\fR +irc +.TP +\fBfiles/modules/multiplexer/multiplexer.n\fR +multiplexer +.TP +\fBfiles/modules/irc/picoirc.n\fR +picoirc +.RE +checkbox +.RS +.TP +\fBfiles/modules/html/html.n\fR +html +.TP +\fBfiles/modules/javascript/javascript.n\fR +javascript +.RE +checkbutton +.RS +.TP +\fBfiles/modules/html/html.n\fR +html +.RE +checksum +.RS +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.RE +chop +.RS +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.RE +cipher +.RS +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +cksum +.RS +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +class +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.TP +\fBfiles/modules/stooop/stooop.n\fR +stooop +.RE +class methods +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +class variables +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +cleanup +.RS +.TP +\fBfiles/modules/try/tcllib_try.n\fR +try +.RE +client +.RS +.TP +\fBfiles/modules/nns/nns_client.n\fR +nameserv +.TP +\fBfiles/modules/nns/nns_auto.n\fR +nameserv::auto +.TP +\fBfiles/modules/nns/nns_common.n\fR +nameserv::common +.TP +\fBfiles/apps/nns.n\fR +nns +.TP +\fBfiles/modules/nns/nns_intro.n\fR +nns_intro +.TP +\fBfiles/apps/nnslog.n\fR +nnslog +.RE +cloud +.RS +.TP +\fBfiles/modules/amazon-s3/S3.n\fR +S3 +.RE +cmdline processing +.RS +.TP +\fBfiles/modules/cmdline/cmdline.n\fR +cmdline +.RE +color control +.RS +.TP +\fBfiles/modules/term/ansi_cattr.n\fR +term::ansi::code::attr +.TP +\fBfiles/modules/term/ansi_cctrl.n\fR +term::ansi::code::ctrl +.RE +columns +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +comm +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.TP +\fBfiles/modules/interp/deleg_method.n\fR +deleg_method +.TP +\fBfiles/modules/interp/deleg_proc.n\fR +deleg_proc +.TP +\fBfiles/modules/nns/nns_protocol.n\fR +nameserv::protocol +.RE +command +.RS +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.RE +command line processing +.RS +.TP +\fBfiles/modules/cmdline/cmdline.n\fR +cmdline +.RE +command prefix +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +comment +.RS +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.TP +\fBfiles/modules/png/png.n\fR +png +.RE +common +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +common prefix +.RS +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.RE +communication +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.RE +comparison +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +complete graph +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +complex numbers +.RS +.TP +\fBfiles/modules/math/qcomplex.n\fR +math::complexnumbers +.TP +\fBfiles/modules/math/fourier.n\fR +math::fourier +.RE +compression +.RS +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +computations +.RS +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.RE +concatenation channel +.RS +.TP +\fBfiles/modules/virtchannel_base/cat.n\fR +tcl::chan::cat +.TP +\fBfiles/modules/virtchannel_base/facade.n\fR +tcl::chan::facade +.RE +connected component +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +connected fifos +.RS +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.RE +connection +.RS +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.RE +constants +.RS +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +CONTAINER +.RS +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.RE +contents +.RS +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.RE +context-free grammar +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.RE +context-free languages +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +control +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.TP +\fBfiles/modules/term/term.n\fR +term +.TP +\fBfiles/modules/term/ansi_code.n\fR +term::ansi::code +.TP +\fBfiles/modules/term/ansi_cattr.n\fR +term::ansi::code::attr +.TP +\fBfiles/modules/term/ansi_cctrl.n\fR +term::ansi::code::ctrl +.TP +\fBfiles/modules/term/ansi_cmacros.n\fR +term::ansi::code::macros +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.TP +\fBfiles/modules/term/ansi_send.n\fR +term::ansi::send +.TP +\fBfiles/modules/term/imenu.n\fR +term::interact::menu +.TP +\fBfiles/modules/term/ipager.n\fR +term::interact::pager +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.TP +\fBfiles/modules/term/term_send.n\fR +term::send +.RE +control structure +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +conversion +.RS +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/math/roman.n\fR +math::roman +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +cooked +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +cookie +.RS +.TP +\fBfiles/modules/ncgi/ncgi.n\fR +ncgi +.RE +copy +.RS +.TP +\fBfiles/modules/fileutil/multi.n\fR +fileutil::multi +.TP +\fBfiles/modules/fileutil/multiop.n\fR +fileutil::multi::op +.TP +\fBfiles/modules/transfer/copyops.n\fR +transfer::copy +.TP +\fBfiles/modules/transfer/tqueue.n\fR +transfer::copy::queue +.TP +\fBfiles/modules/transfer/ddest.n\fR +transfer::data::destination +.TP +\fBfiles/modules/transfer/dsource.n\fR +transfer::data::source +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +coroutine +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +Cost +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +counter +.RS +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.RE +counting +.RS +.TP +\fBfiles/modules/counter/counter.n\fR +counter +.RE +CPARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.RE +crc +.RS +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +crc16 +.RS +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.RE +crc32 +.RS +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.RE +cryptography +.RS +.TP +\fBfiles/modules/blowfish/blowfish.n\fR +blowfish +.RE +CSS +.RS +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.RE +csv +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wcsv.n\fR +bench::out::csv +.TP +\fBfiles/modules/csv/csv.n\fR +csv +.RE +currying +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +cut edge +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +cut vertex +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +CVS +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +cvs +.RS +.TP +\fBfiles/modules/doctools/cvs.n\fR +doctools::cvs +.RE +cvs log +.RS +.TP +\fBfiles/modules/doctools/cvs.n\fR +doctools::cvs +.RE +cyclic redundancy check +.RS +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +data analysis +.RS +.TP +\fBfiles/modules/math/statistics.n\fR +math::statistics +.RE +data destination +.RS +.TP +\fBfiles/modules/transfer/ddest.n\fR +transfer::data::destination +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.RE +data entry form +.RS +.TP +\fBfiles/modules/tepam/tepam_argument_dialogbox.n\fR +tepam::argument_dialogbox +.RE +data exchange +.RS +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/json/json.n\fR +json +.TP +\fBfiles/modules/json/json_write.n\fR +json::write +.TP +\fBfiles/modules/yaml/yaml.n\fR +yaml +.RE +data integrity +.RS +.TP +\fBfiles/modules/aes/aes.n\fR +aes +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/des/des.n\fR +des +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +data source +.RS +.TP +\fBfiles/modules/transfer/dsource.n\fR +transfer::data::source +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +data structures +.RS +.TP +\fBfiles/modules/struct/record.n\fR +struct::record +.RE +database +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +dataflow +.RS +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.RE +DE +.RS +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.RE +decimal +.RS +.TP +\fBfiles/modules/math/decimal.n\fR +math::decimal +.RE +declare +.RS +.TP +\fBfiles/modules/term/ansi_code.n\fR +term::ansi::code +.RE +decompression +.RS +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +decryption +.RS +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +deferal +.RS +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +define +.RS +.TP +\fBfiles/modules/term/ansi_code.n\fR +term::ansi::code +.RE +degree +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +degree constrained spanning tree +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +degrees +.RS +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.RE +delegation +.RS +.TP +\fBfiles/modules/interp/deleg_method.n\fR +deleg_method +.TP +\fBfiles/modules/interp/deleg_proc.n\fR +deleg_proc +.RE +depth-first +.RS +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +der +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +DES +.RS +.TP +\fBfiles/modules/des/des.n\fR +des +.RE +deserialization +.RS +.TP +\fBfiles/modules/doctools2idx/import_docidx.n\fR +doctools::idx::import::docidx +.TP +\fBfiles/modules/doctools2idx/import_json.n\fR +doctools::idx::import::json +.TP +\fBfiles/modules/doctools2idx/structure.n\fR +doctools::idx::structure +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.TP +\fBfiles/modules/doctools2toc/structure.n\fR +doctools::toc::structure +.RE +diameter +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +diff +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +diff -n format +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +difference +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +differential +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +differential equations +.RS +.TP +\fBfiles/modules/math/calculus.n\fR +math::calculus +.RE +dijkstra +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +directory access +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.RE +directory traversal +.RS +.TP +\fBfiles/modules/fileutil/traverse.n\fR +fileutil_traverse +.RE +discrete items +.RS +.TP +\fBfiles/modules/struct/pool.n\fR +struct::pool +.RE +disjoint set +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +dispatcher +.RS +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.RE +distance +.RS +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +DNS +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +do +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.RE +docidx +.RS +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_docidx.n\fR +doctools::idx::export::docidx +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2idx/import_docidx.n\fR +doctools::idx::import::docidx +.TP +\fBfiles/modules/doctools2idx/parse.n\fR +doctools::idx::parse +.TP +\fBfiles/modules/doctools2idx/structure.n\fR +doctools::idx::structure +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.RE +docidx commands +.RS +.TP +\fBfiles/modules/doctools/docidx_lang_cmdref.n\fR +docidx_lang_cmdref +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.RE +docidx language +.RS +.TP +\fBfiles/modules/doctools/docidx_lang_cmdref.n\fR +docidx_lang_cmdref +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.RE +docidx markup +.RS +.TP +\fBfiles/modules/doctools/docidx_lang_cmdref.n\fR +docidx_lang_cmdref +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.RE +docidx syntax +.RS +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.RE +docstrip +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +doctoc +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/parse.n\fR +doctools::toc::parse +.TP +\fBfiles/modules/doctools2toc/structure.n\fR +doctools::toc::structure +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.RE +doctoc commands +.RS +.TP +\fBfiles/modules/doctools/doctoc_lang_cmdref.n\fR +doctoc_lang_cmdref +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.RE +doctoc language +.RS +.TP +\fBfiles/modules/doctools/doctoc_lang_cmdref.n\fR +doctoc_lang_cmdref +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.RE +doctoc markup +.RS +.TP +\fBfiles/modules/doctools/doctoc_lang_cmdref.n\fR +doctoc_lang_cmdref +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.RE +doctoc syntax +.RS +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.RE +doctools +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/modules/doctools/changelog.n\fR +doctools::changelog +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.TP +\fBfiles/modules/doctools2idx/export_docidx.n\fR +doctools::idx::export::docidx +.TP +\fBfiles/modules/doctools2idx/export_html.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools2idx/export_json.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/export_nroff.n\fR +doctools::idx::export::nroff +.TP +\fBfiles/modules/doctools2idx/export_text.n\fR +doctools::idx::export::text +.TP +\fBfiles/modules/doctools2idx/export_wiki.n\fR +doctools::idx::export::wiki +.TP +\fBfiles/modules/doctools2idx/import_docidx.n\fR +doctools::idx::import::docidx +.TP +\fBfiles/modules/doctools2idx/import_json.n\fR +doctools::idx::import::json +.TP +\fBfiles/modules/doctools2idx/parse.n\fR +doctools::idx::parse +.TP +\fBfiles/modules/doctools2idx/structure.n\fR +doctools::idx::structure +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.TP +\fBfiles/modules/doctools2toc/parse.n\fR +doctools::toc::parse +.TP +\fBfiles/modules/doctools2toc/structure.n\fR +doctools::toc::structure +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.RE +doctools commands +.RS +.TP +\fBfiles/modules/doctools/doctools_lang_cmdref.n\fR +doctools_lang_cmdref +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.RE +doctools language +.RS +.TP +\fBfiles/modules/doctools/doctools_lang_cmdref.n\fR +doctools_lang_cmdref +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.RE +doctools markup +.RS +.TP +\fBfiles/modules/doctools/doctools_lang_cmdref.n\fR +doctools_lang_cmdref +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.RE +doctools syntax +.RS +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.RE +document +.RS +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.RE +documentation +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +DOM +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +dom +.RS +.TP +\fBfiles/modules/amazon-s3/xsxp.n\fR +xsxp +.RE +domain name service +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +e +.RS +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.RE +earley +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.RE +EBNF +.RS +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +eccentricity +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +edge +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +emacs +.RS +.TP +\fBfiles/modules/doctools/changelog.n\fR +doctools::changelog +.TP +\fBfiles/modules/doctools/cvs.n\fR +doctools::cvs +.RE +email +.RS +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +emptiness +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +empty interpreter +.RS +.TP +\fBfiles/modules/interp/tcllib_interp.n\fR +interp +.RE +EN +.RS +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.RE +encoding +.RS +.TP +\fBfiles/modules/base64/ascii85.n\fR +ascii85 +.TP +\fBfiles/modules/base64/base64.n\fR +base64 +.TP +\fBfiles/modules/base64/uuencode.n\fR +uuencode +.TP +\fBfiles/modules/base64/yencode.n\fR +yencode +.RE +encryption +.RS +.TP +\fBfiles/modules/aes/aes.n\fR +aes +.TP +\fBfiles/modules/blowfish/blowfish.n\fR +blowfish +.TP +\fBfiles/modules/des/des.n\fR +des +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +entry mask +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.RE +equal +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +equality +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +equivalence class +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +error +.RS +.TP +\fBfiles/modules/try/tcllib_try.n\fR +try +.RE +error function +.RS +.TP +\fBfiles/modules/math/special.n\fR +math::special +.RE +event +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.TP +\fBfiles/modules/uev/uevent.n\fR +uevent +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +event management +.RS +.TP +\fBfiles/modules/virtchannel_core/events.n\fR +tcl::chan::events +.RE +events +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +examples +.RS +.TP +\fBfiles/modules/bench/bench_lang_intro.n\fR +bench_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.RE +exception +.RS +.TP +\fBfiles/modules/try/tcllib_try.n\fR +try +.RE +exchange format +.RS +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/json/json.n\fR +json +.TP +\fBfiles/modules/json/json_write.n\fR +json::write +.RE +exclusion +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +execution +.RS +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.RE +exif +.RS +.TP +\fBfiles/modules/exif/exif.n\fR +exif +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.RE +exit +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +export +.RS +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_docidx.n\fR +doctools::idx::export::docidx +.TP +\fBfiles/modules/doctools2idx/export_html.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools2idx/export_json.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/export_nroff.n\fR +doctools::idx::export::nroff +.TP +\fBfiles/modules/doctools2idx/export_text.n\fR +doctools::idx::export::text +.TP +\fBfiles/modules/doctools2idx/export_wiki.n\fR +doctools::idx::export::wiki +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.RE +expression +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +extended namespace +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +faq +.RS +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.RE +fetching information +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +FFT +.RS +.TP +\fBfiles/modules/math/fourier.n\fR +math::fourier +.RE +fifo +.RS +.TP +\fBfiles/modules/virtchannel_base/fifo.n\fR +tcl::chan::fifo +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.RE +file +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +file recognition +.RS +.TP +\fBfiles/modules/fumagic/cfront.n\fR +fileutil::magic::cfront +.TP +\fBfiles/modules/fumagic/cgen.n\fR +fileutil::magic::cgen +.TP +\fBfiles/modules/fumagic/filetypes.n\fR +fileutil::magic::filetype +.TP +\fBfiles/modules/fumagic/mimetypes.n\fR +fileutil::magic::mimetype +.TP +\fBfiles/modules/fumagic/rtcore.n\fR +fileutil::magic::rt +.RE +file type +.RS +.TP +\fBfiles/modules/fumagic/cfront.n\fR +fileutil::magic::cfront +.TP +\fBfiles/modules/fumagic/cgen.n\fR +fileutil::magic::cgen +.TP +\fBfiles/modules/fumagic/filetypes.n\fR +fileutil::magic::filetype +.TP +\fBfiles/modules/fumagic/mimetypes.n\fR +fileutil::magic::mimetype +.TP +\fBfiles/modules/fumagic/rtcore.n\fR +fileutil::magic::rt +.RE +file utilities +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.TP +\fBfiles/modules/fumagic/cfront.n\fR +fileutil::magic::cfront +.TP +\fBfiles/modules/fumagic/cgen.n\fR +fileutil::magic::cgen +.TP +\fBfiles/modules/fumagic/filetypes.n\fR +fileutil::magic::filetype +.TP +\fBfiles/modules/fumagic/mimetypes.n\fR +fileutil::magic::mimetype +.TP +\fBfiles/modules/fumagic/rtcore.n\fR +fileutil::magic::rt +.TP +\fBfiles/modules/fileutil/multi.n\fR +fileutil::multi +.TP +\fBfiles/modules/fileutil/multiop.n\fR +fileutil::multi::op +.RE +filesystem +.RS +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.RE +filter +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +final +.RS +.TP +\fBfiles/modules/try/tcllib_try.n\fR +try +.RE +find +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +finite +.RS +.TP +\fBfiles/modules/struct/pool.n\fR +struct::pool +.RE +finite automaton +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.RE +FIPS 180-1 +.RS +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.RE +first permutation +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +Fisher-Yates +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +flatten +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +floating-point +.RS +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.TP +\fBfiles/modules/math/fuzzy.n\fR +math::fuzzy +.RE +flow +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.RE +flow network +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +folding +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +foldl +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +foldr +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +foreach +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +form +.RS +.TP +\fBfiles/modules/html/html.n\fR +html +.TP +\fBfiles/modules/ncgi/ncgi.n\fR +ncgi +.RE +format conversion +.RS +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.RE +formatter +.RS +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.RE +formatting +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wcsv.n\fR +bench::out::csv +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.TP +\fBfiles/modules/textutil/tabify.n\fR +textutil::tabify +.RE +formatting engine +.RS +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.RE +Fourier transform +.RS +.TP +\fBfiles/modules/math/fourier.n\fR +math::fourier +.RE +FR +.RS +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +frame +.RS +.TP +\fBfiles/modules/term/ansi_cmacros.n\fR +term::ansi::code::macros +.RE +ftp +.RS +.TP +\fBfiles/modules/ftp/ftp.n\fR +ftp +.TP +\fBfiles/modules/ftp/ftp_geturl.n\fR +ftp::geturl +.TP +\fBfiles/modules/ftpd/ftpd.n\fR +ftpd +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +ftpd +.RS +.TP +\fBfiles/modules/ftpd/ftpd.n\fR +ftpd +.RE +ftpserver +.RS +.TP +\fBfiles/modules/ftpd/ftpd.n\fR +ftpd +.RE +full outer join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +generate event +.RS +.TP +\fBfiles/modules/uev/uevent.n\fR +uevent +.RE +generate permutations +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +generation +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.RE +generator +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +geocoding +.RS +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.RE +geodesy +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.TP +\fBfiles/modules/mapproj/mapproj.n\fR +mapproj +.RE +geography +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.RE +get character +.RS +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.RE +gets +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +global +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +gopher +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +gps +.RS +.TP +\fBfiles/modules/gpx/gpx.n\fR +gpx +.TP +\fBfiles/modules/nmea/nmea.n\fR +nmea +.RE +gpx +.RS +.TP +\fBfiles/modules/gpx/gpx.n\fR +gpx +.RE +grammar +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.TP +\fBfiles/modules/grammar_me/me_cpu.n\fR +grammar::me::cpu +.TP +\fBfiles/modules/grammar_me/me_cpucore.n\fR +grammar::me::cpu::core +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.TP +\fBfiles/modules/grammar_me/me_tcl.n\fR +grammar::me::tcl +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_me/me_vm.n\fR +grammar::me_vm +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +graph +.RS +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.TP +\fBfiles/modules/struct/graph1.n\fR +struct::graph_v1 +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/stack.n\fR +struct::stack +.RE +graph walking +.RS +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.RE +green threads +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +grep +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.RE +GUID +.RS +.TP +\fBfiles/modules/uuid/uuid.n\fR +uuid +.RE +hashing +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/md5crypt/md5crypt.n\fR +md5crypt +.TP +\fBfiles/modules/otp/otp.n\fR +otp +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.RE +heuristic +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +hex +.RS +.TP +\fBfiles/modules/base32/base32hex.n\fR +base32::hex +.RE +hexadecimal +.RS +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.RE +histogram +.RS +.TP +\fBfiles/modules/counter/counter.n\fR +counter +.RE +hook +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.TP +\fBfiles/modules/uev/uevent.n\fR +uevent +.RE +horspool +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.RE +HTML +.RS +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_html.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.RE +html +.RS +.TP +\fBfiles/modules/html/html.n\fR +html +.TP +\fBfiles/modules/htmlparse/htmlparse.n\fR +htmlparse +.TP +\fBfiles/modules/javascript/javascript.n\fR +javascript +.TP +\fBfiles/modules/ncgi/ncgi.n\fR +ncgi +.RE +http +.RS +.TP +\fBfiles/modules/http/autoproxy.n\fR +autoproxy +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +huddle +.RS +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/yaml/yaml.n\fR +yaml +.RE +human readable +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.RE +hyphenation +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +i18n +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +ident +.RS +.TP +\fBfiles/modules/ident/ident.n\fR +ident +.RE +identification +.RS +.TP +\fBfiles/modules/ident/ident.n\fR +ident +.RE +identity +.RS +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.RE +idle +.RS +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +image +.RS +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.TP +\fBfiles/modules/png/png.n\fR +png +.TP +\fBfiles/modules/tiff/tiff.n\fR +tiff +.RE +imap +.RS +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.RE +import +.RS +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2idx/import_docidx.n\fR +doctools::idx::import::docidx +.TP +\fBfiles/modules/doctools2idx/import_json.n\fR +doctools::idx::import::json +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.RE +in-memory channel +.RS +.TP +\fBfiles/modules/virtchannel_base/fifo.n\fR +tcl::chan::fifo +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.TP +\fBfiles/modules/virtchannel_base/memchan.n\fR +tcl::chan::memchan +.TP +\fBfiles/modules/virtchannel_base/string.n\fR +tcl::chan::string +.TP +\fBfiles/modules/virtchannel_base/variable.n\fR +tcl::chan::variable +.RE +in-order +.RS +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +inclusion +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +Incr Tcl +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +indenting +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +independent set +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +index +.RS +.TP +\fBfiles/modules/doctools/docidx_intro.n\fR +docidx_intro +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_docidx.n\fR +doctools::idx::export::docidx +.TP +\fBfiles/modules/doctools2idx/export_html.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools2idx/export_json.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/export_nroff.n\fR +doctools::idx::export::nroff +.TP +\fBfiles/modules/doctools2idx/export_text.n\fR +doctools::idx::export::text +.TP +\fBfiles/modules/doctools2idx/export_wiki.n\fR +doctools::idx::export::wiki +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2idx/import_docidx.n\fR +doctools::idx::import::docidx +.TP +\fBfiles/modules/doctools2idx/import_json.n\fR +doctools::idx::import::json +.RE +index formatter +.RS +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.RE +info +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +inner join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +input mode +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +integer +.RS +.TP +\fBfiles/modules/math/roman.n\fR +math::roman +.RE +integration +.RS +.TP +\fBfiles/modules/math/calculus.n\fR +math::calculus +.RE +inter-thread communication +.RS +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.RE +internationalization +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +internet +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.TP +\fBfiles/modules/ftp/ftp.n\fR +ftp +.TP +\fBfiles/modules/ftp/ftp_geturl.n\fR +ftp::geturl +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/pop3d/pop3d_dbox.n\fR +pop3d::dbox +.TP +\fBfiles/modules/pop3d/pop3d_udb.n\fR +pop3d::udb +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +internet address +.RS +.TP +\fBfiles/modules/dns/tcllib_ip.n\fR +tcllib_ip +.RE +interpolation +.RS +.TP +\fBfiles/modules/math/interpolate.n\fR +math::interpolate +.RE +interpreter +.RS +.TP +\fBfiles/modules/interp/deleg_method.n\fR +deleg_method +.TP +\fBfiles/modules/interp/deleg_proc.n\fR +deleg_proc +.TP +\fBfiles/modules/interp/tcllib_interp.n\fR +interp +.TP +\fBfiles/modules/wip/wip.n\fR +wip +.RE +intersection +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +interval +.RS +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.RE +ip +.RS +.TP +\fBfiles/modules/dns/tcllib_ip.n\fR +tcllib_ip +.RE +ipc +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.RE +ipv4 +.RS +.TP +\fBfiles/modules/dns/tcllib_ip.n\fR +tcllib_ip +.RE +ipv6 +.RS +.TP +\fBfiles/modules/dns/tcllib_ip.n\fR +tcllib_ip +.RE +irc +.RS +.TP +\fBfiles/modules/irc/irc.n\fR +irc +.TP +\fBfiles/modules/irc/picoirc.n\fR +picoirc +.RE +isthmus +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +iterator +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +javascript +.RS +.TP +\fBfiles/modules/javascript/javascript.n\fR +javascript +.TP +\fBfiles/modules/json/json.n\fR +json +.TP +\fBfiles/modules/json/json_write.n\fR +json::write +.RE +jfif +.RS +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.RE +join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +jpeg +.RS +.TP +\fBfiles/modules/exif/exif.n\fR +exif +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.RE +JSON +.RS +.TP +\fBfiles/modules/doctools2idx/export_json.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/import_json.n\fR +doctools::idx::import::json +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.RE +json +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/json/json.n\fR +json +.TP +\fBfiles/modules/json/json_write.n\fR +json::write +.RE +justification +.RS +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +keyword index +.RS +.TP +\fBfiles/modules/doctools/docidx_intro.n\fR +docidx_intro +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.RE +keywords +.RS +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.RE +knuth +.RS +.TP +\fBfiles/modules/soundex/soundex.n\fR +soundex +.RE +l10n +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +lambda +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.RE +LaTeX +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +latex +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.RE +latitute +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.RE +ldap +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +ldap client +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.RE +ldif +.RS +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.RE +least squares +.RS +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.RE +left outer join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +lemon +.RS +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.RE +level graph +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +lexer +.RS +.TP +\fBfiles/modules/doctools2idx/parse.n\fR +doctools::idx::parse +.TP +\fBfiles/modules/doctools2toc/parse.n\fR +doctools::toc::parse +.RE +limitsize +.RS +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.RE +line +.RS +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.RE +linear algebra +.RS +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.RE +linear equations +.RS +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.RE +linear program +.RS +.TP +\fBfiles/modules/math/optimize.n\fR +math::optimize +.RE +lines +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +list +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/wip/wip.n\fR +wip +.RE +listener +.RS +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.RE +literate programming +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +LL(k) +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +local searching +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +localization +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +location +.RS +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.RE +log +.RS +.TP +\fBfiles/modules/doctools/cvs.n\fR +doctools::cvs +.TP +\fBfiles/modules/log/log.n\fR +log +.TP +\fBfiles/modules/log/logger.n\fR +logger +.RE +log level +.RS +.TP +\fBfiles/modules/log/log.n\fR +log +.TP +\fBfiles/modules/log/logger.n\fR +logger +.RE +logger +.RS +.TP +\fBfiles/modules/log/logger.n\fR +logger +.TP +\fBfiles/modules/log/loggerAppender.n\fR +logger::appender +.TP +\fBfiles/modules/log/loggerUtils.n\fR +logger::utils +.RE +longest common subsequence +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +longitude +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.RE +loop +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +macros +.RS +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.RE +mail +.RS +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +mailto +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +maker note +.RS +.TP +\fBfiles/modules/exif/exif.n\fR +exif +.RE +man_macros +.RS +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.RE +manpage +.RS +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.RE +map +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.TP +\fBfiles/modules/mapproj/mapproj.n\fR +mapproj +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +markup +.RS +.TP +\fBfiles/modules/doctools/docidx_intro.n\fR +docidx_intro +.TP +\fBfiles/modules/doctools/docidx_lang_cmdref.n\fR +docidx_lang_cmdref +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.TP +\fBfiles/modules/doctools/doctoc_intro.n\fR +doctoc_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_cmdref.n\fR +doctoc_lang_cmdref +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/doctools/doctools_intro.n\fR +doctools_intro +.TP +\fBfiles/modules/doctools/doctools_lang_cmdref.n\fR +doctools_lang_cmdref +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +matching +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +math +.RS +.TP +\fBfiles/modules/math/math.n\fR +math +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.TP +\fBfiles/modules/math/bignum.n\fR +math::bignum +.TP +\fBfiles/modules/math/calculus.n\fR +math::calculus +.TP +\fBfiles/modules/math/qcomplex.n\fR +math::complexnumbers +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.TP +\fBfiles/modules/math/decimal.n\fR +math::decimal +.TP +\fBfiles/modules/math/fuzzy.n\fR +math::fuzzy +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.TP +\fBfiles/modules/math/interpolate.n\fR +math::interpolate +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.TP +\fBfiles/modules/math/optimize.n\fR +math::optimize +.TP +\fBfiles/modules/math/polynomials.n\fR +math::polynomials +.TP +\fBfiles/modules/math/rational_funcs.n\fR +math::rationalfunctions +.TP +\fBfiles/modules/math/special.n\fR +math::special +.TP +\fBfiles/modules/simulation/annealing.n\fR +simulation::annealing +.TP +\fBfiles/modules/simulation/montecarlo.n\fR +simulation::montecarlo +.TP +\fBfiles/modules/simulation/simulation_random.n\fR +simulation::random +.RE +mathematics +.RS +.TP +\fBfiles/modules/math/fourier.n\fR +math::fourier +.TP +\fBfiles/modules/math/statistics.n\fR +math::statistics +.RE +matrices +.RS +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.RE +matrix +.RS +.TP +\fBfiles/modules/csv/csv.n\fR +csv +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.TP +\fBfiles/modules/report/report.n\fR +report +.TP +\fBfiles/modules/struct/matrix.n\fR +struct::matrix +.TP +\fBfiles/modules/struct/matrix1.n\fR +struct::matrix_v1 +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/stack.n\fR +struct::stack +.RE +max cut +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +maximum +.RS +.TP +\fBfiles/modules/math/optimize.n\fR +math::optimize +.RE +maximum flow +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +md4 +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.RE +md5 +.RS +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/md5crypt/md5crypt.n\fR +md5crypt +.RE +md5crypt +.RS +.TP +\fBfiles/modules/md5crypt/md5crypt.n\fR +md5crypt +.RE +mega widget +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +membership +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +menu +.RS +.TP +\fBfiles/modules/term/ansi_cmacros.n\fR +term::ansi::code::macros +.TP +\fBfiles/modules/term/imenu.n\fR +term::interact::menu +.RE +merge +.RS +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +merge find +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +merging +.RS +.TP +\fBfiles/modules/bench/bench.n\fR +bench +.RE +message +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.TP +\fBfiles/modules/log/log.n\fR +log +.RE +message catalog +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +message level +.RS +.TP +\fBfiles/modules/log/log.n\fR +log +.RE +message package +.RS +.TP +\fBfiles/modules/doctools2base/tcllib_msgcat.n\fR +doctools::msgcat +.TP +\fBfiles/modules/doctools2idx/msgcat_c.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2idx/msgcat_de.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2idx/msgcat_en.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2idx/msgcat_fr.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/msgcat_c.n\fR +doctools::msgcat::toc::c +.TP +\fBfiles/modules/doctools2toc/msgcat_de.n\fR +doctools::msgcat::toc::de +.TP +\fBfiles/modules/doctools2toc/msgcat_en.n\fR +doctools::msgcat::toc::en +.TP +\fBfiles/modules/doctools2toc/msgcat_fr.n\fR +doctools::msgcat::toc::fr +.RE +message-digest +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/md5crypt/md5crypt.n\fR +md5crypt +.TP +\fBfiles/modules/otp/otp.n\fR +otp +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.RE +metakit +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +method +.RS +.TP +\fBfiles/modules/interp/deleg_method.n\fR +deleg_method +.TP +\fBfiles/modules/interp/tcllib_interp.n\fR +interp +.RE +method reference +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +mime +.RS +.TP +\fBfiles/modules/fumagic/cfront.n\fR +fileutil::magic::cfront +.TP +\fBfiles/modules/fumagic/cgen.n\fR +fileutil::magic::cgen +.TP +\fBfiles/modules/fumagic/mimetypes.n\fR +fileutil::magic::mimetype +.TP +\fBfiles/modules/fumagic/rtcore.n\fR +fileutil::magic::rt +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +minimal spanning tree +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +minimum +.RS +.TP +\fBfiles/modules/math/optimize.n\fR +math::optimize +.RE +minimum cost flow +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +minimum degree spanning tree +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +minimum diameter spanning tree +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +module +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +montecarlo simulation +.RS +.TP +\fBfiles/modules/simulation/montecarlo.n\fR +simulation::montecarlo +.RE +move +.RS +.TP +\fBfiles/modules/fileutil/multi.n\fR +fileutil::multi +.TP +\fBfiles/modules/fileutil/multiop.n\fR +fileutil::multi::op +.RE +multi-file +.RS +.TP +\fBfiles/modules/fileutil/multi.n\fR +fileutil::multi +.TP +\fBfiles/modules/fileutil/multiop.n\fR +fileutil::multi::op +.RE +multiplexer +.RS +.TP +\fBfiles/modules/multiplexer/multiplexer.n\fR +multiplexer +.RE +multiprecision +.RS +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.TP +\fBfiles/modules/math/bignum.n\fR +math::bignum +.RE +my method +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +name service +.RS +.TP +\fBfiles/modules/nns/nns_client.n\fR +nameserv +.TP +\fBfiles/modules/nns/nns_auto.n\fR +nameserv::auto +.TP +\fBfiles/modules/nns/nns_common.n\fR +nameserv::common +.TP +\fBfiles/modules/nns/nns_protocol.n\fR +nameserv::protocol +.TP +\fBfiles/modules/nns/nns_server.n\fR +nameserv::server +.TP +\fBfiles/apps/nns.n\fR +nns +.TP +\fBfiles/modules/nns/nns_intro.n\fR +nns_intro +.TP +\fBfiles/apps/nnsd.n\fR +nnsd +.TP +\fBfiles/apps/nnslog.n\fR +nnslog +.RE +namespace unknown +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +namespace utilities +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +neighbour +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +net +.RS +.TP +\fBfiles/modules/ftp/ftp.n\fR +ftp +.TP +\fBfiles/modules/ftp/ftp_geturl.n\fR +ftp::geturl +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +network +.RS +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/pop3d/pop3d_dbox.n\fR +pop3d::dbox +.TP +\fBfiles/modules/pop3d/pop3d_udb.n\fR +pop3d::udb +.RE +news +.RS +.TP +\fBfiles/modules/nntp/nntp.n\fR +nntp +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +next permutation +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +nmea +.RS +.TP +\fBfiles/modules/nmea/nmea.n\fR +nmea +.RE +nntp +.RS +.TP +\fBfiles/modules/nntp/nntp.n\fR +nntp +.RE +nntpclient +.RS +.TP +\fBfiles/modules/nntp/nntp.n\fR +nntp +.RE +no-op +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.RE +node +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +nominatim +.RS +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.RE +normalization +.RS +.TP +\fBfiles/modules/bench/bench.n\fR +bench +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/stringprep/unicode.n\fR +unicode +.RE +nroff +.RS +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_nroff.n\fR +doctools::idx::export::nroff +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.RE +NTP +.RS +.TP +\fBfiles/modules/ntp/ntp_time.n\fR +ntp_time +.RE +null +.RS +.TP +\fBfiles/modules/virtchannel_base/null.n\fR +tcl::chan::null +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.RE +number theory +.RS +.TP +\fBfiles/modules/math/numtheory.n\fR +math::numtheory +.RE +object +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.TP +\fBfiles/modules/stooop/stooop.n\fR +stooop +.RE +object oriented +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.TP +\fBfiles/modules/stooop/stooop.n\fR +stooop +.RE +observer +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.RE +on-idle +.RS +.TP +\fBfiles/modules/uev/uevent_onidle.n\fR +uevent::onidle +.RE +one time pad +.RS +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.RE +optimization +.RS +.TP +\fBfiles/modules/math/optimize.n\fR +math::optimize +.TP +\fBfiles/modules/simulation/annealing.n\fR +simulation::annealing +.RE +ordered list +.RS +.TP +\fBfiles/modules/struct/prioqueue.n\fR +struct::prioqueue +.RE +otp +.RS +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.RE +outer join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +package +.RS +.TP +\fBfiles/modules/csv/csv.n\fR +csv +.RE +package indexing +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +page +.RS +.TP +\fBfiles/modules/page/page_intro.n\fR +page_intro +.TP +\fBfiles/modules/page/page_pluginmgr.n\fR +page_pluginmgr +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/page/page_util_quote.n\fR +page_util_quote +.RE +pager +.RS +.TP +\fBfiles/modules/term/ipager.n\fR +term::interact::pager +.RE +paragraph +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +PARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.RE +parameter entry form +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_argument_dialogbox.n\fR +tepam::argument_dialogbox +.RE +parser +.RS +.TP +\fBfiles/modules/doctools2idx/parse.n\fR +doctools::idx::parse +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.TP +\fBfiles/modules/doctools2toc/parse.n\fR +doctools::toc::parse +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.TP +\fBfiles/modules/amazon-s3/xsxp.n\fR +xsxp +.RE +parser generator +.RS +.TP +\fBfiles/apps/page.n\fR +page +.TP +\fBfiles/modules/page/page_intro.n\fR +page_intro +.TP +\fBfiles/modules/page/page_pluginmgr.n\fR +page_pluginmgr +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/page/page_util_quote.n\fR +page_util_quote +.RE +parsing +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bibtex/bibtex.n\fR +bibtex +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.TP +\fBfiles/modules/grammar_me/me_cpu.n\fR +grammar::me::cpu +.TP +\fBfiles/modules/grammar_me/me_cpucore.n\fR +grammar::me::cpu::core +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.TP +\fBfiles/modules/grammar_me/me_tcl.n\fR +grammar::me::tcl +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_me/me_vm.n\fR +grammar::me_vm +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/htmlparse/htmlparse.n\fR +htmlparse +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/yaml/yaml.n\fR +yaml +.RE +parsing expression +.RS +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +parsing expression grammar +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +partial application +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.RE +partition +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +partitioned set +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.RE +passive +.RS +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.RE +password +.RS +.TP +\fBfiles/modules/otp/otp.n\fR +otp +.RE +patch +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +patching +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +PEG +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +performance +.RS +.TP +\fBfiles/modules/bench/bench.n\fR +bench +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wcsv.n\fR +bench::out::csv +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.TP +\fBfiles/modules/bench/bench_intro.n\fR +bench_intro +.TP +\fBfiles/modules/bench/bench_lang_intro.n\fR +bench_lang_intro +.TP +\fBfiles/modules/bench/bench_lang_spec.n\fR +bench_lang_spec +.TP +\fBfiles/modules/profiler/profiler.n\fR +profiler +.RE +permutation +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +persistence +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +pi +.RS +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.RE +plain text +.RS +.TP +\fBfiles/modules/doctools2idx/export_text.n\fR +doctools::idx::export::text +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.RE +plane geometry +.RS +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.RE +plugin +.RS +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2base/nroff_manmacros.n\fR +doctools::nroff::man_macros +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.RE +plugin management +.RS +.TP +\fBfiles/modules/pluginmgr/pluginmgr.n\fR +pluginmgr +.RE +plugin search +.RS +.TP +\fBfiles/modules/pluginmgr/pluginmgr.n\fR +pluginmgr +.RE +png +.RS +.TP +\fBfiles/modules/png/png.n\fR +png +.RE +point +.RS +.TP +\fBfiles/modules/math/math_geometry.n\fR +math::geometry +.RE +polynomial functions +.RS +.TP +\fBfiles/modules/math/polynomials.n\fR +math::polynomials +.RE +pool +.RS +.TP +\fBfiles/modules/struct/pool.n\fR +struct::pool +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.RE +pop +.RS +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.RE +pop3 +.RS +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/pop3d/pop3d_dbox.n\fR +pop3d::dbox +.TP +\fBfiles/modules/pop3d/pop3d_udb.n\fR +pop3d::udb +.RE +post-order +.RS +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +pre-order +.RS +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +prefix +.RS +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.TP +\fBfiles/modules/textutil/trim.n\fR +textutil::trim +.RE +prime +.RS +.TP +\fBfiles/modules/math/numtheory.n\fR +math::numtheory +.RE +prioqueue +.RS +.TP +\fBfiles/modules/struct/prioqueue.n\fR +struct::prioqueue +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.RE +priority queue +.RS +.TP +\fBfiles/modules/struct/prioqueue.n\fR +struct::prioqueue +.RE +proc +.RS +.TP +\fBfiles/modules/lambda/lambda.n\fR +lambda +.RE +procedure +.RS +.TP +\fBfiles/modules/interp/deleg_proc.n\fR +deleg_proc +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_procedure.n\fR +tepam::procedure +.RE +producer +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.RE +profile +.RS +.TP +\fBfiles/modules/profiler/profiler.n\fR +profiler +.RE +projection +.RS +.TP +\fBfiles/modules/mapproj/mapproj.n\fR +mapproj +.RE +prospero +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +protocol +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.TP +\fBfiles/modules/nns/nns_protocol.n\fR +nameserv::protocol +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/pop3d/pop3d_dbox.n\fR +pop3d::dbox +.TP +\fBfiles/modules/pop3d/pop3d_udb.n\fR +pop3d::udb +.RE +proxy +.RS +.TP +\fBfiles/modules/http/autoproxy.n\fR +autoproxy +.RE +public key cipher +.RS +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.RE +publisher +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.RE +push down automaton +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +queue +.RS +.TP +\fBfiles/modules/csv/csv.n\fR +csv +.TP +\fBfiles/modules/htmlparse/htmlparse.n\fR +htmlparse +.TP +\fBfiles/modules/struct/stack.n\fR +struct::stack +.TP +\fBfiles/modules/transfer/tqueue.n\fR +transfer::copy::queue +.RE +quoting +.RS +.TP +\fBfiles/modules/page/page_util_quote.n\fR +page_util_quote +.RE +radians +.RS +.TP +\fBfiles/modules/math/constants.n\fR +math::constants +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +radiobutton +.RS +.TP +\fBfiles/modules/html/html.n\fR +html +.RE +radius +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +random +.RS +.TP +\fBfiles/modules/virtchannel_base/random.n\fR +tcl::chan::random +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.RE +random numbers +.RS +.TP +\fBfiles/modules/simulation/simulation_random.n\fR +simulation::random +.RE +rational functions +.RS +.TP +\fBfiles/modules/math/rational_funcs.n\fR +math::rationalfunctions +.RE +raw +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +rc4 +.RS +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.RE +RCS +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +RCS patch +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +read +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +reading +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.RE +receiver +.RS +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.RE +reconnect +.RS +.TP +\fBfiles/modules/nns/nns_auto.n\fR +nameserv::auto +.RE +record +.RS +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/record.n\fR +struct::record +.RE +recursive descent +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +reduce +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +reference +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.RE +reflected channel +.RS +.TP +\fBfiles/modules/virtchannel_base/cat.n\fR +tcl::chan::cat +.TP +\fBfiles/modules/virtchannel_core/core.n\fR +tcl::chan::core +.TP +\fBfiles/modules/virtchannel_core/events.n\fR +tcl::chan::events +.TP +\fBfiles/modules/virtchannel_base/facade.n\fR +tcl::chan::facade +.TP +\fBfiles/modules/virtchannel_base/fifo.n\fR +tcl::chan::fifo +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.TP +\fBfiles/modules/virtchannel_base/memchan.n\fR +tcl::chan::memchan +.TP +\fBfiles/modules/virtchannel_base/null.n\fR +tcl::chan::null +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.TP +\fBfiles/modules/virtchannel_base/random.n\fR +tcl::chan::random +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.TP +\fBfiles/modules/virtchannel_base/string.n\fR +tcl::chan::string +.TP +\fBfiles/modules/virtchannel_base/textwindow.n\fR +tcl::chan::textwindow +.TP +\fBfiles/modules/virtchannel_base/variable.n\fR +tcl::chan::variable +.TP +\fBfiles/modules/virtchannel_base/zero.n\fR +tcl::chan::zero +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.TP +\fBfiles/modules/virtchannel_core/transformcore.n\fR +tcl::transform::core +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +regular expression +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/textutil_split.n\fR +textutil::split +.TP +\fBfiles/modules/textutil/trim.n\fR +textutil::trim +.RE +regular grammar +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.RE +regular languages +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.RE +remote communication +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.RE +remote execution +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.RE +remove +.RS +.TP +\fBfiles/modules/fileutil/multi.n\fR +fileutil::multi +.TP +\fBfiles/modules/fileutil/multiop.n\fR +fileutil::multi::op +.RE +repeating +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +repetition +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.TP +\fBfiles/modules/textutil/repeat.n\fR +textutil::repeat +.RE +report +.RS +.TP +\fBfiles/modules/report/report.n\fR +report +.RE +reshuffle +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +residual graph +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +resolver +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +resource management +.RS +.TP +\fBfiles/modules/try/tcllib_try.n\fR +try +.RE +restore +.RS +.TP +\fBfiles/modules/nns/nns_auto.n\fR +nameserv::auto +.RE +reverse +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +rfc 821 +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +rfc 822 +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/pop3d/pop3d_dbox.n\fR +pop3d::dbox +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +rfc 868 +.RS +.TP +\fBfiles/modules/ntp/ntp_time.n\fR +ntp_time +.RE +rfc 959 +.RS +.TP +\fBfiles/modules/ftp/ftp.n\fR +ftp +.TP +\fBfiles/modules/ftp/ftp_geturl.n\fR +ftp::geturl +.TP +\fBfiles/modules/ftpd/ftpd.n\fR +ftpd +.RE +rfc 977 +.RS +.TP +\fBfiles/modules/nntp/nntp.n\fR +nntp +.RE +rfc 1034 +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +rfc 1035 +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +rfc 1036 +.RS +.TP +\fBfiles/modules/nntp/nntp.n\fR +nntp +.RE +rfc 1320 +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.RE +rfc 1321 +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.RE +rfc 1413 +.RS +.TP +\fBfiles/modules/ident/ident.n\fR +ident +.RE +rfc 1886 +.RS +.TP +\fBfiles/modules/dns/tcllib_dns.n\fR +dns +.RE +rfc 1939 +.RS +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.RE +rfc 2030 +.RS +.TP +\fBfiles/modules/ntp/ntp_time.n\fR +ntp_time +.RE +rfc 2045 +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.RE +rfc 2046 +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.RE +rfc 2049 +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.RE +rfc 2104 +.RS +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.RE +rfc 2141 +.RS +.TP +\fBfiles/modules/uri/urn-scheme.n\fR +uri_urn +.RE +rfc 2251 +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.RE +rfc 2255 +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +rfc 2289 +.RS +.TP +\fBfiles/modules/otp/otp.n\fR +otp +.RE +rfc 2396 +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +rfc 2554 +.RS +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +rfc 2821 +.RS +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +rfc 2849 +.RS +.TP +\fBfiles/modules/ldap/ldapx.n\fR +ldapx +.RE +rfc 3207 +.RS +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.RE +rfc 3513 +.RS +.TP +\fBfiles/modules/dns/tcllib_ip.n\fR +tcllib_ip +.RE +rfc 4511 +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.RE +rfc3501 +.RS +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.RE +rfc3548 +.RS +.TP +\fBfiles/modules/base32/base32.n\fR +base32 +.TP +\fBfiles/modules/base32/base32hex.n\fR +base32::hex +.RE +right outer join +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +RIPEMD +.RS +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.RE +roman numeral +.RS +.TP +\fBfiles/modules/math/roman.n\fR +math::roman +.RE +roots +.RS +.TP +\fBfiles/modules/math/calculus.n\fR +math::calculus +.RE +rot +.RS +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +rot13 +.RS +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.RE +rounding +.RS +.TP +\fBfiles/modules/math/fuzzy.n\fR +math::fuzzy +.RE +rows +.RS +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.RE +rpc +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.RE +rsa +.RS +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.RE +running +.RS +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.RE +s3 +.RS +.TP +\fBfiles/modules/amazon-s3/S3.n\fR +S3 +.RE +SASL +.RS +.TP +\fBfiles/modules/sasl/sasl.n\fR +SASL +.RE +scanl +.RS +.TP +\fBfiles/modules/generator/generator.n\fR +generator +.RE +SCCS +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +secure +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +security +.RS +.TP +\fBfiles/modules/aes/aes.n\fR +aes +.TP +\fBfiles/modules/blowfish/blowfish.n\fR +blowfish +.TP +\fBfiles/modules/crc/cksum.n\fR +cksum +.TP +\fBfiles/modules/crc/crc16.n\fR +crc16 +.TP +\fBfiles/modules/crc/crc32.n\fR +crc32 +.TP +\fBfiles/modules/des/des.n\fR +des +.TP +\fBfiles/modules/md4/md4.n\fR +md4 +.TP +\fBfiles/modules/md5/md5.n\fR +md5 +.TP +\fBfiles/modules/md5crypt/md5crypt.n\fR +md5crypt +.TP +\fBfiles/modules/otp/otp.n\fR +otp +.TP +\fBfiles/modules/pki/pki.n\fR +pki +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.TP +\fBfiles/modules/ripemd/ripemd128.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160.n\fR +ripemd160 +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +seed +.RS +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.RE +selectionbox +.RS +.TP +\fBfiles/modules/javascript/javascript.n\fR +javascript +.RE +semantic markup +.RS +.TP +\fBfiles/modules/doctools/docidx_intro.n\fR +docidx_intro +.TP +\fBfiles/modules/doctools/docidx_lang_cmdref.n\fR +docidx_lang_cmdref +.TP +\fBfiles/modules/doctools/docidx_lang_faq.n\fR +docidx_lang_faq +.TP +\fBfiles/modules/doctools/docidx_lang_intro.n\fR +docidx_lang_intro +.TP +\fBfiles/modules/doctools/docidx_lang_syntax.n\fR +docidx_lang_syntax +.TP +\fBfiles/modules/doctools/docidx_plugin_apiref.n\fR +docidx_plugin_apiref +.TP +\fBfiles/modules/doctools/doctoc_intro.n\fR +doctoc_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_cmdref.n\fR +doctoc_lang_cmdref +.TP +\fBfiles/modules/doctools/doctoc_lang_faq.n\fR +doctoc_lang_faq +.TP +\fBfiles/modules/doctools/doctoc_lang_intro.n\fR +doctoc_lang_intro +.TP +\fBfiles/modules/doctools/doctoc_lang_syntax.n\fR +doctoc_lang_syntax +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools2idx/introduction.n\fR +doctools2idx_introduction +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools/doctools_intro.n\fR +doctools_intro +.TP +\fBfiles/modules/doctools/doctools_lang_cmdref.n\fR +doctools_lang_cmdref +.TP +\fBfiles/modules/doctools/doctools_lang_faq.n\fR +doctools_lang_faq +.TP +\fBfiles/modules/doctools/doctools_lang_intro.n\fR +doctools_lang_intro +.TP +\fBfiles/modules/doctools/doctools_lang_syntax.n\fR +doctools_lang_syntax +.TP +\fBfiles/modules/doctools/doctools_plugin_apiref.n\fR +doctools_plugin_apiref +.RE +send +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.RE +serialization +.RS +.TP +\fBfiles/modules/bee/bee.n\fR +bee +.TP +\fBfiles/modules/doctools2idx/export_docidx.n\fR +doctools::idx::export::docidx +.TP +\fBfiles/modules/doctools2idx/export_html.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools2idx/export_json.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/export_nroff.n\fR +doctools::idx::export::nroff +.TP +\fBfiles/modules/doctools2idx/export_text.n\fR +doctools::idx::export::text +.TP +\fBfiles/modules/doctools2idx/export_wiki.n\fR +doctools::idx::export::wiki +.TP +\fBfiles/modules/doctools2idx/structure.n\fR +doctools::idx::structure +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.TP +\fBfiles/modules/doctools2toc/structure.n\fR +doctools::toc::structure +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.RE +server +.RS +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.TP +\fBfiles/modules/nns/nns_common.n\fR +nameserv::common +.TP +\fBfiles/modules/nns/nns_server.n\fR +nameserv::server +.TP +\fBfiles/modules/nns/nns_intro.n\fR +nns_intro +.TP +\fBfiles/apps/nnsd.n\fR +nnsd +.RE +service +.RS +.TP +\fBfiles/modules/log/logger.n\fR +logger +.RE +services +.RS +.TP +\fBfiles/modules/ftpd/ftpd.n\fR +ftpd +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +set +.RS +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +sha1 +.RS +.TP +\fBfiles/modules/sha1/sha1.n\fR +sha1 +.RE +sha256 +.RS +.TP +\fBfiles/modules/sha1/sha256.n\fR +sha256 +.RE +shortest path +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +shuffle +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +simulated annealing +.RS +.TP +\fBfiles/modules/simulation/annealing.n\fR +simulation::annealing +.RE +simulation +.RS +.TP +\fBfiles/modules/simulation/simulation_random.n\fR +simulation::random +.RE +singleton +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +size limit +.RS +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.RE +skiplist +.RS +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/skiplist.n\fR +struct::skiplist +.RE +slippy +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.RE +smtp +.RS +.TP +\fBfiles/modules/mime/mime.n\fR +mime +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +smtpd +.RS +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +Snit +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.RE +snit +.RS +.TP +\fBfiles/modules/interp/deleg_method.n\fR +deleg_method +.TP +\fBfiles/modules/interp/tcllib_interp.n\fR +interp +.RE +SNTP +.RS +.TP +\fBfiles/modules/ntp/ntp_time.n\fR +ntp_time +.RE +socket +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/comm/comm_wire.n\fR +comm_wire +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +soundex +.RS +.TP +\fBfiles/modules/soundex/soundex.n\fR +soundex +.RE +source +.RS +.TP +\fBfiles/modules/docstrip/docstrip.n\fR +docstrip +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.TP +\fBfiles/apps/tcldocstrip.n\fR +tcldocstrip +.RE +spacing +.RS +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.RE +spatial interpolation +.RS +.TP +\fBfiles/modules/math/interpolate.n\fR +math::interpolate +.RE +special functions +.RS +.TP +\fBfiles/modules/math/special.n\fR +math::special +.RE +specification +.RS +.TP +\fBfiles/modules/bench/bench_lang_spec.n\fR +bench_lang_spec +.RE +speed +.RS +.TP +\fBfiles/modules/profiler/profiler.n\fR +profiler +.RE +split +.RS +.TP +\fBfiles/modules/textutil/textutil_split.n\fR +textutil::split +.RE +squared graph +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +ssl +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +stack +.RS +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.RE +standard io +.RS +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.RE +state +.RS +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +state (de)serialization +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +statistical distribution +.RS +.TP +\fBfiles/modules/simulation/simulation_random.n\fR +simulation::random +.RE +statistics +.RS +.TP +\fBfiles/modules/counter/counter.n\fR +counter +.TP +\fBfiles/modules/math/math.n\fR +math +.TP +\fBfiles/modules/math/statistics.n\fR +math::statistics +.RE +stdin +.RS +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.RE +stdout +.RS +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.RE +stochastic modelling +.RS +.TP +\fBfiles/modules/simulation/montecarlo.n\fR +simulation::montecarlo +.RE +stream cipher +.RS +.TP +\fBfiles/modules/rc4/rc4.n\fR +rc4 +.RE +stream copy +.RS +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.RE +string +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.TP +\fBfiles/modules/textutil/expander.n\fR +textutil::expander +.TP +\fBfiles/modules/textutil/repeat.n\fR +textutil::repeat +.TP +\fBfiles/modules/textutil/textutil_split.n\fR +textutil::split +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.TP +\fBfiles/modules/textutil/tabify.n\fR +textutil::tabify +.TP +\fBfiles/modules/textutil/trim.n\fR +textutil::trim +.RE +stringprep +.RS +.TP +\fBfiles/modules/stringprep/stringprep.n\fR +stringprep +.TP +\fBfiles/modules/stringprep/stringprep_data.n\fR +stringprep::data +.TP +\fBfiles/modules/stringprep/unicode_data.n\fR +unicode::data +.RE +strongly connected component +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +struct +.RS +.TP +\fBfiles/modules/struct/pool.n\fR +struct::pool +.TP +\fBfiles/modules/struct/record.n\fR +struct::record +.RE +structure +.RS +.TP +\fBfiles/modules/control/control.n\fR +control +.RE +structured queries +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +style +.RS +.TP +\fBfiles/modules/doctools2base/html_cssdefaults.n\fR +doctools::html::cssdefaults +.RE +subcommand +.RS +.TP +\fBfiles/modules/tepam/tepam_introduction.n\fR +tepam +.TP +\fBfiles/modules/tepam/tepam_procedure.n\fR +tepam::procedure +.RE +subgraph +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +subject +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.RE +submitbutton +.RS +.TP +\fBfiles/modules/javascript/javascript.n\fR +javascript +.RE +subscriber +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.RE +subsequence +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +subst +.RS +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.RE +sum +.RS +.TP +\fBfiles/modules/crc/sum.n\fR +sum +.RE +swapping +.RS +.TP +\fBfiles/modules/struct/struct_list.n\fR +struct::list +.RE +symmetric difference +.RS +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +synchronous +.RS +.TP +\fBfiles/modules/cache/async.n\fR +cache::async +.RE +syntax tree +.RS +.TP +\fBfiles/modules/grammar_me/me_util.n\fR +grammar::me::util +.RE +table +.RS +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/html/html.n\fR +html +.TP +\fBfiles/modules/report/report.n\fR +report +.RE +table of contents +.RS +.TP +\fBfiles/modules/doctools/doctoc_intro.n\fR +doctoc_intro +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools2toc/introduction.n\fR +doctools2toc_introduction +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.RE +tabstops +.RS +.TP +\fBfiles/modules/textutil/tabify.n\fR +textutil::tabify +.RE +tallying +.RS +.TP +\fBfiles/modules/counter/counter.n\fR +counter +.RE +tape archive +.RS +.TP +\fBfiles/modules/tar/tar.n\fR +tar +.RE +tar +.RS +.TP +\fBfiles/modules/tar/tar.n\fR +tar +.RE +tcl +.RS +.TP +\fBfiles/modules/math/bigfloat.n\fR +math::bigfloat +.TP +\fBfiles/modules/math/bignum.n\fR +math::bignum +.TP +\fBfiles/modules/math/decimal.n\fR +math::decimal +.RE +Tcl module +.RS +.TP +\fBfiles/modules/docstrip/docstrip_util.n\fR +docstrip_util +.RE +Tcl syntax +.RS +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.RE +tcler's wiki +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.RE +tcllib +.RS +.TP +\fBfiles/modules/csv/csv.n\fR +csv +.RE +TclOO +.RS +.TP +\fBfiles/modules/ooutil/ooutil.n\fR +oo::util +.RE +TCLPARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.RE +TDPL +.RS +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +temp file +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.RE +template processing +.RS +.TP +\fBfiles/modules/textutil/expander.n\fR +textutil::expander +.RE +terminal +.RS +.TP +\fBfiles/modules/term/term.n\fR +term +.TP +\fBfiles/modules/term/ansi_code.n\fR +term::ansi::code +.TP +\fBfiles/modules/term/ansi_cattr.n\fR +term::ansi::code::attr +.TP +\fBfiles/modules/term/ansi_cctrl.n\fR +term::ansi::code::ctrl +.TP +\fBfiles/modules/term/ansi_cmacros.n\fR +term::ansi::code::macros +.TP +\fBfiles/modules/term/ansi_ctrlu.n\fR +term::ansi::ctrl::unix +.TP +\fBfiles/modules/term/ansi_send.n\fR +term::ansi::send +.TP +\fBfiles/modules/term/imenu.n\fR +term::interact::menu +.TP +\fBfiles/modules/term/ipager.n\fR +term::interact::pager +.TP +\fBfiles/modules/term/receive.n\fR +term::receive +.TP +\fBfiles/modules/term/term_bind.n\fR +term::receive::bind +.TP +\fBfiles/modules/term/term_send.n\fR +term::send +.RE +test +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.RE +testing +.RS +.TP +\fBfiles/modules/bench/bench.n\fR +bench +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wcsv.n\fR +bench::out::csv +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.TP +\fBfiles/modules/bench/bench_intro.n\fR +bench_intro +.TP +\fBfiles/modules/bench/bench_lang_intro.n\fR +bench_lang_intro +.TP +\fBfiles/modules/bench/bench_lang_spec.n\fR +bench_lang_spec +.RE +TeX +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +text +.RS +.TP +\fBfiles/modules/bench/bench_read.n\fR +bench::in +.TP +\fBfiles/modules/bench/bench_wtext.n\fR +bench::out::text +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.RE +text comparison +.RS +.TP +\fBfiles/modules/soundex/soundex.n\fR +soundex +.RE +text conversion +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +text differences +.RS +.TP +\fBfiles/modules/rcs/rcs.n\fR +rcs +.RE +text display +.RS +.TP +\fBfiles/modules/term/imenu.n\fR +term::interact::menu +.TP +\fBfiles/modules/term/ipager.n\fR +term::interact::pager +.RE +text expansion +.RS +.TP +\fBfiles/modules/textutil/expander.n\fR +textutil::expander +.RE +text likeness +.RS +.TP +\fBfiles/modules/soundex/soundex.n\fR +soundex +.RE +text processing +.RS +.TP +\fBfiles/modules/bibtex/bibtex.n\fR +bibtex +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/apps/page.n\fR +page +.TP +\fBfiles/modules/page/page_intro.n\fR +page_intro +.TP +\fBfiles/modules/page/page_pluginmgr.n\fR +page_pluginmgr +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/page/page_util_quote.n\fR +page_util_quote +.TP +\fBfiles/modules/yaml/yaml.n\fR +yaml +.RE +text widget +.RS +.TP +\fBfiles/modules/virtchannel_base/textwindow.n\fR +tcl::chan::textwindow +.RE +threads +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +thumbnail +.RS +.TP +\fBfiles/modules/jpeg/jpeg.n\fR +jpeg +.RE +tie +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +tif +.RS +.TP +\fBfiles/modules/tiff/tiff.n\fR +tiff +.RE +tiff +.RS +.TP +\fBfiles/modules/exif/exif.n\fR +exif +.TP +\fBfiles/modules/tiff/tiff.n\fR +tiff +.RE +tile +.RS +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.RE +time +.RS +.TP +\fBfiles/modules/ntp/ntp_time.n\fR +ntp_time +.RE +timestamp +.RS +.TP +\fBfiles/modules/png/png.n\fR +png +.RE +tip 219 +.RS +.TP +\fBfiles/modules/virtchannel_base/cat.n\fR +tcl::chan::cat +.TP +\fBfiles/modules/virtchannel_core/core.n\fR +tcl::chan::core +.TP +\fBfiles/modules/virtchannel_core/events.n\fR +tcl::chan::events +.TP +\fBfiles/modules/virtchannel_base/facade.n\fR +tcl::chan::facade +.TP +\fBfiles/modules/virtchannel_base/fifo.n\fR +tcl::chan::fifo +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.TP +\fBfiles/modules/virtchannel_base/memchan.n\fR +tcl::chan::memchan +.TP +\fBfiles/modules/virtchannel_base/null.n\fR +tcl::chan::null +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.TP +\fBfiles/modules/virtchannel_base/random.n\fR +tcl::chan::random +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.TP +\fBfiles/modules/virtchannel_base/string.n\fR +tcl::chan::string +.TP +\fBfiles/modules/virtchannel_base/textwindow.n\fR +tcl::chan::textwindow +.TP +\fBfiles/modules/virtchannel_base/variable.n\fR +tcl::chan::variable +.TP +\fBfiles/modules/virtchannel_base/zero.n\fR +tcl::chan::zero +.TP +\fBfiles/modules/virtchannel_core/transformcore.n\fR +tcl::transform::core +.RE +tip 230 +.RS +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +tip 234 +.RS +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +tip 317 +.RS +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.RE +Tk +.RS +.TP +\fBfiles/modules/virtchannel_base/textwindow.n\fR +tcl::chan::textwindow +.RE +tls +.RS +.TP +\fBfiles/modules/comm/comm.n\fR +comm +.TP +\fBfiles/modules/imap4/imap4.n\fR +imap4 +.TP +\fBfiles/modules/pop3/pop3.n\fR +pop3 +.TP +\fBfiles/modules/pop3d/pop3d.n\fR +pop3d +.TP +\fBfiles/modules/mime/smtp.n\fR +smtp +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +TMML +.RS +.TP +\fBfiles/modules/doctools/doctools.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/apps/dtplite.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand.n\fR +mpexpand +.RE +toc +.RS +.TP +\fBfiles/modules/doctools/doctoc_intro.n\fR +doctoc_intro +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export_doctoc.n\fR +doctools::toc::export::doctoc +.TP +\fBfiles/modules/doctools2toc/export_html.n\fR +doctools::toc::export::html +.TP +\fBfiles/modules/doctools2toc/export_json.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/export_nroff.n\fR +doctools::toc::export::nroff +.TP +\fBfiles/modules/doctools2toc/export_text.n\fR +doctools::toc::export::text +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.TP +\fBfiles/modules/doctools2toc/import_doctoc.n\fR +doctools::toc::import::doctoc +.TP +\fBfiles/modules/doctools2toc/import_json.n\fR +doctools::toc::import::json +.RE +toc formatter +.RS +.TP +\fBfiles/modules/doctools/doctoc_plugin_apiref.n\fR +doctoc_plugin_apiref +.RE +top-down parsing languages +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +torrent +.RS +.TP +\fBfiles/modules/bee/bee.n\fR +bee +.RE +touch +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.RE +TPDL +.RS +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.RE +transducer +.RS +.TP +\fBfiles/modules/grammar_aycock/aycock.n\fR +grammar::aycock +.TP +\fBfiles/modules/grammar_fa/fa.n\fR +grammar::fa +.TP +\fBfiles/modules/grammar_fa/dacceptor.n\fR +grammar::fa::dacceptor +.TP +\fBfiles/modules/grammar_fa/dexec.n\fR +grammar::fa::dexec +.TP +\fBfiles/modules/grammar_fa/faop.n\fR +grammar::fa::op +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_json_language.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_to_api.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parser_api.n\fR +pt_parser_api +.RE +transfer +.RS +.TP +\fBfiles/modules/transfer/connect.n\fR +transfer::connect +.TP +\fBfiles/modules/transfer/copyops.n\fR +transfer::copy +.TP +\fBfiles/modules/transfer/tqueue.n\fR +transfer::copy::queue +.TP +\fBfiles/modules/transfer/ddest.n\fR +transfer::data::destination +.TP +\fBfiles/modules/transfer/dsource.n\fR +transfer::data::source +.TP +\fBfiles/modules/transfer/receiver.n\fR +transfer::receiver +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +transformation +.RS +.TP +\fBfiles/modules/page/page_util_peg.n\fR +page_util_peg +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +transmitter +.RS +.TP +\fBfiles/modules/transfer/transmitter.n\fR +transfer::transmitter +.RE +travelling salesman +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +traversal +.RS +.TP +\fBfiles/modules/fileutil/traverse.n\fR +fileutil_traverse +.RE +tree +.RS +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.TP +\fBfiles/modules/grammar_me/me_util.n\fR +grammar::me::util +.TP +\fBfiles/modules/htmlparse/htmlparse.n\fR +htmlparse +.TP +\fBfiles/modules/struct/queue.n\fR +struct::queue +.TP +\fBfiles/modules/struct/stack.n\fR +struct::stack +.TP +\fBfiles/modules/struct/struct_tree.n\fR +struct::tree +.TP +\fBfiles/modules/struct/struct_tree1.n\fR +struct::tree_v1 +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +tree query language +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +tree walking +.RS +.TP +\fBfiles/modules/page/page_util_flow.n\fR +page_util_flow +.TP +\fBfiles/modules/page/page_util_norm_lemon.n\fR +page_util_norm_lemon +.TP +\fBfiles/modules/page/page_util_norm_peg.n\fR +page_util_norm_peg +.RE +TreeQL +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +trimming +.RS +.TP +\fBfiles/modules/textutil/textutil.n\fR +textutil +.TP +\fBfiles/modules/textutil/trim.n\fR +textutil::trim +.RE +type +.RS +.TP +\fBfiles/modules/fileutil/fileutil.n\fR +fileutil +.TP +\fBfiles/modules/fumagic/cfront.n\fR +fileutil::magic::cfront +.TP +\fBfiles/modules/fumagic/cgen.n\fR +fileutil::magic::cgen +.TP +\fBfiles/modules/fumagic/filetypes.n\fR +fileutil::magic::filetype +.TP +\fBfiles/modules/fumagic/mimetypes.n\fR +fileutil::magic::mimetype +.TP +\fBfiles/modules/fumagic/rtcore.n\fR +fileutil::magic::rt +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.RE +uevent +.RS +.TP +\fBfiles/modules/hook/hook.n\fR +hook +.RE +unbind +.RS +.TP +\fBfiles/modules/uev/uevent.n\fR +uevent +.RE +uncapitalize +.RS +.TP +\fBfiles/modules/textutil/textutil_string.n\fR +textutil::string +.RE +undenting +.RS +.TP +\fBfiles/modules/textutil/adjust.n\fR +textutil::adjust +.RE +unicode +.RS +.TP +\fBfiles/modules/stringprep/stringprep.n\fR +stringprep +.TP +\fBfiles/modules/stringprep/stringprep_data.n\fR +stringprep::data +.TP +\fBfiles/modules/stringprep/unicode.n\fR +unicode +.TP +\fBfiles/modules/stringprep/unicode_data.n\fR +unicode::data +.RE +union +.RS +.TP +\fBfiles/modules/struct/disjointset.n\fR +struct::disjointset +.TP +\fBfiles/modules/struct/struct_set.n\fR +struct::set +.RE +unit +.RS +.TP +\fBfiles/modules/units/units.n\fR +units +.RE +unknown hooking +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +untie +.RS +.TP +\fBfiles/modules/tie/tie.n\fR +tie +.TP +\fBfiles/modules/tie/tie_std.n\fR +tie +.RE +update +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.RE +uri +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.TP +\fBfiles/modules/uri/urn-scheme.n\fR +uri_urn +.RE +url +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/import.n\fR +doctools::idx::import +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/import.n\fR +doctools::toc::import +.TP +\fBfiles/modules/map/map_geocode_nominatim.n\fR +map::geocode::nominatim +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.TP +\fBfiles/modules/uri/urn-scheme.n\fR +uri_urn +.RE +urn +.RS +.TP +\fBfiles/modules/uri/urn-scheme.n\fR +uri_urn +.RE +utilities +.RS +.TP +\fBfiles/modules/namespacex/namespacex.n\fR +namespacex +.RE +uuencode +.RS +.TP +\fBfiles/modules/base64/uuencode.n\fR +uuencode +.RE +UUID +.RS +.TP +\fBfiles/modules/uuid/uuid.n\fR +uuid +.RE +vectors +.RS +.TP +\fBfiles/modules/math/linalg.n\fR +math::linearalgebra +.RE +vertex +.RS +.TP +\fBfiles/modules/struct/graph.n\fR +struct::graph +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +vertex cover +.RS +.TP +\fBfiles/modules/struct/graphops.n\fR +struct::graph::op +.RE +virtual channel +.RS +.TP +\fBfiles/modules/virtchannel_base/cat.n\fR +tcl::chan::cat +.TP +\fBfiles/modules/virtchannel_core/core.n\fR +tcl::chan::core +.TP +\fBfiles/modules/virtchannel_core/events.n\fR +tcl::chan::events +.TP +\fBfiles/modules/virtchannel_base/facade.n\fR +tcl::chan::facade +.TP +\fBfiles/modules/virtchannel_base/fifo.n\fR +tcl::chan::fifo +.TP +\fBfiles/modules/virtchannel_base/fifo2.n\fR +tcl::chan::fifo2 +.TP +\fBfiles/modules/virtchannel_base/halfpipe.n\fR +tcl::chan::halfpipe +.TP +\fBfiles/modules/virtchannel_base/memchan.n\fR +tcl::chan::memchan +.TP +\fBfiles/modules/virtchannel_base/null.n\fR +tcl::chan::null +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.TP +\fBfiles/modules/virtchannel_base/random.n\fR +tcl::chan::random +.TP +\fBfiles/modules/virtchannel_base/randseed.n\fR +tcl::chan::randseed +.TP +\fBfiles/modules/virtchannel_base/std.n\fR +tcl::chan::std +.TP +\fBfiles/modules/virtchannel_base/string.n\fR +tcl::chan::string +.TP +\fBfiles/modules/virtchannel_base/textwindow.n\fR +tcl::chan::textwindow +.TP +\fBfiles/modules/virtchannel_base/variable.n\fR +tcl::chan::variable +.TP +\fBfiles/modules/virtchannel_base/zero.n\fR +tcl::chan::zero +.TP +\fBfiles/modules/virtchannel_transform/adler32.n\fR +tcl::transform::adler32 +.TP +\fBfiles/modules/virtchannel_transform/base64.n\fR +tcl::transform::base64 +.TP +\fBfiles/modules/virtchannel_core/transformcore.n\fR +tcl::transform::core +.TP +\fBfiles/modules/virtchannel_transform/counter.n\fR +tcl::transform::counter +.TP +\fBfiles/modules/virtchannel_transform/crc32.n\fR +tcl::transform::crc32 +.TP +\fBfiles/modules/virtchannel_transform/hex.n\fR +tcl::transform::hex +.TP +\fBfiles/modules/virtchannel_transform/identity.n\fR +tcl::transform::identity +.TP +\fBfiles/modules/virtchannel_transform/limitsize.n\fR +tcl::transform::limitsize +.TP +\fBfiles/modules/virtchannel_transform/observe.n\fR +tcl::transform::observe +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.TP +\fBfiles/modules/virtchannel_transform/rot.n\fR +tcl::transform::rot +.TP +\fBfiles/modules/virtchannel_transform/spacer.n\fR +tcl::transform::spacer +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +virtual machine +.RS +.TP +\fBfiles/modules/grammar_me/me_cpu.n\fR +grammar::me::cpu +.TP +\fBfiles/modules/grammar_me/me_cpucore.n\fR +grammar::me::cpu::core +.TP +\fBfiles/modules/grammar_me/gasm.n\fR +grammar::me::cpu::gasm +.TP +\fBfiles/modules/grammar_me/me_tcl.n\fR +grammar::me::tcl +.TP +\fBfiles/modules/grammar_me/me_intro.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_me/me_vm.n\fR +grammar::me_vm +.TP +\fBfiles/modules/grammar_peg/peg_interp.n\fR +grammar::peg::interp +.TP +\fBfiles/modules/pt/pt_param.n\fR +pt::param +.RE +vwait +.RS +.TP +\fBfiles/modules/coroutine/coroutine.n\fR +coroutine +.TP +\fBfiles/modules/coroutine/coro_auto.n\fR +coroutine::auto +.TP +\fBfiles/modules/smtpd/smtpd.n\fR +smtpd +.RE +wais +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +widget +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +widget adaptors +.RS +.TP +\fBfiles/modules/snit/snit.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq.n\fR +snitfaq +.RE +wiki +.RS +.TP +\fBfiles/modules/doctools2idx/container.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/export.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/export_wiki.n\fR +doctools::idx::export::wiki +.TP +\fBfiles/modules/doctools2toc/container.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools/doctoc.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/export.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/export_wiki.n\fR +doctools::toc::export::wiki +.RE +word +.RS +.TP +\fBfiles/modules/doctools2base/tcl_parse.n\fR +doctools::tcl::parse +.TP +\fBfiles/modules/wip/wip.n\fR +wip +.RE +www +.RS +.TP +\fBfiles/modules/uri/uri.n\fR +uri +.RE +x.208 +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +x.209 +.RS +.TP +\fBfiles/modules/asn/asn.n\fR +asn +.RE +x.500 +.RS +.TP +\fBfiles/modules/ldap/ldap.n\fR +ldap +.RE +xml +.RS +.TP +\fBfiles/modules/amazon-s3/xsxp.n\fR +xsxp +.RE +xor +.RS +.TP +\fBfiles/modules/virtchannel_transform/otp.n\fR +tcl::transform::otp +.RE +XPath +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +XSLT +.RS +.TP +\fBfiles/modules/treeql/treeql.n\fR +treeql +.RE +yaml +.RS +.TP +\fBfiles/modules/yaml/huddle.n\fR +huddle +.TP +\fBfiles/modules/yaml/yaml.n\fR +yaml +.RE +ydecode +.RS +.TP +\fBfiles/modules/base64/yencode.n\fR +yencode +.RE +yEnc +.RS +.TP +\fBfiles/modules/base64/yencode.n\fR +yencode +.RE +yencode +.RS +.TP +\fBfiles/modules/base64/yencode.n\fR +yencode +.RE +zero +.RS +.TP +\fBfiles/modules/virtchannel_base/nullzero.n\fR +tcl::chan::nullzero +.TP +\fBfiles/modules/virtchannel_base/zero.n\fR +tcl::chan::zero +.RE +zlib +.RS +.TP +\fBfiles/modules/virtchannel_transform/zlib.n\fR +tcl::transform::zlib +.RE +zoom +.RS +.TP +\fBfiles/modules/map/map_slippy.n\fR +map::slippy +.TP +\fBfiles/modules/map/map_slippy_cache.n\fR +map::slippy::cache +.TP +\fBfiles/modules/map/map_slippy_fetcher.n\fR +map::slippy::fetcher +.RE ADDED embedded/man/toc.n Index: embedded/man/toc.n ================================================================== --- /dev/null +++ embedded/man/toc.n @@ -0,0 +1,1371 @@ +'\" +'\" Generated by tcllib/doctools/toc with format 'nroff' +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "Table Of Contents" n +.BS +.SH CONTENTS +tcllib +.RS +.TP +\fBaes\fR +\fIfiles/modules/aes/aes.n\fR: Implementation of the AES block cipher +.TP +\fBascii85\fR +\fIfiles/modules/base64/ascii85.n\fR: ascii85-encode/decode binary data +.TP +\fBasn\fR +\fIfiles/modules/asn/asn.n\fR: ASN.1 BER encoder/decoder +.TP +\fBautoproxy\fR +\fIfiles/modules/http/autoproxy.n\fR: Automatic HTTP proxy usage and authentication +.TP +\fBbase32\fR +\fIfiles/modules/base32/base32.n\fR: base32 standard encoding +.TP +\fBbase32::core\fR +\fIfiles/modules/base32/base32core.n\fR: Expanding basic base32 maps +.TP +\fBbase32::hex\fR +\fIfiles/modules/base32/base32hex.n\fR: base32 extended hex encoding +.TP +\fBbase64\fR +\fIfiles/modules/base64/base64.n\fR: base64-encode/decode binary data +.TP +\fBbee\fR +\fIfiles/modules/bee/bee.n\fR: BitTorrent Serialization Format Encoder/Decoder +.TP +\fBbench\fR +\fIfiles/modules/bench/bench.n\fR: bench - Processing benchmark suites +.TP +\fBbench::in\fR +\fIfiles/modules/bench/bench_read.n\fR: bench::in - Reading benchmark results +.TP +\fBbench::out::csv\fR +\fIfiles/modules/bench/bench_wcsv.n\fR: bench::out::csv - Formatting benchmark results as CSV +.TP +\fBbench::out::text\fR +\fIfiles/modules/bench/bench_wtext.n\fR: bench::out::text - Formatting benchmark results as human readable text +.TP +\fBbench_intro\fR +\fIfiles/modules/bench/bench_intro.n\fR: bench introduction +.TP +\fBbench_lang_intro\fR +\fIfiles/modules/bench/bench_lang_intro.n\fR: bench language introduction +.TP +\fBbench_lang_spec\fR +\fIfiles/modules/bench/bench_lang_spec.n\fR: bench language specification +.TP +\fBbibtex\fR +\fIfiles/modules/bibtex/bibtex.n\fR: Parse bibtex files +.TP +\fBblowfish\fR +\fIfiles/modules/blowfish/blowfish.n\fR: Implementation of the Blowfish block cipher +.TP +\fBcache::async\fR +\fIfiles/modules/cache/async.n\fR: Asynchronous in-memory cache +.TP +\fBcksum\fR +\fIfiles/modules/crc/cksum.n\fR: Calculate a cksum(1) compatible checksum +.TP +\fBclock_iso8601\fR +\fIfiles/modules/clock/iso8601.n\fR: Parsing ISO 8601 dates/times +.TP +\fBclock_rfc2822\fR +\fIfiles/modules/clock/rfc2822.n\fR: Parsing ISO 8601 dates/times +.TP +\fBcmdline\fR +\fIfiles/modules/cmdline/cmdline.n\fR: Procedures to process command lines and options. +.TP +\fBcomm\fR +\fIfiles/modules/comm/comm.n\fR: A remote communication facility for Tcl (8.3 and later) +.TP +\fBcomm_wire\fR +\fIfiles/modules/comm/comm_wire.n\fR: The comm wire protocol +.TP +\fBcontrol\fR +\fIfiles/modules/control/control.n\fR: Procedures for control flow structures. +.TP +\fBcoroutine\fR +\fIfiles/modules/coroutine/coroutine.n\fR: Coroutine based event and IO handling +.TP +\fBcoroutine::auto\fR +\fIfiles/modules/coroutine/coro_auto.n\fR: Automatic event and IO coroutine awareness +.TP +\fBcounter\fR +\fIfiles/modules/counter/counter.n\fR: Procedures for counters and histograms +.TP +\fBcrc16\fR +\fIfiles/modules/crc/crc16.n\fR: Perform a 16bit Cyclic Redundancy Check +.TP +\fBcrc32\fR +\fIfiles/modules/crc/crc32.n\fR: Perform a 32bit Cyclic Redundancy Check +.TP +\fBcsv\fR +\fIfiles/modules/csv/csv.n\fR: Procedures to handle CSV data. +.TP +\fBdeleg_method\fR +\fIfiles/modules/interp/deleg_method.n\fR: Creation of comm delegates (snit methods) +.TP +\fBdeleg_proc\fR +\fIfiles/modules/interp/deleg_proc.n\fR: Creation of comm delegates (procedures) +.TP +\fBdes\fR +\fIfiles/modules/des/des.n\fR: Implementation of the DES and triple-DES ciphers +.TP +\fBdns\fR +\fIfiles/modules/dns/tcllib_dns.n\fR: Tcl Domain Name Service Client +.TP +\fBdocidx_intro\fR +\fIfiles/modules/doctools/docidx_intro.n\fR: docidx introduction +.TP +\fBdocidx_lang_cmdref\fR +\fIfiles/modules/doctools/docidx_lang_cmdref.n\fR: docidx language command reference +.TP +\fBdocidx_lang_faq\fR +\fIfiles/modules/doctools/docidx_lang_faq.n\fR: docidx language faq +.TP +\fBdocidx_lang_intro\fR +\fIfiles/modules/doctools/docidx_lang_intro.n\fR: docidx language introduction +.TP +\fBdocidx_lang_syntax\fR +\fIfiles/modules/doctools/docidx_lang_syntax.n\fR: docidx language syntax +.TP +\fBdocidx_plugin_apiref\fR +\fIfiles/modules/doctools/docidx_plugin_apiref.n\fR: docidx plugin API reference +.TP +\fBdocstrip\fR +\fIfiles/modules/docstrip/docstrip.n\fR: Docstrip style source code extraction +.TP +\fBdocstrip_util\fR +\fIfiles/modules/docstrip/docstrip_util.n\fR: Docstrip-related utilities +.TP +\fBdoctoc_intro\fR +\fIfiles/modules/doctools/doctoc_intro.n\fR: doctoc introduction +.TP +\fBdoctoc_lang_cmdref\fR +\fIfiles/modules/doctools/doctoc_lang_cmdref.n\fR: doctoc language command reference +.TP +\fBdoctoc_lang_faq\fR +\fIfiles/modules/doctools/doctoc_lang_faq.n\fR: doctoc language faq +.TP +\fBdoctoc_lang_intro\fR +\fIfiles/modules/doctools/doctoc_lang_intro.n\fR: doctoc language introduction +.TP +\fBdoctoc_lang_syntax\fR +\fIfiles/modules/doctools/doctoc_lang_syntax.n\fR: doctoc language syntax +.TP +\fBdoctoc_plugin_apiref\fR +\fIfiles/modules/doctools/doctoc_plugin_apiref.n\fR: doctoc plugin API reference +.TP +\fBdoctools\fR +\fIfiles/modules/doctools/doctools.n\fR: doctools - Processing documents +.TP +\fBdoctools2idx_introduction\fR +\fIfiles/modules/doctools2idx/introduction.n\fR: DocTools - Keyword indices +.TP +\fBdoctools2toc_introduction\fR +\fIfiles/modules/doctools2toc/introduction.n\fR: DocTools - Tables of Contents +.TP +\fBdoctools::changelog\fR +\fIfiles/modules/doctools/changelog.n\fR: Processing text in Emacs ChangeLog format +.TP +\fBdoctools::cvs\fR +\fIfiles/modules/doctools/cvs.n\fR: Processing text in 'cvs log' format +.TP +\fBdoctools::html::cssdefaults\fR +\fIfiles/modules/doctools2base/html_cssdefaults.n\fR: Default CSS style for HTML export plugins +.TP +\fBdoctools::idx\fR +\fIfiles/modules/doctools2idx/container.n\fR: Holding keyword indices +.TP +\fBdoctools::idx\fR +\fIfiles/modules/doctools/docidx.n\fR: docidx - Processing indices +.TP +\fBdoctools::idx::export\fR +\fIfiles/modules/doctools2idx/export.n\fR: Exporting keyword indices +.TP +\fBdoctools::idx::export::docidx\fR +\fIfiles/modules/doctools2idx/export_docidx.n\fR: docidx export plugin +.TP +\fBdoctools::idx::export::html\fR +\fIfiles/modules/doctools2idx/export_html.n\fR: HTML export plugin +.TP +\fBdoctools::idx::export::json\fR +\fIfiles/modules/doctools2idx/export_json.n\fR: JSON export plugin +.TP +\fBdoctools::idx::export::nroff\fR +\fIfiles/modules/doctools2idx/export_nroff.n\fR: nroff export plugin +.TP +\fBdoctools::idx::export::text\fR +\fIfiles/modules/doctools2idx/export_text.n\fR: plain text export plugin +.TP +\fBdoctools::idx::export::wiki\fR +\fIfiles/modules/doctools2idx/export_wiki.n\fR: wiki export plugin +.TP +\fBdoctools::idx::import\fR +\fIfiles/modules/doctools2idx/import.n\fR: Importing keyword indices +.TP +\fBdoctools::idx::import::docidx\fR +\fIfiles/modules/doctools2idx/import_docidx.n\fR: docidx import plugin +.TP +\fBdoctools::idx::import::json\fR +\fIfiles/modules/doctools2idx/import_json.n\fR: JSON import plugin +.TP +\fBdoctools::idx::parse\fR +\fIfiles/modules/doctools2idx/parse.n\fR: Parsing text in docidx format +.TP +\fBdoctools::idx::structure\fR +\fIfiles/modules/doctools2idx/structure.n\fR: Docidx serialization utilities +.TP +\fBdoctools::msgcat\fR +\fIfiles/modules/doctools2base/tcllib_msgcat.n\fR: Message catalog management for the various document parsers +.TP +\fBdoctools::msgcat::idx::c\fR +\fIfiles/modules/doctools2idx/msgcat_c.n\fR: Message catalog for the docidx parser (C) +.TP +\fBdoctools::msgcat::idx::de\fR +\fIfiles/modules/doctools2idx/msgcat_de.n\fR: Message catalog for the docidx parser (DE) +.TP +\fBdoctools::msgcat::idx::en\fR +\fIfiles/modules/doctools2idx/msgcat_en.n\fR: Message catalog for the docidx parser (EN) +.TP +\fBdoctools::msgcat::idx::fr\fR +\fIfiles/modules/doctools2idx/msgcat_fr.n\fR: Message catalog for the docidx parser (FR) +.TP +\fBdoctools::msgcat::toc::c\fR +\fIfiles/modules/doctools2toc/msgcat_c.n\fR: Message catalog for the doctoc parser (C) +.TP +\fBdoctools::msgcat::toc::de\fR +\fIfiles/modules/doctools2toc/msgcat_de.n\fR: Message catalog for the doctoc parser (DE) +.TP +\fBdoctools::msgcat::toc::en\fR +\fIfiles/modules/doctools2toc/msgcat_en.n\fR: Message catalog for the doctoc parser (EN) +.TP +\fBdoctools::msgcat::toc::fr\fR +\fIfiles/modules/doctools2toc/msgcat_fr.n\fR: Message catalog for the doctoc parser (FR) +.TP +\fBdoctools::nroff::man_macros\fR +\fIfiles/modules/doctools2base/nroff_manmacros.n\fR: Default CSS style for NROFF export plugins +.TP +\fBdoctools::tcl::parse\fR +\fIfiles/modules/doctools2base/tcl_parse.n\fR: Processing text in 'subst -novariables' format +.TP +\fBdoctools::toc\fR +\fIfiles/modules/doctools2toc/container.n\fR: Holding tables of contents +.TP +\fBdoctools::toc\fR +\fIfiles/modules/doctools/doctoc.n\fR: doctoc - Processing tables of contents +.TP +\fBdoctools::toc::export\fR +\fIfiles/modules/doctools2toc/export.n\fR: Exporting tables of contents +.TP +\fBdoctools::toc::export::doctoc\fR +\fIfiles/modules/doctools2toc/export_doctoc.n\fR: doctoc export plugin +.TP +\fBdoctools::toc::export::html\fR +\fIfiles/modules/doctools2toc/export_html.n\fR: HTML export plugin +.TP +\fBdoctools::toc::export::json\fR +\fIfiles/modules/doctools2toc/export_json.n\fR: JSON export plugin +.TP +\fBdoctools::toc::export::nroff\fR +\fIfiles/modules/doctools2toc/export_nroff.n\fR: nroff export plugin +.TP +\fBdoctools::toc::export::text\fR +\fIfiles/modules/doctools2toc/export_text.n\fR: plain text export plugin +.TP +\fBdoctools::toc::export::wiki\fR +\fIfiles/modules/doctools2toc/export_wiki.n\fR: wiki export plugin +.TP +\fBdoctools::toc::import\fR +\fIfiles/modules/doctools2toc/import.n\fR: Importing keyword indices +.TP +\fBdoctools::toc::import::doctoc\fR +\fIfiles/modules/doctools2toc/import_doctoc.n\fR: doctoc import plugin +.TP +\fBdoctools::toc::import::json\fR +\fIfiles/modules/doctools2toc/import_json.n\fR: JSON import plugin +.TP +\fBdoctools::toc::parse\fR +\fIfiles/modules/doctools2toc/parse.n\fR: Parsing text in doctoc format +.TP +\fBdoctools::toc::structure\fR +\fIfiles/modules/doctools2toc/structure.n\fR: Doctoc serialization utilities +.TP +\fBdoctools_intro\fR +\fIfiles/modules/doctools/doctools_intro.n\fR: doctools introduction +.TP +\fBdoctools_lang_cmdref\fR +\fIfiles/modules/doctools/doctools_lang_cmdref.n\fR: doctools language command reference +.TP +\fBdoctools_lang_faq\fR +\fIfiles/modules/doctools/doctools_lang_faq.n\fR: doctools language faq +.TP +\fBdoctools_lang_intro\fR +\fIfiles/modules/doctools/doctools_lang_intro.n\fR: doctools language introduction +.TP +\fBdoctools_lang_syntax\fR +\fIfiles/modules/doctools/doctools_lang_syntax.n\fR: doctools language syntax +.TP +\fBdoctools_plugin_apiref\fR +\fIfiles/modules/doctools/doctools_plugin_apiref.n\fR: doctools plugin API reference +.TP +\fBdtplite\fR +\fIfiles/apps/dtplite.n\fR: Lightweight DocTools Markup Processor +.TP +\fBexif\fR +\fIfiles/modules/exif/exif.n\fR: Tcl EXIF extracts and parses EXIF fields from digital images +.TP +\fBfileutil\fR +\fIfiles/modules/fileutil/fileutil.n\fR: Procedures implementing some file utilities +.TP +\fBfileutil::magic::cfront\fR +\fIfiles/modules/fumagic/cfront.n\fR: Generator core for compiler of magic(5) files +.TP +\fBfileutil::magic::cgen\fR +\fIfiles/modules/fumagic/cgen.n\fR: Generator core for compiler of magic(5) files +.TP +\fBfileutil::magic::filetype\fR +\fIfiles/modules/fumagic/filetypes.n\fR: Procedures implementing file-type recognition +.TP +\fBfileutil::magic::mimetype\fR +\fIfiles/modules/fumagic/mimetypes.n\fR: Procedures implementing mime-type recognition +.TP +\fBfileutil::magic::rt\fR +\fIfiles/modules/fumagic/rtcore.n\fR: Runtime core for file type recognition engines written in pure Tcl +.TP +\fBfileutil::multi\fR +\fIfiles/modules/fileutil/multi.n\fR: Multi-file operation, scatter/gather, standard object +.TP +\fBfileutil::multi::op\fR +\fIfiles/modules/fileutil/multiop.n\fR: Multi-file operation, scatter/gather +.TP +\fBfileutil_traverse\fR +\fIfiles/modules/fileutil/traverse.n\fR: Iterative directory traversal +.TP +\fBftp\fR +\fIfiles/modules/ftp/ftp.n\fR: Client-side tcl implementation of the ftp protocol +.TP +\fBftp::geturl\fR +\fIfiles/modules/ftp/ftp_geturl.n\fR: Uri handler for ftp urls +.TP +\fBftpd\fR +\fIfiles/modules/ftpd/ftpd.n\fR: Tcl FTP server implementation +.TP +\fBgenerator\fR +\fIfiles/modules/generator/generator.n\fR: Procedures for creating and using generators. +.TP +\fBgpx\fR +\fIfiles/modules/gpx/gpx.n\fR: Extracts waypoints, tracks and routes from GPX files +.TP +\fBgrammar::aycock\fR +\fIfiles/modules/grammar_aycock/aycock.n\fR: Aycock-Horspool-Earley parser generator for Tcl +.TP +\fBgrammar::fa\fR +\fIfiles/modules/grammar_fa/fa.n\fR: Create and manipulate finite automatons +.TP +\fBgrammar::fa::dacceptor\fR +\fIfiles/modules/grammar_fa/dacceptor.n\fR: Create and use deterministic acceptors +.TP +\fBgrammar::fa::dexec\fR +\fIfiles/modules/grammar_fa/dexec.n\fR: Execute deterministic finite automatons +.TP +\fBgrammar::fa::op\fR +\fIfiles/modules/grammar_fa/faop.n\fR: Operations on finite automatons +.TP +\fBgrammar::me::cpu\fR +\fIfiles/modules/grammar_me/me_cpu.n\fR: Virtual machine implementation II for parsing token streams +.TP +\fBgrammar::me::cpu::core\fR +\fIfiles/modules/grammar_me/me_cpucore.n\fR: ME virtual machine state manipulation +.TP +\fBgrammar::me::cpu::gasm\fR +\fIfiles/modules/grammar_me/gasm.n\fR: ME assembler +.TP +\fBgrammar::me::tcl\fR +\fIfiles/modules/grammar_me/me_tcl.n\fR: Virtual machine implementation I for parsing token streams +.TP +\fBgrammar::me::util\fR +\fIfiles/modules/grammar_me/me_util.n\fR: AST utilities +.TP +\fBgrammar::me_ast\fR +\fIfiles/modules/grammar_me/me_ast.n\fR: Various representations of ASTs +.TP +\fBgrammar::me_intro\fR +\fIfiles/modules/grammar_me/me_intro.n\fR: Introduction to virtual machines for parsing token streams +.TP +\fBgrammar::me_vm\fR +\fIfiles/modules/grammar_me/me_vm.n\fR: Virtual machine for parsing token streams +.TP +\fBgrammar::peg\fR +\fIfiles/modules/grammar_peg/peg.n\fR: Create and manipulate parsing expression grammars +.TP +\fBgrammar::peg::interp\fR +\fIfiles/modules/grammar_peg/peg_interp.n\fR: Interpreter for parsing expression grammars +.TP +\fBhook\fR +\fIfiles/modules/hook/hook.n\fR: Hooks +.TP +\fBhtml\fR +\fIfiles/modules/html/html.n\fR: Procedures to generate HTML structures +.TP +\fBhtmlparse\fR +\fIfiles/modules/htmlparse/htmlparse.n\fR: Procedures to parse HTML strings +.TP +\fBhuddle\fR +\fIfiles/modules/yaml/huddle.n\fR: Create and manipulate huddle object +.TP +\fBident\fR +\fIfiles/modules/ident/ident.n\fR: Ident protocol client +.TP +\fBimap4\fR +\fIfiles/modules/imap4/imap4.n\fR: imap client-side tcl implementation of imap protocol +.TP +\fBinifile\fR +\fIfiles/modules/inifile/ini.n\fR: Parsing of Windows INI files +.TP +\fBinterp\fR +\fIfiles/modules/interp/tcllib_interp.n\fR: Interp creation and aliasing +.TP +\fBirc\fR +\fIfiles/modules/irc/irc.n\fR: Create IRC connection and interface. +.TP +\fBjavascript\fR +\fIfiles/modules/javascript/javascript.n\fR: Procedures to generate HTML and Java Script structures. +.TP +\fBjpeg\fR +\fIfiles/modules/jpeg/jpeg.n\fR: JPEG querying and manipulation of meta data +.TP +\fBjson\fR +\fIfiles/modules/json/json.n\fR: JSON parser +.TP +\fBjson::write\fR +\fIfiles/modules/json/json_write.n\fR: JSON generation +.TP +\fBlambda\fR +\fIfiles/modules/lambda/lambda.n\fR: Utility commands for anonymous procedures +.TP +\fBldap\fR +\fIfiles/modules/ldap/ldap.n\fR: LDAP client +.TP +\fBldapx\fR +\fIfiles/modules/ldap/ldapx.n\fR: LDAP extended object interface +.TP +\fBlog\fR +\fIfiles/modules/log/log.n\fR: Procedures to log messages of libraries and applications. +.TP +\fBlogger\fR +\fIfiles/modules/log/logger.n\fR: System to control logging of events. +.TP +\fBlogger::appender\fR +\fIfiles/modules/log/loggerAppender.n\fR: Collection of predefined appenders for logger +.TP +\fBlogger::utils\fR +\fIfiles/modules/log/loggerUtils.n\fR: Utilities for logger +.TP +\fBmap::geocode::nominatim\fR +\fIfiles/modules/map/map_geocode_nominatim.n\fR: Resolving geographical names with a Nominatim service +.TP +\fBmap::slippy\fR +\fIfiles/modules/map/map_slippy.n\fR: Common code for slippy based map packages +.TP +\fBmap::slippy::cache\fR +\fIfiles/modules/map/map_slippy_cache.n\fR: Management of a tile cache in the local filesystem +.TP +\fBmap::slippy::fetcher\fR +\fIfiles/modules/map/map_slippy_fetcher.n\fR: Accessing a server providing tiles for slippy-based maps +.TP +\fBmapproj\fR +\fIfiles/modules/mapproj/mapproj.n\fR: Map projection routines +.TP +\fBmath\fR +\fIfiles/modules/math/math.n\fR: Tcl Math Library +.TP +\fBmath::bigfloat\fR +\fIfiles/modules/math/bigfloat.n\fR: Arbitrary precision floating-point numbers +.TP +\fBmath::bignum\fR +\fIfiles/modules/math/bignum.n\fR: Arbitrary precision integer numbers +.TP +\fBmath::calculus\fR +\fIfiles/modules/math/calculus.n\fR: Integration and ordinary differential equations +.TP +\fBmath::calculus::romberg\fR +\fIfiles/modules/math/romberg.n\fR: Romberg integration +.TP +\fBmath::calculus::symdiff\fR +\fIfiles/modules/math/symdiff.n\fR: Symbolic differentiation for Tcl +.TP +\fBmath::combinatorics\fR +\fIfiles/modules/math/combinatorics.n\fR: Combinatorial functions in the Tcl Math Library +.TP +\fBmath::complexnumbers\fR +\fIfiles/modules/math/qcomplex.n\fR: Straightforward complex number package +.TP +\fBmath::constants\fR +\fIfiles/modules/math/constants.n\fR: Mathematical and numerical constants +.TP +\fBmath::decimal\fR +\fIfiles/modules/math/decimal.n\fR: General decimal arithmetic +.TP +\fBmath::fourier\fR +\fIfiles/modules/math/fourier.n\fR: Discrete and fast fourier transforms +.TP +\fBmath::fuzzy\fR +\fIfiles/modules/math/fuzzy.n\fR: Fuzzy comparison of floating-point numbers +.TP +\fBmath::geometry\fR +\fIfiles/modules/math/math_geometry.n\fR: Geometrical computations +.TP +\fBmath::interpolate\fR +\fIfiles/modules/math/interpolate.n\fR: Interpolation routines +.TP +\fBmath::linearalgebra\fR +\fIfiles/modules/math/linalg.n\fR: Linear Algebra +.TP +\fBmath::numtheory\fR +\fIfiles/modules/math/numtheory.n\fR: Number Theory +.TP +\fBmath::optimize\fR +\fIfiles/modules/math/optimize.n\fR: Optimisation routines +.TP +\fBmath::polynomials\fR +\fIfiles/modules/math/polynomials.n\fR: Polynomial functions +.TP +\fBmath::rationalfunctions\fR +\fIfiles/modules/math/rational_funcs.n\fR: Polynomial functions +.TP +\fBmath::roman\fR +\fIfiles/modules/math/roman.n\fR: Tools for creating and manipulating roman numerals +.TP +\fBmath::special\fR +\fIfiles/modules/math/special.n\fR: Special mathematical functions +.TP +\fBmath::statistics\fR +\fIfiles/modules/math/statistics.n\fR: Basic statistical functions and procedures +.TP +\fBmd4\fR +\fIfiles/modules/md4/md4.n\fR: MD4 Message-Digest Algorithm +.TP +\fBmd5\fR +\fIfiles/modules/md5/md5.n\fR: MD5 Message-Digest Algorithm +.TP +\fBmd5crypt\fR +\fIfiles/modules/md5crypt/md5crypt.n\fR: MD5-based password encryption +.TP +\fBmime\fR +\fIfiles/modules/mime/mime.n\fR: Manipulation of MIME body parts +.TP +\fBmpexpand\fR +\fIfiles/modules/doctools/mpexpand.n\fR: Markup processor +.TP +\fBmultiplexer\fR +\fIfiles/modules/multiplexer/multiplexer.n\fR: One-to-many communication with sockets. +.TP +\fBnameserv\fR +\fIfiles/modules/nns/nns_client.n\fR: Name service facility, Client +.TP +\fBnameserv::auto\fR +\fIfiles/modules/nns/nns_auto.n\fR: Name service facility, Client Extension +.TP +\fBnameserv::common\fR +\fIfiles/modules/nns/nns_common.n\fR: Name service facility, shared definitions +.TP +\fBnameserv::protocol\fR +\fIfiles/modules/nns/nns_protocol.n\fR: Name service facility, client/server protocol +.TP +\fBnameserv::server\fR +\fIfiles/modules/nns/nns_server.n\fR: Name service facility, Server +.TP +\fBnamespacex\fR +\fIfiles/modules/namespacex/namespacex.n\fR: Namespace utility commands +.TP +\fBncgi\fR +\fIfiles/modules/ncgi/ncgi.n\fR: Procedures to manipulate CGI values. +.TP +\fBnmea\fR +\fIfiles/modules/nmea/nmea.n\fR: Process NMEA data +.TP +\fBnns\fR +\fIfiles/apps/nns.n\fR: Name service facility, Commandline Client Application +.TP +\fBnns_intro\fR +\fIfiles/modules/nns/nns_intro.n\fR: Name service facility, introduction +.TP +\fBnnsd\fR +\fIfiles/apps/nnsd.n\fR: Name service facility, Commandline Server Application +.TP +\fBnnslog\fR +\fIfiles/apps/nnslog.n\fR: Name service facility, Commandline Logging Client Application +.TP +\fBnntp\fR +\fIfiles/modules/nntp/nntp.n\fR: Tcl client for the NNTP protocol +.TP +\fBntp_time\fR +\fIfiles/modules/ntp/ntp_time.n\fR: Tcl Time Service Client +.TP +\fBoo::util\fR +\fIfiles/modules/ooutil/ooutil.n\fR: Utility commands for TclOO +.TP +\fBotp\fR +\fIfiles/modules/otp/otp.n\fR: One-Time Passwords +.TP +\fBpage\fR +\fIfiles/apps/page.n\fR: Parser Generator +.TP +\fBpage_intro\fR +\fIfiles/modules/page/page_intro.n\fR: page introduction +.TP +\fBpage_pluginmgr\fR +\fIfiles/modules/page/page_pluginmgr.n\fR: page plugin manager +.TP +\fBpage_util_flow\fR +\fIfiles/modules/page/page_util_flow.n\fR: page dataflow/treewalker utility +.TP +\fBpage_util_norm_lemon\fR +\fIfiles/modules/page/page_util_norm_lemon.n\fR: page AST normalization, LEMON +.TP +\fBpage_util_norm_peg\fR +\fIfiles/modules/page/page_util_norm_peg.n\fR: page AST normalization, PEG +.TP +\fBpage_util_peg\fR +\fIfiles/modules/page/page_util_peg.n\fR: page PEG transformation utilities +.TP +\fBpage_util_quote\fR +\fIfiles/modules/page/page_util_quote.n\fR: page character quoting utilities +.TP +\fBpicoirc\fR +\fIfiles/modules/irc/picoirc.n\fR: Small and simple embeddable IRC client. +.TP +\fBpki\fR +\fIfiles/modules/pki/pki.n\fR: Implementation of the public key cipher +.TP +\fBpluginmgr\fR +\fIfiles/modules/pluginmgr/pluginmgr.n\fR: Manage a plugin +.TP +\fBpng\fR +\fIfiles/modules/png/png.n\fR: PNG querying and manipulation of meta data +.TP +\fBpop3\fR +\fIfiles/modules/pop3/pop3.n\fR: Tcl client for POP3 email protocol +.TP +\fBpop3d\fR +\fIfiles/modules/pop3d/pop3d.n\fR: Tcl POP3 server implementation +.TP +\fBpop3d::dbox\fR +\fIfiles/modules/pop3d/pop3d_dbox.n\fR: Simple mailbox database for pop3d +.TP +\fBpop3d::udb\fR +\fIfiles/modules/pop3d/pop3d_udb.n\fR: Simple user database for pop3d +.TP +\fBprofiler\fR +\fIfiles/modules/profiler/profiler.n\fR: Tcl source code profiler +.TP +\fBpt\fR +\fIfiles/modules/pt/pt.n\fR: Parser Tools Application +.TP +\fBpt::ast\fR +\fIfiles/modules/pt/pt_astree.n\fR: Abstract Syntax Tree Serialization +.TP +\fBpt::cparam::configuration::critcl\fR +\fIfiles/modules/pt/pt_cparam_config_critcl.n\fR: C/PARAM, Canned configuration, Critcl +.TP +\fBpt::json_language\fR +\fIfiles/modules/pt/pt_json_language.n\fR: The JSON Grammar Exchange Format +.TP +\fBpt::param\fR +\fIfiles/modules/pt/pt_param.n\fR: PackRat Machine Specification +.TP +\fBpt::pe\fR +\fIfiles/modules/pt/pt_pexpression.n\fR: Parsing Expression Serialization +.TP +\fBpt::pe::op\fR +\fIfiles/modules/pt/pt_pexpr_op.n\fR: Parsing Expression Utilities +.TP +\fBpt::peg\fR +\fIfiles/modules/pt/pt_pegrammar.n\fR: Parsing Expression Grammar Serialization +.TP +\fBpt::peg::container\fR +\fIfiles/modules/pt/pt_peg_container.n\fR: PEG Storage +.TP +\fBpt::peg::container::peg\fR +\fIfiles/modules/pt/pt_peg_container_peg.n\fR: PEG Storage. Canned PEG grammar specification +.TP +\fBpt::peg::export\fR +\fIfiles/modules/pt/pt_peg_export.n\fR: PEG Export +.TP +\fBpt::peg::export::container\fR +\fIfiles/modules/pt/pt_peg_export_container.n\fR: PEG Export Plugin. Write CONTAINER format +.TP +\fBpt::peg::export::json\fR +\fIfiles/modules/pt/pt_peg_export_json.n\fR: PEG Export Plugin. Write JSON format +.TP +\fBpt::peg::export::peg\fR +\fIfiles/modules/pt/pt_peg_export_peg.n\fR: PEG Export Plugin. Write PEG format +.TP +\fBpt::peg::from::container\fR +\fIfiles/modules/pt/pt_peg_from_container.n\fR: PEG Conversion. From CONTAINER format +.TP +\fBpt::peg::from::json\fR +\fIfiles/modules/pt/pt_peg_from_json.n\fR: PEG Conversion. Read JSON format +.TP +\fBpt::peg::from::peg\fR +\fIfiles/modules/pt/pt_peg_from_peg.n\fR: PEG Conversion. Read PEG format +.TP +\fBpt::peg::import\fR +\fIfiles/modules/pt/pt_peg_import.n\fR: PEG Import +.TP +\fBpt::peg::import::container\fR +\fIfiles/modules/pt/pt_peg_import_container.n\fR: PEG Import Plugin. From CONTAINER format +.TP +\fBpt::peg::import::json\fR +\fIfiles/modules/pt/pt_peg_import_json.n\fR: PEG Import Plugin. Read JSON format +.TP +\fBpt::peg::import::peg\fR +\fIfiles/modules/pt/pt_peg_import_peg.n\fR: PEG Import Plugin. Read PEG format +.TP +\fBpt::peg::interp\fR +\fIfiles/modules/pt/pt_peg_interp.n\fR: Interpreter for parsing expression grammars +.TP +\fBpt::peg::to::container\fR +\fIfiles/modules/pt/pt_peg_to_container.n\fR: PEG Conversion. Write CONTAINER format +.TP +\fBpt::peg::to::cparam\fR +\fIfiles/modules/pt/pt_peg_to_cparam.n\fR: PEG Conversion. Write CPARAM format +.TP +\fBpt::peg::to::json\fR +\fIfiles/modules/pt/pt_peg_to_json.n\fR: PEG Conversion. Write JSON format +.TP +\fBpt::peg::to::param\fR +\fIfiles/modules/pt/pt_peg_to_param.n\fR: PEG Conversion. Write PARAM format +.TP +\fBpt::peg::to::peg\fR +\fIfiles/modules/pt/pt_peg_to_peg.n\fR: PEG Conversion. Write PEG format +.TP +\fBpt::peg::to::tclparam\fR +\fIfiles/modules/pt/pt_peg_to_tclparam.n\fR: PEG Conversion. Write TCLPARAM format +.TP +\fBpt::peg_language\fR +\fIfiles/modules/pt/pt_peg_language.n\fR: PEG Language Tutorial +.TP +\fBpt::pegrammar\fR +\fIfiles/modules/pt/pt_peg_introduction.n\fR: Introduction to Parsing Expression Grammars +.TP +\fBpt::pgen\fR +\fIfiles/modules/pt/pt_pgen.n\fR: Parser Generator +.TP +\fBpt::rde\fR +\fIfiles/modules/pt/pt_rdengine.n\fR: Parsing Runtime Support, PARAM based +.TP +\fBpt::tclparam::configuration::snit\fR +\fIfiles/modules/pt/pt_tclparam_config_snit.n\fR: Tcl/PARAM, Canned configuration, Snit +.TP +\fBpt::tclparam::configuration::tcloo\fR +\fIfiles/modules/pt/pt_tclparam_config_tcloo.n\fR: Tcl/PARAM, Canned configuration, Tcloo +.TP +\fBpt_export_api\fR +\fIfiles/modules/pt/pt_to_api.n\fR: Parser Tools Export API +.TP +\fBpt_import_api\fR +\fIfiles/modules/pt/pt_from_api.n\fR: Parser Tools Import API +.TP +\fBpt_introduction\fR +\fIfiles/modules/pt/pt_introduction.n\fR: Introduction to Parser Tools +.TP +\fBpt_parser_api\fR +\fIfiles/modules/pt/pt_parser_api.n\fR: Parser API +.TP +\fBrc4\fR +\fIfiles/modules/rc4/rc4.n\fR: Implementation of the RC4 stream cipher +.TP +\fBrcs\fR +\fIfiles/modules/rcs/rcs.n\fR: RCS low level utilities +.TP +\fBreport\fR +\fIfiles/modules/report/report.n\fR: Create and manipulate report objects +.TP +\fBrest\fR +\fIfiles/modules/rest/rest.n\fR: define REST web APIs and call them inline or asychronously +.TP +\fBripemd128\fR +\fIfiles/modules/ripemd/ripemd128.n\fR: RIPEMD-128 Message-Digest Algorithm +.TP +\fBripemd160\fR +\fIfiles/modules/ripemd/ripemd160.n\fR: RIPEMD-160 Message-Digest Algorithm +.TP +\fBS3\fR +\fIfiles/modules/amazon-s3/S3.n\fR: Amazon S3 Web Service Interface +.TP +\fBSASL\fR +\fIfiles/modules/sasl/sasl.n\fR: Implementation of SASL mechanisms for Tcl +.TP +\fBsha1\fR +\fIfiles/modules/sha1/sha1.n\fR: SHA1 Message-Digest Algorithm +.TP +\fBsha256\fR +\fIfiles/modules/sha1/sha256.n\fR: SHA256 Message-Digest Algorithm +.TP +\fBsimulation::annealing\fR +\fIfiles/modules/simulation/annealing.n\fR: Simulated annealing +.TP +\fBsimulation::montecarlo\fR +\fIfiles/modules/simulation/montecarlo.n\fR: Monte Carlo simulations +.TP +\fBsimulation::random\fR +\fIfiles/modules/simulation/simulation_random.n\fR: Pseudo-random number generators +.TP +\fBsmtp\fR +\fIfiles/modules/mime/smtp.n\fR: Client-side tcl implementation of the smtp protocol +.TP +\fBsmtpd\fR +\fIfiles/modules/smtpd/smtpd.n\fR: Tcl SMTP server implementation +.TP +\fBsnit\fR +\fIfiles/modules/snit/snit.n\fR: Snit's Not Incr Tcl +.TP +\fBsnitfaq\fR +\fIfiles/modules/snit/snitfaq.n\fR: Snit Frequently Asked Questions +.TP +\fBsoundex\fR +\fIfiles/modules/soundex/soundex.n\fR: Soundex +.TP +\fBstooop\fR +\fIfiles/modules/stooop/stooop.n\fR: Object oriented extension. +.TP +\fBstringprep\fR +\fIfiles/modules/stringprep/stringprep.n\fR: Implementation of stringprep +.TP +\fBstringprep::data\fR +\fIfiles/modules/stringprep/stringprep_data.n\fR: stringprep data tables, generated, internal +.TP +\fBstruct::disjointset\fR +\fIfiles/modules/struct/disjointset.n\fR: Disjoint set data structure +.TP +\fBstruct::graph\fR +\fIfiles/modules/struct/graph.n\fR: Create and manipulate directed graph objects +.TP +\fBstruct::graph::op\fR +\fIfiles/modules/struct/graphops.n\fR: Operation for (un)directed graph objects +.TP +\fBstruct::graph_v1\fR +\fIfiles/modules/struct/graph1.n\fR: Create and manipulate directed graph objects +.TP +\fBstruct::list\fR +\fIfiles/modules/struct/struct_list.n\fR: Procedures for manipulating lists +.TP +\fBstruct::matrix\fR +\fIfiles/modules/struct/matrix.n\fR: Create and manipulate matrix objects +.TP +\fBstruct::matrix_v1\fR +\fIfiles/modules/struct/matrix1.n\fR: Create and manipulate matrix objects +.TP +\fBstruct::pool\fR +\fIfiles/modules/struct/pool.n\fR: Create and manipulate pool objects (of discrete items) +.TP +\fBstruct::prioqueue\fR +\fIfiles/modules/struct/prioqueue.n\fR: Create and manipulate prioqueue objects +.TP +\fBstruct::queue\fR +\fIfiles/modules/struct/queue.n\fR: Create and manipulate queue objects +.TP +\fBstruct::record\fR +\fIfiles/modules/struct/record.n\fR: Define and create records (similar to 'C' structures) +.TP +\fBstruct::set\fR +\fIfiles/modules/struct/struct_set.n\fR: Procedures for manipulating sets +.TP +\fBstruct::skiplist\fR +\fIfiles/modules/struct/skiplist.n\fR: Create and manipulate skiplists +.TP +\fBstruct::stack\fR +\fIfiles/modules/struct/stack.n\fR: Create and manipulate stack objects +.TP +\fBstruct::tree\fR +\fIfiles/modules/struct/struct_tree.n\fR: Create and manipulate tree objects +.TP +\fBstruct::tree_v1\fR +\fIfiles/modules/struct/struct_tree1.n\fR: Create and manipulate tree objects +.TP +\fBsum\fR +\fIfiles/modules/crc/sum.n\fR: Calculate a sum(1) compatible checksum +.TP +\fBtar\fR +\fIfiles/modules/tar/tar.n\fR: Tar file creation, extraction & manipulation +.TP +\fBtcl::chan::cat\fR +\fIfiles/modules/virtchannel_base/cat.n\fR: Concatenation channel +.TP +\fBtcl::chan::core\fR +\fIfiles/modules/virtchannel_core/core.n\fR: Basic reflected/virtual channel support +.TP +\fBtcl::chan::events\fR +\fIfiles/modules/virtchannel_core/events.n\fR: Event support for reflected/virtual channels +.TP +\fBtcl::chan::facade\fR +\fIfiles/modules/virtchannel_base/facade.n\fR: Facade channel +.TP +\fBtcl::chan::fifo\fR +\fIfiles/modules/virtchannel_base/fifo.n\fR: In-memory fifo channel +.TP +\fBtcl::chan::fifo2\fR +\fIfiles/modules/virtchannel_base/fifo2.n\fR: In-memory interconnected fifo channels +.TP +\fBtcl::chan::halfpipe\fR +\fIfiles/modules/virtchannel_base/halfpipe.n\fR: In-memory channel, half of a fifo2 +.TP +\fBtcl::chan::memchan\fR +\fIfiles/modules/virtchannel_base/memchan.n\fR: In-memory channel +.TP +\fBtcl::chan::null\fR +\fIfiles/modules/virtchannel_base/null.n\fR: Null channel +.TP +\fBtcl::chan::nullzero\fR +\fIfiles/modules/virtchannel_base/nullzero.n\fR: Null/Zero channel combination +.TP +\fBtcl::chan::random\fR +\fIfiles/modules/virtchannel_base/random.n\fR: Random channel +.TP +\fBtcl::chan::randseed\fR +\fIfiles/modules/virtchannel_base/randseed.n\fR: Utilities for random channels +.TP +\fBtcl::chan::std\fR +\fIfiles/modules/virtchannel_base/std.n\fR: Standard I/O, unification of stdin and stdout +.TP +\fBtcl::chan::string\fR +\fIfiles/modules/virtchannel_base/string.n\fR: Read-only in-memory channel +.TP +\fBtcl::chan::textwindow\fR +\fIfiles/modules/virtchannel_base/textwindow.n\fR: Textwindow channel +.TP +\fBtcl::chan::variable\fR +\fIfiles/modules/virtchannel_base/variable.n\fR: In-memory channel using variable for storage +.TP +\fBtcl::chan::zero\fR +\fIfiles/modules/virtchannel_base/zero.n\fR: Zero channel +.TP +\fBtcl::transform::adler32\fR +\fIfiles/modules/virtchannel_transform/adler32.n\fR: Adler32 transformation +.TP +\fBtcl::transform::base64\fR +\fIfiles/modules/virtchannel_transform/base64.n\fR: Base64 encoding transformation +.TP +\fBtcl::transform::core\fR +\fIfiles/modules/virtchannel_core/transformcore.n\fR: Basic reflected/virtual channel transform support +.TP +\fBtcl::transform::counter\fR +\fIfiles/modules/virtchannel_transform/counter.n\fR: Counter transformation +.TP +\fBtcl::transform::crc32\fR +\fIfiles/modules/virtchannel_transform/crc32.n\fR: Crc32 transformation +.TP +\fBtcl::transform::hex\fR +\fIfiles/modules/virtchannel_transform/hex.n\fR: Hexadecimal encoding transformation +.TP +\fBtcl::transform::identity\fR +\fIfiles/modules/virtchannel_transform/identity.n\fR: Identity transformation +.TP +\fBtcl::transform::limitsize\fR +\fIfiles/modules/virtchannel_transform/limitsize.n\fR: limiting input +.TP +\fBtcl::transform::observe\fR +\fIfiles/modules/virtchannel_transform/observe.n\fR: Observer transformation, stream copy +.TP +\fBtcl::transform::otp\fR +\fIfiles/modules/virtchannel_transform/otp.n\fR: Encryption via one-time pad +.TP +\fBtcl::transform::rot\fR +\fIfiles/modules/virtchannel_transform/rot.n\fR: rot-encryption +.TP +\fBtcl::transform::spacer\fR +\fIfiles/modules/virtchannel_transform/spacer.n\fR: Space insertation and removal +.TP +\fBtcl::transform::zlib\fR +\fIfiles/modules/virtchannel_transform/zlib.n\fR: zlib (de)compression +.TP +\fBtcldocstrip\fR +\fIfiles/apps/tcldocstrip.n\fR: Tcl-based Docstrip Processor +.TP +\fBtcllib_ip\fR +\fIfiles/modules/dns/tcllib_ip.n\fR: IPv4 and IPv6 address manipulation +.TP +\fBtclrep/machineparameters\fR +\fIfiles/modules/math/machineparameters.n\fR: Compute double precision machine parameters. +.TP +\fBtepam\fR +\fIfiles/modules/tepam/tepam_introduction.n\fR: An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager +.TP +\fBtepam::argument_dialogbox\fR +\fIfiles/modules/tepam/tepam_argument_dialogbox.n\fR: TEPAM argument_dialogbox, reference manual +.TP +\fBtepam::procedure\fR +\fIfiles/modules/tepam/tepam_procedure.n\fR: TEPAM procedure, reference manual +.TP +\fBterm\fR +\fIfiles/modules/term/term.n\fR: General terminal control +.TP +\fBterm::ansi::code\fR +\fIfiles/modules/term/ansi_code.n\fR: Helper for control sequences +.TP +\fBterm::ansi::code::attr\fR +\fIfiles/modules/term/ansi_cattr.n\fR: ANSI attribute sequences +.TP +\fBterm::ansi::code::ctrl\fR +\fIfiles/modules/term/ansi_cctrl.n\fR: ANSI control sequences +.TP +\fBterm::ansi::code::macros\fR +\fIfiles/modules/term/ansi_cmacros.n\fR: Macro sequences +.TP +\fBterm::ansi::ctrl::unix\fR +\fIfiles/modules/term/ansi_ctrlu.n\fR: Control operations and queries +.TP +\fBterm::ansi::send\fR +\fIfiles/modules/term/ansi_send.n\fR: Output of ANSI control sequences to terminals +.TP +\fBterm::interact::menu\fR +\fIfiles/modules/term/imenu.n\fR: Terminal widget, menu +.TP +\fBterm::interact::pager\fR +\fIfiles/modules/term/ipager.n\fR: Terminal widget, paging +.TP +\fBterm::receive\fR +\fIfiles/modules/term/receive.n\fR: General input from terminals +.TP +\fBterm::receive::bind\fR +\fIfiles/modules/term/term_bind.n\fR: Keyboard dispatch from terminals +.TP +\fBterm::send\fR +\fIfiles/modules/term/term_send.n\fR: General output to terminals +.TP +\fBtextutil\fR +\fIfiles/modules/textutil/textutil.n\fR: Procedures to manipulate texts and strings. +.TP +\fBtextutil::adjust\fR +\fIfiles/modules/textutil/adjust.n\fR: Procedures to adjust, indent, and undent paragraphs +.TP +\fBtextutil::expander\fR +\fIfiles/modules/textutil/expander.n\fR: Procedures to process templates and expand text. +.TP +\fBtextutil::repeat\fR +\fIfiles/modules/textutil/repeat.n\fR: Procedures to repeat strings. +.TP +\fBtextutil::split\fR +\fIfiles/modules/textutil/textutil_split.n\fR: Procedures to split texts +.TP +\fBtextutil::string\fR +\fIfiles/modules/textutil/textutil_string.n\fR: Procedures to manipulate texts and strings. +.TP +\fBtextutil::tabify\fR +\fIfiles/modules/textutil/tabify.n\fR: Procedures to (un)tabify strings +.TP +\fBtextutil::trim\fR +\fIfiles/modules/textutil/trim.n\fR: Procedures to trim strings +.TP +\fBtie\fR +\fIfiles/modules/tie/tie.n\fR: Array persistence +.TP +\fBtie\fR +\fIfiles/modules/tie/tie_std.n\fR: Array persistence, standard data sources +.TP +\fBtiff\fR +\fIfiles/modules/tiff/tiff.n\fR: TIFF reading, writing, and querying and manipulation of meta data +.TP +\fBtransfer::connect\fR +\fIfiles/modules/transfer/connect.n\fR: Connection setup +.TP +\fBtransfer::copy\fR +\fIfiles/modules/transfer/copyops.n\fR: Data transfer foundation +.TP +\fBtransfer::copy::queue\fR +\fIfiles/modules/transfer/tqueue.n\fR: Queued transfers +.TP +\fBtransfer::data::destination\fR +\fIfiles/modules/transfer/ddest.n\fR: Data destination +.TP +\fBtransfer::data::source\fR +\fIfiles/modules/transfer/dsource.n\fR: Data source +.TP +\fBtransfer::receiver\fR +\fIfiles/modules/transfer/receiver.n\fR: Data source +.TP +\fBtransfer::transmitter\fR +\fIfiles/modules/transfer/transmitter.n\fR: Data source +.TP +\fBtreeql\fR +\fIfiles/modules/treeql/treeql.n\fR: Query tree objects +.TP +\fBtry\fR +\fIfiles/modules/try/tcllib_try.n\fR: try - Trap and process errors and exceptions +.TP +\fBuevent\fR +\fIfiles/modules/uev/uevent.n\fR: User events +.TP +\fBuevent::onidle\fR +\fIfiles/modules/uev/uevent_onidle.n\fR: Request merging and deferal to idle time +.TP +\fBunicode\fR +\fIfiles/modules/stringprep/unicode.n\fR: Implementation of Unicode normalization +.TP +\fBunicode::data\fR +\fIfiles/modules/stringprep/unicode_data.n\fR: unicode data tables, generated, internal +.TP +\fBunits\fR +\fIfiles/modules/units/units.n\fR: unit conversion +.TP +\fBuri\fR +\fIfiles/modules/uri/uri.n\fR: URI utilities +.TP +\fBuri_urn\fR +\fIfiles/modules/uri/urn-scheme.n\fR: URI utilities, URN scheme +.TP +\fBuuencode\fR +\fIfiles/modules/base64/uuencode.n\fR: UU-encode/decode binary data +.TP +\fBuuid\fR +\fIfiles/modules/uuid/uuid.n\fR: UUID generation and comparison +.TP +\fBwip\fR +\fIfiles/modules/wip/wip.n\fR: Word Interpreter +.TP +\fBxsxp\fR +\fIfiles/modules/amazon-s3/xsxp.n\fR: eXtremely Simple Xml Parser +.TP +\fByaml\fR +\fIfiles/modules/yaml/yaml.n\fR: YAML Format Encoder/Decoder +.TP +\fByencode\fR +\fIfiles/modules/base64/yencode.n\fR: Y-encode/decode binary data ADDED embedded/www/image/arch_core_container.png Index: embedded/www/image/arch_core_container.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_container.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_eplugins.png Index: embedded/www/image/arch_core_eplugins.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_eplugins.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_export.png Index: embedded/www/image/arch_core_export.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_export.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_import.png Index: embedded/www/image/arch_core_import.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_import.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_iplugins.png Index: embedded/www/image/arch_core_iplugins.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_iplugins.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_support.png Index: embedded/www/image/arch_core_support.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_support.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_transform.png Index: embedded/www/image/arch_core_transform.png ================================================================== --- /dev/null +++ embedded/www/image/arch_core_transform.png cannot compute difference between binary files ADDED embedded/www/image/arch_user_app.png Index: embedded/www/image/arch_user_app.png ================================================================== --- /dev/null +++ embedded/www/image/arch_user_app.png cannot compute difference between binary files ADDED embedded/www/image/arch_user_pkg.png Index: embedded/www/image/arch_user_pkg.png ================================================================== --- /dev/null +++ embedded/www/image/arch_user_pkg.png cannot compute difference between binary files ADDED embedded/www/image/architecture.png Index: embedded/www/image/architecture.png ================================================================== --- /dev/null +++ embedded/www/image/architecture.png cannot compute difference between binary files ADDED embedded/www/image/expr_ast.png Index: embedded/www/image/expr_ast.png ================================================================== --- /dev/null +++ embedded/www/image/expr_ast.png cannot compute difference between binary files ADDED embedded/www/image/flow.png Index: embedded/www/image/flow.png ================================================================== --- /dev/null +++ embedded/www/image/flow.png cannot compute difference between binary files ADDED embedded/www/image/gen_options.png Index: embedded/www/image/gen_options.png ================================================================== --- /dev/null +++ embedded/www/image/gen_options.png cannot compute difference between binary files ADDED embedded/www/index.html Index: embedded/www/index.html ================================================================== --- /dev/null +++ embedded/www/index.html @@ -0,0 +1,3982 @@ +<html> +<! -- Generated by tcllib/doctools/idx with format 'html' + --> +<! -- CVS: $Id$ Keyword Index + --> +<head> +<title> Keyword Index + + +
[ + Table Of Contents +| Home +]
+

Keyword Index

+
+ . · / · 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Keywords: . +
.ddt + docstrip_util +
.dtx + docstrip · tcldocstrip +
+Keywords: / +
/dev/null + tcl::chan::null · tcl::chan::nullzero +
/dev/random + tcl::chan::random · tcl::chan::randseed +
/dev/zero + tcl::chan::nullzero · tcl::chan::zero +
+Keywords: 3 +
3DES + des +
+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 +
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 +
automatic + nameserv::auto +
automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
aycock + grammar::aycock +
+Keywords: B +
base32 + base32 · base32::core · base32::hex +
base64 + base64 · tcl::transform::base64 +
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 +
blocking flow + struct::graph::op +
blowfish + blowfish +
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 +
cache + cache::async · map::slippy::cache +
caesar cipher + tcl::transform::rot +
calculus + math::calculus +
callback + cache::async · hook · lambda · oo::util · uevent::onidle +
callbacks + tcl::chan::halfpipe +
capitalize + textutil::string +
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 +
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 +
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 +
class methods + oo::util +
class variables + oo::util +
cleanup + try +
client + nameserv · nameserv::auto · nameserv::common · nns · nns_intro · nnslog +
cloud + S3 +
cmdline processing + cmdline +
color control + term::ansi::code::attr · term::ansi::code::ctrl +
columns + term::ansi::ctrl::unix +
comm + comm · comm_wire · deleg_method · deleg_proc · nameserv::protocol +
command + doctools::tcl::parse +
command line processing + cmdline +
command prefix + lambda · oo::util +
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 +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 · 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 +
cryptography + blowfish +
CSS + doctools::html::cssdefaults +
csv + bench::in · bench::out::csv · csv +
currying + lambda · 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 +
data source + transfer::data::source · transfer::transmitter +
data structures + struct::record +
database + tie · tie +
dataflow + page_util_flow +
DE + doctools::msgcat::idx::de · doctools::msgcat::toc::de +
decimal + math::decimal +
declare + term::ansi::code +
decompression + tcl::transform::zlib +
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 +
deserialization + doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::structure · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::structure +
diameter + struct::graph::op +
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 +
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 +
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 +
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 +
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 +
DOM + treeql +
dom + xsxp +
domain name service + dns +
+Keywords: E +
e + math::constants +
earley + grammar::aycock +
EBNF + pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 +
entry mask + tepam +
equal + struct::list +
equality + struct::list +
equivalence class + struct::disjointset +
error + try +
error function + math::special +
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 + 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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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::mimetype · fileutil::magic::rt +
file type + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::mimetype · fileutil::magic::rt +
file utilities + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::mimetype · fileutil::magic::rt · fileutil::multi · fileutil::multi::op +
filesystem + map::slippy::cache +
filter + generator · struct::list +
final + try +
find + struct::disjointset +
finite + struct::pool +
finite automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
FIPS 180-1 + sha1 · sha256 +
first permutation + struct::list +
Fisher-Yates + struct::list +
flatten + struct::list +
floating-point + math::bigfloat · math::fuzzy +
flow + control +
flow network + struct::graph::op +
folding + struct::list +
foldl + generator +
foldr + generator +
foreach + generator +
form + html · ncgi +
format conversion + pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam +
formatter + doctools_plugin_apiref +
formatting + bench::in · bench::out::csv · bench::out::text · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export · textutil · textutil::adjust · textutil::string · textutil::tabify +
formatting engine + docidx_plugin_apiref · doctoc_plugin_apiref · doctools_plugin_apiref +
Fourier transform + math::fourier +
FR + doctools::msgcat::idx::fr · doctools::msgcat::toc::fr +
frame + term::ansi::code::macros +
ftp + ftp · ftp::geturl · ftpd · uri +
ftpd + ftpd +
ftpserver + ftpd +
full outer join + struct::list +
+Keywords: G +
generate event + uevent +
generate permutations + struct::list +
generation + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
generator + generator +
geocoding + map::geocode::nominatim +
geodesy + map::slippy · mapproj +
geography + map::slippy +
get character + term::receive +
gets + coroutine · coroutine::auto +
global + coroutine · coroutine::auto +
gopher + uri +
gps + gpx · nmea +
gpx + gpx +
grammar + grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 +
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 · mpexpand +
html + html · htmlparse · javascript · ncgi +
http + autoproxy · map::geocode::nominatim · map::slippy::fetcher · uri +
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 +
ident + ident +
identification + ident +
identity + tcl::transform::identity +
idle + uevent::onidle +
image + jpeg · png · tiff +
imap + imap4 +
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 +
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 +
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 +
isthmus + struct::graph::op +
iterator + generator +
+Keywords: J +
javascript + javascript · json · json::write +
jfif + jpeg +
join + struct::list +
jpeg + exif · 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 · 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 +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 + 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 +
+Keywords: M +
macros + doctools::nroff::man_macros +
mail + imap4 · mime · pop3 · smtp +
mailto + uri +
maker note + exif +
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 · 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 · mpexpand · tcldocstrip +
matching + grammar::me_intro · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api · struct::graph::op +
math + math · math::bigfloat · math::bignum · math::calculus · math::complexnumbers · math::constants · math::decimal · math::fuzzy · math::geometry · math::interpolate · math::linearalgebra · math::optimize · math::polynomials · math::rationalfunctions · math::special · simulation::annealing · simulation::montecarlo · simulation::random +
mathematics + math::fourier · math::statistics +
matrices + math::linearalgebra +
matrix + csv · math::linearalgebra · report · struct::matrix · struct::matrix_v1 · struct::queue · struct::stack +
max cut + struct::graph::op +
maximum + math::optimize +
maximum flow + struct::graph::op +
md4 + md4 · ripemd128 · ripemd160 +
md5 + md5 · md5crypt +
md5crypt + md5crypt +
mega widget + snit · snitfaq +
membership + struct::set +
menu + term::ansi::code::macros · term::interact::menu +
merge + tcl::chan::randseed · 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 +
mime + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::mimetype · 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 +
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 +
+Keywords: N +
name service + nameserv · nameserv::auto · nameserv::common · nameserv::protocol · nameserv::server · nns · nns_intro · nnsd · nnslog +
namespace unknown + namespacex +
namespace utilities + namespacex +
neighbour + struct::graph · struct::graph::op +
net + ftp · ftp::geturl · imap4 · mime · smtp +
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 +
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 · mpexpand +
NTP + ntp_time +
null + tcl::chan::null · tcl::chan::nullzero +
number theory + math::numtheory +
+Keywords: O +
object + snit · snitfaq · stooop +
object oriented + snit · snitfaq · stooop +
observer + hook · tcl::transform::observe +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api · 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 · yaml +
parsing expression + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
parsing expression grammar + grammar::me_intro · grammar::peg · grammar::peg::interp · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
partial application + lambda +
partition + struct::disjointset +
partitioned set + struct::disjointset +
passive + transfer::connect +
password + otp +
patch + docstrip_util +
patching + rcs +
PEG + grammar::me_intro · page_util_norm_peg · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 +
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 +
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 +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
+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::chan::randseed +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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::randseed · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · 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 +
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 +
reverse + struct::list +
rfc 821 + mime · smtp · smtpd +
rfc 822 + mime · pop3d::dbox · smtp +
rfc 868 + ntp_time +
rfc 959 + ftp · ftp::geturl · ftpd +
rfc 977 + nntp +
rfc 1034 + dns +
rfc 1035 + dns +
rfc 1036 + nntp +
rfc 1320 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1321 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1413 + ident +
rfc 1886 + dns +
rfc 1939 + pop3 · pop3d +
rfc 2030 + ntp_time +
rfc 2045 + mime +
rfc 2046 + mime +
rfc 2049 + mime +
rfc 2104 + md4 · md5 · ripemd128 · ripemd160 · sha1 · sha256 +
rfc 2141 + uri_urn +
rfc 2251 + ldap · ldapx +
rfc 2255 + uri +
rfc 2289 + otp +
rfc 2396 + uri +
rfc 2554 + smtp +
rfc 2821 + smtp · smtpd +
rfc 2849 + ldapx +
rfc 3207 + smtp +
rfc 3513 + tcllib_ip +
rfc 4511 + ldap +
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 +
scanl + generator +
SCCS + rcs +
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 +
seed + tcl::chan::randseed +
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 +
service + logger +
services + ftpd · smtpd +
set + struct::queue · struct::set +
sha1 + sha1 +
sha256 + sha256 +
shortest path + struct::graph::op +
shuffle + struct::list +
simulated annealing + simulation::annealing +
simulation + simulation::random +
singleton + 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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
state (de)serialization + namespacex +
statistical distribution + simulation::random +
statistics + counter · math · math::statistics +
stdin + tcl::chan::std +
stdout + tcl::chan::std +
stochastic modelling + simulation::montecarlo +
stream cipher + rc4 +
stream copy + tcl::transform::observe +
string + textutil · textutil::adjust · textutil::expander · textutil::repeat · textutil::split · textutil::string · textutil::tabify · textutil::trim +
stringprep + stringprep · stringprep::data · unicode::data +
strongly connected component + struct::graph::op +
struct + struct::pool · struct::record +
structure + control +
structured queries + treeql +
style + doctools::html::cssdefaults +
subcommand + tepam · tepam::procedure +
subgraph + struct::graph · struct::graph::op +
subject + hook +
submitbutton + javascript +
subscriber + hook +
subsequence + struct::list +
subst + doctools::tcl::parse +
sum + sum +
swapping + struct::list +
symmetric difference + struct::set +
synchronous + cache::async +
syntax tree + grammar::me::util +
+Keywords: T +
table + doctools::toc · doctools::toc::export · doctools::toc::import · html · report +
table of contents + doctoc_intro · doctoc_plugin_apiref · doctools2toc_introduction · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json +
tabstops + textutil::tabify +
tallying + counter +
tape archive + tar +
tar + tar +
tcl + math::bigfloat · math::bignum · math::decimal +
Tcl module + docstrip_util +
Tcl syntax + doctools::tcl::parse +
tcler's wiki + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
tcllib + csv +
TclOO + oo::util +
TCLPARAM + pt::peg::to::tclparam +
TDPL + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
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 + 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 +
thumbnail + jpeg +
tie + tie · tie +
tif + tiff +
tiff + exif · tiff +
tile + map::slippy::cache · map::slippy::fetcher +
time + ntp_time +
timestamp + png +
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::randseed · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · 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 · 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 +
top-down parsing languages + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · 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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
torrent + bee +
touch + fileutil +
TPDL + grammar::me_intro +
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::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::snit · pt::tclparam::configuration::tcloo · pt_export_api · pt_import_api · pt_introduction · pt_parser_api +
transfer + transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
transformation + page_util_peg · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
transmitter + transfer::transmitter +
travelling salesman + struct::graph::op +
traversal + fileutil_traverse +
tree + grammar::me::cpu::gasm · grammar::me::util · htmlparse · struct::queue · struct::stack · struct::tree · struct::tree_v1 · treeql +
tree query language + treeql +
tree walking + page_util_flow · page_util_norm_lemon · page_util_norm_peg +
TreeQL + treeql +
trimming + textutil · textutil::trim +
type + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::mimetype · fileutil::magic::rt · snit +
+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 +
utilities + namespacex +
uuencode + uuencode +
UUID + uuid +
+Keywords: V +
vectors + math::linearalgebra +
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::randseed · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · 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 +
vwait + coroutine · coroutine::auto · smtpd +
+Keywords: W +
wais + uri +
widget + snit · snitfaq +
widget adaptors + snit · snitfaq +
wiki + doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::wiki · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::wiki +
word + doctools::tcl::parse · wip +
www + uri +
+Keywords: X +
x.208 + asn +
x.209 + asn +
x.500 + ldap +
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 +
zlib + tcl::transform::zlib +
zoom + map::slippy · map::slippy::cache · map::slippy::fetcher +
+ ADDED embedded/www/tcllib/files/apps/dtplite.html Index: embedded/www/tcllib/files/apps/dtplite.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/dtplite.html @@ -0,0 +1,408 @@ + + +dtplite - Documentation toolbox + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

dtplite(n) 1.0 tcllib "Documentation toolbox"

+

Name

+

dtplite - Lightweight DocTools Markup Processor

+
+ + +

Description

+

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

+

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

+

USE CASES

+

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

+
    +

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

    2. +

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

    3. +

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

    4. +
+

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

+

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

+
+

COMMAND LINE

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

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

+
+
path output (in)
+

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

+

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

+
(path|handle) format (in)
+

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

+
path inputfile (in)
+

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

+
+
dtplite validate inputfile
+

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

+
dtplite -o output ?options? format inputdirectory
+

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

+

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

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

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

+

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

+
+
+

OPTIONS

+

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

+
+
-exclude string
+

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

+
-ext string
+

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

+

When used multiple times only the last definition is relevant.

+
-header file
+

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

+

When used multiple times only the last definition is relevant.

+
-footer file
+

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

+

When used multiple times only the last definition is relevant.

+
-style file
+

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

+

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

+

When used multiple times only the last definition is relevant.

+
-toc path
+

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

+

When used multiple times only the last definition is relevant.

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

+
+
+

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 application it describes, will undoubtedly +contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +application and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/apps/nns.html Index: embedded/www/tcllib/files/apps/nns.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/nns.html @@ -0,0 +1,235 @@ + + +nns - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nns(n) 1.1 tcllib "Name service facility"

+

Name

+

nns - Name service facility, Commandline Client Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

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

+

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

+

USE CASES

+

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

+
    +

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

    2. +

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

    3. +
+

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

+
+

COMMAND LINE

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

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

+

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

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

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

+

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

+

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

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

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

+

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

+
nns who
+

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

+
+
+

OPTIONS

+

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

+
+
-host name|ipaddress
+

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

+
-port number
+

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

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/nnsd.html Index: embedded/www/tcllib/files/apps/nnsd.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/nnsd.html @@ -0,0 +1,203 @@ + + +nnsd - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nnsd(n) 1.0.1 tcllib "Name service facility"

+

Name

+

nnsd - Name service facility, Commandline Server Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

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

+

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

+

USE CASES

+

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

+
    +

  1. Run a nano name service on some host.

    2. +
+
+

COMMAND LINE

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

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

+

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

+
+
+

OPTIONS

+

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

+
+
-localonly bool
+

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

+
-port number
+

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

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/nnslog.html Index: embedded/www/tcllib/files/apps/nnslog.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/nnslog.html @@ -0,0 +1,206 @@ + + +nnslog - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nnslog(n) 1.0 tcllib "Name service facility"

+

Name

+

nnslog - Name service facility, Commandline Logging Client Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

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

+

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

+

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

+

USE CASES

+

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

+
    +

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

    2. +
+
+

COMMAND LINE

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

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

+

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

+
+
+

OPTIONS

+

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

+
+
-host name|ipaddress
+

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

+
-port number
+

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

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/page.html Index: embedded/www/tcllib/files/apps/page.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/page.html @@ -0,0 +1,473 @@ + + +page - Development Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page(n) 1.0 tcllib "Development Tools"

+

Name

+

page - Parser Generator

+
+ + +

Description

+

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

+

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

+

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

+

COMMAND LINE

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

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

+

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

+

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

+
+
path input (in)
+

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

+
path output (in)
+

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

+

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

+

If the argument is missing - is assumed.

+
+
+
+

OPERATION

+

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

+
+

OPTIONS

+

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

+

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

+

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

+
-c peg
+

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

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

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

+
--version
+
+
-V
+

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

+
-P
+

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

+
-T
+

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

+
-D
+

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

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

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

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

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

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

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

+
-a
+
+
--append
+

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

+
-p
+
+
--prepend
+

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

+
--reset
+

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

+
-c file
+
+
--configuration file
+

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

+

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

+
+
+

PLUGINS

+

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

+

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

+

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

+
+
-c name
+

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

+

We have one predefined plugin:

+
+
peg
+

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

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

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

+

We have five predefined plugins:

+
+
peg
+

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

+
hb
+

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

+
ser
+

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

+
lemon
+

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

+
treeser
+

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

+
+
-w name
+

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

+

We have eight predefined plugins:

+
+
identity
+

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

+
null
+

Generates nothing, and ignores the incoming data structure.

+
tree
+

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

+
peg
+

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

+
tpc
+

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

+
hb
+

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

+
ser
+

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

+
me
+

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

+
+
-t name
+

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

+

We have two predefined plugins:

+
+
reach
+

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

+
use
+

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

+
+
+
+

PLUGIN LOCATIONS

+

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

+
    +

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

    2. +

  2. The environment variable PAGE_PLUGINS

    3. +

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

    4. +

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

    5. +
+

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

+
    +

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

    2. +

  2. The environment variable PAGE_<TYPE>_PLUGINS

    3. +

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

    4. +

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

    5. +
+

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

+
    +

  1. reader

    2. +

  2. writer

    3. +

  3. transform

    4. +

  4. config

    5. +
+

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

+

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

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

page::pluginmgr

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/apps/tcldocstrip.html Index: embedded/www/tcllib/files/apps/tcldocstrip.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/apps/tcldocstrip.html @@ -0,0 +1,276 @@ + + +tcldocstrip - Textprocessing toolbox + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

+

Name

+

tcldocstrip - Tcl-based Docstrip Processor

+
+ + +

Description

+

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

+

tcldocstrip is based upon the package docstrip.

+

USE CASES

+

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

+
    +

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

    2. +

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

    3. +

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

    4. +
+
+

COMMAND LINE

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

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

+
+
path output (in)
+

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

+

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

+
path inputfile (in)
+

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

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

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

+

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

+
tcldocstrip -guards input
+

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

+
+
+

OPTIONS

+

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

+
+
-metaprefix string
+

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

+

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

+
-onerror mode
+

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

+

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

+
+
ignore
+

Just ignore the error; continue as if nothing happened.

+
puts
+

Write an error message to stderr, then continue processing.

+
throw
+

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

+
+
-trimlines bool
+

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

+

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

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

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

+

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

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/aes/aes.html Index: embedded/www/tcllib/files/modules/aes/aes.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/aes/aes.html @@ -0,0 +1,265 @@ + + +aes - Advanced Encryption Standard (AES) + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

aes - Implementation of the AES block cipher

+
+ + +

Description

+

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

+
+

COMMANDS

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

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

+

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

+

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

+

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

+
+
+

PROGRAMMING INTERFACE

+

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

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

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

+
::aes::Encrypt Key data
+

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

+
::aes::Decrypt Key data
+

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

+
::aes::Reset Key iv
+

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

+
::aes::Final Key
+

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

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

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

+
Cipher Block Chaining (CBC)
+

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

+
+
+

EXAMPLES

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

REFERENCES

+
    +

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

    2. +
+
+

AUTHORS

+

Thorsten Schloermann, Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/amazon-s3/S3.html Index: embedded/www/tcllib/files/modules/amazon-s3/S3.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/amazon-s3/S3.html @@ -0,0 +1,1261 @@ + +S3 - Amazon S3 Web Service Utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

S3 - Amazon S3 Web Service Interface

+
+ +

Synopsis

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

Description

+

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

+

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

+

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

+

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

+
+

ERROR REPORTING

+

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

+
+
usage
+

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

+
local
+

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

+
socket
+

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

+
remote
+

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

+
notyet
+

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

+
xml
+

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

+
+
+

COMMANDS

+

This package provides several separate levels of complexity.

+
    +

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

    • +

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

    • +

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

    • +

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

    • +

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

    • +
+

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

+
+

LOW LEVEL COMMANDS

+

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

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

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

+

The following options are accepted:

+
+
-reset boolean
+

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

+
-retries integer
+

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

+
-accesskeyid idstring
+
+
-secretaccesskey idstring
+

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

+
-service-access-point FQDN
+

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

+
-slop-seconds integer
+

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

+
-use-tls boolean
+

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

+
-bucket-prefix string
+

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

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

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

+
-default-separator string
+

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

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

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

+
-default-bucket bucketname
+

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

+
+
S3::SuggestBucket ?name?
+

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

+
S3::REST dict
+

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

+

The possible input keys are these:

+
+
verb GET|PUT|DELETE|HEAD
+

This required item indicates the verb to be used.

+
resource string
+

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

+
?rtype torrent|acl?
+

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

+
?parameters dict?
+

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

+
?headers dict?
+

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

+
?inbody contentstring?
+

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

+
?infile filename?
+

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

+
?S3chan channel?
+

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

+
?outchan channel?
+

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

+
?resultvar varname?
+

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

+
?throwsocket throw|return?
+

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

+
+

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

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

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

+
httpstatus threedigits
+

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

+
httpmessage text
+

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

+
outbody contentstring
+

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

+
outheaders dict
+

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

+
+
+
+

HIGH LEVEL COMMANDS

+

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

+

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

+

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

+
+
-blocking boolean
+

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

+
-parse-xml xmlstring
+

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

+
-bucket bucketname
+

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

+
-resource resourcename
+

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

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

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

+
+
always
+

Always copy the data. This is the default.

+
never
+

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

+
exists
+

Copy the data only if the destination already exists.

+
missing
+

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

+
newer
+

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

+
date
+

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

+
checksum
+

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

+
different
+

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

+
+

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

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

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

+
+
-blocking boolean
+

See above for standard definition.

+
-parse-xml xmlstring
+

See above for standard definition.

+
-result-type REST
+

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

+
-result-type xml
+

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

+
-result-type pxml
+

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

+
-result-type dict
+

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

+
+
Owner/ID
+

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

+
Owner/DisplayName
+

The Amazon AWS ID's Display Name.

+
Bucket/Name
+

A list of names, one for each bucket.

+
Bucket/CreationDate
+

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

+
+
-result-type names
+

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

+
-result-type owner
+

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

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

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

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

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

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

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

+
+
-bucket bucketname
+

The standard bucket argument.

+
-blocking boolean
+

The standard blocking argument.

+
-parse-xml xmlstring
+

The standard parse-xml argument.

+
-max-count integer
+

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

+
-prefix prefixstring
+

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

+
-delimiter delimiterstring
+

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

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

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

+
+
REST
+

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

+
xml
+

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

+
pxml
+

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

+
names
+

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

+
dict
+

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

+
+
Name
+

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

+
Prefix
+

From the final call to S3::REST.

+
Marker
+

From the final call to S3::REST.

+
MaxKeys
+

From the final call to S3::REST.

+
IsTruncated
+

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

+
NextMarker
+

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

+
Key
+

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

+
LastModified
+

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

+
ETag
+

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

+
Size
+

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

+
Owner/ID
+

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

+
Owner/DisplayName
+

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

+
CommonPrefixes/Prefix
+

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

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

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

+
+
-bucket
+

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

+
-resource
+

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

+
-blocking
+

The standard blocking flag.

+
-file
+

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

+
-content
+

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

+
-acl
+

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

+
-x-amz-meta-*
+

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

+
-content-type
+

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

+
-compare
+

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

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

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

+
+
-bucket
+

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

+
-resource
+

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

+
-blocking
+

The standard blocking flag.

+
-file
+

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

+
-timestamp
+

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

+
-content
+

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

+
-compare
+

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

+
-headers
+

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

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

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

+
+
-bucket
+

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

+
-resource
+

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

+
-blocking
+

The standard blocking flag.

+
-dict
+

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

+
-headers
+

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

+
-status
+

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

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

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

+
+
-blocking boolean
+

See above for standard definition.

+
-bucket
+

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

+
-resource
+

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

+
-parse-xml xml
+

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

+
-result-type REST
+

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

+
-result-type xml
+

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

+
-result-type pxml
+

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

+
-result-type dict
+

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

+

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

+

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

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

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

+
+
-blocking boolean
+

See above for standard definition.

+
-bucket
+

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

+
-resource
+

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

+
-owner
+

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

+
-acl
+

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

+

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

+

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

+

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

+

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

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

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

+
+
-bucket
+

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

+
-resource
+

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

+
-blocking
+

The standard blocking flag.

+
-status
+

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

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

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

+
+
-bucket
+

This names the bucket into which data will be pushed.

+
-directory
+

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

+
-prefix
+

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

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

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

+
-blocking
+

This is the standard blocking option.

+
-compare
+

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

+
-x-amz-meta-*
+

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

+
-acl
+

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

+
-delete
+

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

+
-error
+

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

+
+
throw
+

The error is rethrown with the same errorCode.

+
break
+

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

+
continue
+

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

+
+
-progress
+

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

+
+

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

+

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

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

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

+

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

+
+
-bucket
+

This names the bucket from which data will be pulled.

+
-directory
+

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

+
-prefix
+

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

+
-blocking
+

This is the standard blocking option.

+
-compare
+

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

+
-timestamp
+

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

+
-delete
+

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

+
-error
+

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

+
-progress
+

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

+
+

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

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

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

+
+
-bucket
+

The bucket from which resources will be deleted.

+
-blocking
+

The standard blocking option.

+
-prefix
+

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

+
-error
+

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

+
-progress
+

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

+
+

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

+
+
+

LIMITATIONS

+
    +

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

    • +

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

    • +

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

    • +

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

    • +

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

    • +

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

    • +

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

    • +

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

    • +
+
+

USAGE SUGGESTIONS

+

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

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

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

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

FUTURE DEVELOPMENTS

+

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

+

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

+

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

+

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

+
+

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

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/amazon-s3/xsxp.html Index: embedded/www/tcllib/files/modules/amazon-s3/xsxp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/amazon-s3/xsxp.html @@ -0,0 +1,243 @@ + +xsxp - Amazon S3 Web Service Utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

xsxp - eXtremely Simple Xml Parser

+
+ + +

Description

+

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

+

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

+

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

+

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

+
+

COMMANDS

+

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

+
+
xsxp::parse xml
+

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

+
    +

  • The first element is the name of the tag.

    • +

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

    • +

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

    • +

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

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

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

+

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

+

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

+
+
%ALL
+

returns the entire selected element.

+
%TAGNAME
+

returns lindex 0 of the selected element.

+
%ATTRIBUTES
+

returns index 1 of the selected element.

+
%CHILDREN
+

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

+
%PCDATA
+

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

+
%PCDATA?
+

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

+
+

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

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

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

+

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

+
xsxp::only pxml tagname
+

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

+
xsxp::prettyprint pxml ?chan?
+

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

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/asn/asn.html Index: embedded/www/tcllib/files/modules/asn/asn.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/asn/asn.html @@ -0,0 +1,504 @@ + + +asn - ASN.1 processing + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

asn - ASN.1 BER encoder/decoder

+
+ +

Synopsis

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

Description

+

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

+

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

+

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

+

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

+
+

PUBLIC API

+

ENCODER

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

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

+
::asn::asnSequenceFromList elist
+

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

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

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

+
::asn::asnSetFromList elist
+

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

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

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

+
::asn::asnApplication appNumber data
+

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

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

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

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

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

+
::asn::asnInteger number
+

Returns the encoded form of the specified integer +number.

+
::asn::asnEnumeration number
+

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

+
::asn::asnBoolean bool
+

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

+
::asn::asnContext context data
+

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

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

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

+
::asn::asnObjectIdentifier idlist
+

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

+
::asn::asnUTCTime utcstring
+

Returns the encoded form of the specified UTC time string.

+
::asn::asnNull
+

Returns the NULL encoding.

+
::asn::asnBitString string
+

Returns the encoded form of the specified string.

+
::asn::asnOctetString string
+

Returns the encoded form of the specified string.

+
::asn::asnNumericString string
+

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

+
::asn::asnPrintableString string
+

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

+
::asn::asnIA5String string
+

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

+
::asn::asnBMPString string
+

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

+
::asn::asnUTF8String string
+

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

+
::asn::asnString string
+

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

+
::asn::defaultStringType ?type?
+

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

+
+
+

DECODER

+

General notes:

+
    +

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

    2. +

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

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

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

+
::asn::asnGetLength data_var length_var
+

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

+
::asn::asnGetResponse chan data_var
+

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

+
::asn::asnGetInteger data_var int_var
+

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

+
::asn::asnGetEnumeration data_var enum_var
+

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

+
::asn::asnGetOctetString data_var string_var
+

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

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

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

+

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

+

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

+
::asn::asnGetNumericString data_var string_var
+

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

+
::asn::asnGetPrintableString data_var string_var
+

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

+
::asn::asnGetIA5String data_var string_var
+

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

+
::asn::asnGetBMPString data_var string_var
+

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

+
::asn::asnGetUTF8String data_var string_var
+

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

+
::asn::asnGetUTCTime data_var utc_var
+

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

+
::asn::asnGetBitString data_var bits_var
+

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

+
::asn::asnGetObjectIdentifier data_var oid_var
+

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

+
::asn::asnGetBoolean data_var bool_var
+

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

+
::asn::asnGetNull data_var
+

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

+
::asn::asnGetSequence data_var sequence_var
+

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

+

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

+
::asn::asnGetSet data_var set_var
+

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

+

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

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

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

+

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

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

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

+

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

+
+
+

HANDLING TAGS

+

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

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

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

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

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

+
::asn::asnRetag data_var newTag
+

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

+
+
+
+

EXAMPLES

+

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

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32.html Index: embedded/www/tcllib/files/modules/base32/base32.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base32/base32.html @@ -0,0 +1,200 @@ + + +base32 - Base32 encoding + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

base32(n) 0.1 tcllib "Base32 encoding"

+

Name

+

base32 - base32 standard encoding

+
+ +

Synopsis

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

Description

+

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

+
+

API

+
+
::base32::encode string
+

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

+
::base32::decode estring
+

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

+

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

+

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

+
    +

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

    2. +

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

    3. +

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

    4. +

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

    5. +
+
+
+

Code map

+

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

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

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32core.html Index: embedded/www/tcllib/files/modules/base32/base32core.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base32/base32core.html @@ -0,0 +1,190 @@ + + +base32::core - Base32 encoding + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

base32::core - Expanding basic base32 maps

+
+ +

Synopsis

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

Description

+

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

+

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

+
+

API

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

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

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

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

+

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

+

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

+
    +

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

    2. +

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

    3. +

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

    4. +
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32hex.html Index: embedded/www/tcllib/files/modules/base32/base32hex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base32/base32hex.html @@ -0,0 +1,202 @@ + + +base32::hex - Base32 encoding + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

base32::hex - base32 extended hex encoding

+
+ +

Synopsis

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

Description

+

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

+
+

API

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

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

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

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

+

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

+

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

+
    +

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

    2. +

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

    3. +

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

    4. +

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

    5. +
+
+
+

Code map

+

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

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

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/ascii85.html Index: embedded/www/tcllib/files/modules/base64/ascii85.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base64/ascii85.html @@ -0,0 +1,198 @@ + +ascii85 - Text encoding & decoding binary data + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

ascii85 - ascii85-encode/decode binary data

+
+ +

Synopsis

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

Description

+

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

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

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

+

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

+

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

+
::ascii85::decode string
+

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

+
+
+

EXAMPLES

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

References

+
    +

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

    2. +

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

    3. +
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/base64.html Index: embedded/www/tcllib/files/modules/base64/base64.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base64/base64.html @@ -0,0 +1,192 @@ + +base64 - Text encoding & decoding binary data + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

base64 - base64-encode/decode binary data

+
+ +

Synopsis

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

Description

+

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

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

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

+

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

+

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

+

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

+
::base64::decode string
+

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

+
+
+

EXAMPLES

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

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/uuencode.html Index: embedded/www/tcllib/files/modules/base64/uuencode.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base64/uuencode.html @@ -0,0 +1,214 @@ + +uuencode - Text encoding & decoding binary data + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

uuencode - UU-encode/decode binary data

+
+ + +

Description

+

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

+
+
::uuencode::encode string
+

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

+
::uuencode::decode string
+

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

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

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

+
+
+

OPTIONS

+
+
-filename name
+

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

+
-name string
+

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

+
-mode octal
+

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

+
+
+

EXAMPLES

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

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/yencode.html Index: embedded/www/tcllib/files/modules/base64/yencode.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/base64/yencode.html @@ -0,0 +1,207 @@ + +yencode - Text encoding & decoding binary data + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

yencode - Y-encode/decode binary data

+
+ + +

Description

+

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

+
+
::yencode::encode string
+

returns the yEnc encoded data.

+
::yencode::decode string
+

Decodes the given yEnc encoded data.

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

Encode a file or block of data.

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

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

+
+
+

OPTIONS

+
+
-filename name
+

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

+
-name string
+

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

+
-line integer
+

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

+
-crc32 boolean
+

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

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

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/bee/bee.html Index: embedded/www/tcllib/files/modules/bee/bee.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bee/bee.html @@ -0,0 +1,378 @@ + + +bee - BitTorrent + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

bee(n) 0.1 tcllib "BitTorrent"

+

Name

+

bee - BitTorrent Serialization Format Encoder/Decoder

+
+ + +

Description

+

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

+
+

PUBLIC API

+

ENCODER

+

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

+
+
::bee::encodeString string
+

Returns the bee-encoding of the string.

+
::bee::encodeNumber integer
+

Returns the bee-encoding of the integer number.

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

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

+
::bee::encodeList list
+

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

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

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

+
::bee::encodeDict dict
+

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

+
+
+

DECODER

+

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

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

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

+

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

+

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

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

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

+

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

+
+
string
+

A list containing three elements:

+
    +

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

    • +

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

    • +

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

    • +
+

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

+
integer
+

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

+
list
+

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

+
dictionary
+

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

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

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

+
+
-command
+

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

+
+
cmdprefix eof token
+

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

+
cmdprefix error token message
+

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

+
cmdprefix value token value
+

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

+
+
-exact
+

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

+

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

+
-prefix
+

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

+
+
::bee::decodeCancel token
+

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

+
::bee::decodePush token string
+

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

+
+
+
+

FORMAT DEFINITION

+

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

+
+
String S
+

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

+
Integer N
+

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

+
List v1 ... vn
+

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

+
Dict k1 -> v1 ...
+

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

+

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

+
+

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

+
+
i
+

Integer.

+
l
+

List.

+
d
+

Dictionary.

+
[0-9]
+

String.

+
+

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

+
+ +

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench.html Index: embedded/www/tcllib/files/modules/bench/bench.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench.html @@ -0,0 +1,335 @@ + + +bench - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

bench - bench - Processing benchmark suites

+
+ + +

Description

+

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

+

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

+
+

PUBLIC API

+

Benchmark execution

+
+
::bench::locate pattern paths
+

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

+

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

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

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

+

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

+

The available options are

+
+
-errors flag
+

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

+
-threads n
+

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

+
-match pattern
+

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

+
-rmatch pattern
+

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

+
-iters n
+

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

+
-pkgdir path
+

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

+

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

+

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

+

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

+
+
::bench::versions interp_list
+

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

+

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

+
+
+

Result manipulation

+
+
::bench::del bench_result column
+

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

+

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

+

The column is identified by an integer number.

+
::bench::edit bench_result column newvalue
+

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

+

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

+

The column is identified by an integer number.

+
::bench::merge bench_result...
+

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

+

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

+
::bench::norm bench_result column
+

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

+

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

+

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

+

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

+

The column is identified by an integer number.

+
::bench::out::raw bench_result
+

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

+

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

+

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

+
+
+

Result format

+

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

+

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

+
+
{interp *}
+

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

+

The associated value is the version of the Tcl interpreter.

+
{desc *}
+

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

+

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

+
{usec * *}
+

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

+

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

+
+
ERR
+

Benchmark could not be executed, failed with a Tcl error.

+
BAD_RES
+

The benchmark could be executed, however the result from its body did +not match the declared expectations.

+
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

bench_intro, bench_lang_intro, bench_lang_spec, bench_read, bench_wcsv, bench_wtext

+
+ +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_intro.html @@ -0,0 +1,175 @@ + + +bench_intro - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

bench_intro - bench introduction

+
+ +

Description

+

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

+
    +

  1. A tcl based language for the declaration of test cases. A test case is +represented by a tcl command declaring the various parts needed to +execute it, like setup, cleanup, the commands to test, etc.

    2. +

  2. A package providing the ability to execute test cases written in that +language.

    3. +
+

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

+
    +

  1. A writer of benchmarks has to understand the bench language +itself. A beginner to bench should read the more informally written +bench language introduction first. Having digested this the +formal bench language specification should become +understandable. A writer experienced with bench may only need this +last document from time to time, to refresh her memory.

    2. +

  2. A user of benchmark suites written in the bench language +has to know which tools are available for use. +At the bottom level sits the package bench, providing the +basic facilities to read and execute files containing benchmarks +written in the bench language, and to manipulate benchmark results.

    3. +
+
+

HISTORICAL NOTES

+

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

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category bench of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_lang_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_lang_intro.html @@ -0,0 +1,251 @@ + + +bench_lang_intro - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

bench_lang_intro - bench language introduction

+
+ +

Description

+

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

+

Fundamentals

+

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

+
+

Basics

+

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

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

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

+
+

Pre- and postprocessing

+

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

+

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

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

Advanced pre- and postprocessing

+

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

+

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

+

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

+

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

+

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

+

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

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

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of benchmarks, he should be fortified enough to be able +to understand the formal bench language specfication. It will +also serve as the detailed specification and cheat sheet for all +available commands and their syntax.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category bench of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_lang_spec.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_spec.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_lang_spec.html @@ -0,0 +1,233 @@ + + +bench_lang_spec - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

bench_lang_spec(n) 1.0 tcllib "Documentation tools"

+

Name

+

bench_lang_spec - bench language specification

+
+ + +

Description

+

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

+
+

Commands

+
+
bench_rm path...
+

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

+
bench_tmpfile
+

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

+

The base location of the temporary files is platform dependent:

+
+
Unix, and indeterminate platform
+

"/tmp"

+
Windows
+

$TEMP

+
Anything else
+

The current working directory.

+
+
bench options...
+

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

+
+
-body script
+

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

+
-desc msg
+

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

+

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

+
-ipost script
+

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

+
-ipre script
+

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

+
-iterations num
+

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

+

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

+
-post script
+

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

+
-pre script
+

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

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_read.html Index: embedded/www/tcllib/files/modules/bench/bench_read.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_read.html @@ -0,0 +1,184 @@ + + +bench::in - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

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

+
+ +

Synopsis

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

Description

+

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

+

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

+

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

+
+

PUBLIC API

+
+
::bench::in::read file
+

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

+
+
bench::out::raw
+

Provided by package bench.

+
bench::out::csv
+

Provided by package bench::out::csv.

+
bench::out::text
+

Provided by package bench::out::text.

+
+

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

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_wcsv.html Index: embedded/www/tcllib/files/modules/bench/bench_wcsv.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_wcsv.html @@ -0,0 +1,176 @@ + + +bench::out::csv - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

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

+
+ +

Synopsis

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

Description

+

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

+

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

+

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

+
+

PUBLIC API

+
+
::bench::out::csv bench_result
+

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

+

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

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_wtext.html Index: embedded/www/tcllib/files/modules/bench/bench_wtext.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bench/bench_wtext.html @@ -0,0 +1,176 @@ + + +bench::out::text - Benchmarking/Performance tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

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

+
+ +

Synopsis

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

Description

+

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

+

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

+

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

+
+

PUBLIC API

+
+
::bench::out::text bench_result
+

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

+

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

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bibtex/bibtex.html Index: embedded/www/tcllib/files/modules/bibtex/bibtex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/bibtex/bibtex.html @@ -0,0 +1,255 @@ + + +bibtex - bibtex + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

bibtex(n) 0.5 tcllib "bibtex"

+

Name

+

bibtex - Parse bibtex files

+
+ + +

Description

+

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

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

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

+
::bibtex::parse text
+

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

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

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

+

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

+
+
cmd token parseresult
+

The parse result will have the structure explained above, for the +simpler forms of the parser.

+
+

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

+
::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? (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.

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

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/blowfish/blowfish.html Index: embedded/www/tcllib/files/modules/blowfish/blowfish.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/blowfish/blowfish.html @@ -0,0 +1,264 @@ + + +blowfish - Blowfish Block Cipher + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

blowfish(n) 1.0.3 tcllib "Blowfish Block Cipher"

+

Name

+

blowfish - Implementation of the Blowfish block cipher

+
+ + +

Description

+

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

+
+

COMMANDS

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

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

+

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

+

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

+

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

+
+
+

PROGRAMMING INTERFACE

+
+
::blowfish::Init mode keydata iv
+

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

+
::blowfish::Encrypt Key data
+

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

+
::blowfish::Decrypt Key data
+

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

+
::blowfish::Reset Key iv
+

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

+
::blowfish::Final Key
+

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

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

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

+
Cipher Block Chaining (CBC)
+

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

+
+
+

EXAMPLES

+
+% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!"
+d0d8f27e7a374b9e2dbd9938dd04195a
+
+
+ set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv]
+ append ciphertext [blowfish::Encrypt $Key $plaintext]
+ append ciphertext [blowfish::Encrypt $Key $additional_plaintext]
+ blowfish::Final $Key
+
+
+

REFERENCES

+
    +

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

    2. +
+
+

AUTHORS

+

Frank Pilhofer, Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

3des, des, rc4

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/cache/async.html Index: embedded/www/tcllib/files/modules/cache/async.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/cache/async.html @@ -0,0 +1,238 @@ + +cache::async - In-memory caches + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

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

+

Name

+

cache::async - Asynchronous in-memory cache

+
+ + +

Description

+

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

+
+

API

+

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

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

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

+

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

+

The only supported option is

+
+
-full-async-results
+

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

+
+
+

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

+
+
objectName get key donecmdprefix
+

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

+

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

+
    +

  1. The string set, the key, and the value.

    2. +

  2. The string unset, and the key.

    3. +
+

These two possibilities are used to either signal the value for the +key, or that the key has no value defined for it. The +latter is distinct from the cache not knowing about the key.

+

For a cache object configured to be fully asynchronous (default) the +donecmdprefix is always run in an idle-handler, decoupling it +from the request. Otherwise the callback will be invoked synchronously +when the key is known to the cache at the time of the +invokation.

+

Another important part of the cache's behaviour, as it is asynchronous +it is possible that multiple get requests are issued for the +same key before it can respond. In that case the cache will +issue only one data request to the provider, for the first of these, +and suspend the others, and then notify all of them when the data +becomes available.

+
objectName set key value
+
+
objectName unset key
+

These two methods are provided to allow users of the cache to make +keys known to the cache, as either having a value, or as +undefined.

+

It is expected that the data provider (see commandprefix of the +constructor) uses them in response to data requests for unknown keys.

+

Note how this matches the cache's own API towards its caller, calling +the donecmd of get-requests issued to itself with +either "set key value" or "unset key", versus issuing +get-requests to its own provider with itself in the place of +the donecmd, expecting to be called with either "set key value" +or "unset key".

+

This also means that these methods invoke the donecmd of all +get-requests waiting for information about the modified +key.

+
objectName exists key
+

This method queries the cache for knowledge about the key and +returns a boolean value. The result is true if the key is +known, and false otherwise.

+
objectName clear ?key?
+

This method resets the state of either the specified key or of +all keys known to the cache, making it unkown. This forces future +get-requests to reload the information from the provider.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +
ADDED embedded/www/tcllib/files/modules/clock/iso8601.html Index: embedded/www/tcllib/files/modules/clock/iso8601.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/clock/iso8601.html @@ -0,0 +1,166 @@ + + +clock_iso8601 - Date/Time Utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

clock_iso8601(n) 0.1 tcllib "Date/Time Utilities"

+

Name

+

clock_iso8601 - Parsing ISO 8601 dates/times

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require clock::iso8601 ?0.1?
    • +
+ +
+
+

Description

+

This package provides functionality to parse dates and times in +ISO 8601 format.

+
+
::clock::iso8601 parse_date date options...
+

This command parses an ISO8601 date string in an unknown variant and +returns the given date/time in seconds since epoch.

+

The acceptable options are +-base, +-gmt, +-locale, and +-timezone +of the builtin command clock scan.

+
::clock::iso8601 parse_time time options...
+

This command parses a full ISO8601 timestamp string (date and time) in +an unknown variant and returns the given time in seconds since epoch.

+

The acceptable options are +-base, +-gmt, +-locale, and +-timezone +of the builtin command clock scan.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/clock/rfc2822.html Index: embedded/www/tcllib/files/modules/clock/rfc2822.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/clock/rfc2822.html @@ -0,0 +1,151 @@ + + +clock_rfc2822 - Date/Time Utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

clock_rfc2822(n) 0.1 tcllib "Date/Time Utilities"

+

Name

+

clock_rfc2822 - Parsing ISO 8601 dates/times

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require clock::rfc2822 ?0.1?
    • +
+ +
+
+

Description

+

This package provides functionality to parse dates in +RFC 2822 format.

+
+
::clock::rfc2822 parse_date date
+

This command parses an RFC2822 date string and returns +the given date in seconds since epoch. An error is thrown +if the command is unable to parse the date.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/cmdline/cmdline.html Index: embedded/www/tcllib/files/modules/cmdline/cmdline.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/cmdline/cmdline.html @@ -0,0 +1,262 @@ + +cmdline - Command line and option processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

cmdline(n) 1.3.3 tcllib "Command line and option processing"

+

Name

+

cmdline - Procedures to process command lines and options.

+
+ + +

Description

+

This package provides commands to parse command lines and options.

+
+

::argv handling

+

One of the most common variables this package will be used with is +::argv, which holds the command line of the current +application. This variable has a companion ::argc which is +initialized to the number of elements in ::argv at the beginning +of the application.

+

The commands in this package will not modify the ::argc +companion when called with ::argv. Keeping the value consistent, +if such is desired or required, is the responsibility of the caller.

+
+

API

+
+
::cmdline::getopt argvVar optstring optVar valVar
+

This command works in a fashion like the standard C based getopt +function. Given an option string and a pointer to an array of args +this command will process the first argument and return info on how to +proceed. The command returns 1 if an option was found, 0 if no more +options were found, and -1 if an error occurred.

+

argvVar contains the name of the list of arguments to +process. If options are found the list is modified and the processed +arguments are removed from the start of the list.

+

optstring contains a list of command options that the +application will accept. If the option ends in ".arg" the command +will use the next argument as an argument to the option. 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 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.

+
+
+

EXAMPLES

+
+        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:"
+        array set params [::cmdline::getoptions argv $options $usage]
+        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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/comm/comm.html Index: embedded/www/tcllib/files/modules/comm/comm.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/comm/comm.html @@ -0,0 +1,1011 @@ + +comm - Remote communication + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

comm(n) 4.6.2 tcllib "Remote communication"

+

Name

+

comm - A remote communication facility for Tcl (8.3 and later)

+
+ + +

Description

+

The comm command provides an inter-interpreter remote +execution facility much like Tk's send(n), except that it uses +sockets rather than the X server for the communication path. As a +result, comm works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path.

+

These commands work just like send and winfo interps :

+
+    ::comm::comm send ?-async? id cmd ?arg arg ...?
+    ::comm::comm interps
+
+

This is all that is really needed to know in order to use +comm

+

Commands

+

The package initializes ::comm::comm as the default chan.

+

comm names communication endpoints with an id unique +to each machine. Before sending commands, the id of another +interpreter is needed. Unlike Tk's send, comm doesn't +implicitly know the id's of all the interpreters on the system. +The following four methods make up the basic comm interface.

+
+
::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?
+

This invokes the given command in the interpreter named by id. The +command waits for the result and remote errors are returned unless the +-async or -command option is given. If -async +is given, send returns immediately and there is no further notification of +result. If -command is used, callback specifies a command +to invoke when the result is received. These options are mutually +exclusive. The callback will receive arguments in the form +-option value, suitable for array set. +The options are: -id, the comm id of the interpreter that received +the command; -serial, a unique serial for each command sent to a +particular comm interpreter; -chan, the comm channel name; +-code, the result code of the command; -errorcode, the +errorcode, if any, of the command; -errorinfo, the errorinfo, if +any, of the command; and -result, the return value of the command. +If connection is lost before a reply is received, the callback will be +invoked with a connection lost message with -code equal to -1. When +-command is used, the command returns the unique serial for the +command.

+
::comm::comm self
+

Returns the id for this channel.

+
::comm::comm interps
+

Returns a list of all the remote id's to which this channel is +connected. comm learns a new remote id when a command +is first issued it, or when a remote id first issues a command +to this comm channel. ::comm::comm ids is an alias for this +method.

+
::comm::comm connect ?id?
+

Whereas ::comm::comm send will automatically connect to the +given id, this forces a connection to a remote id without +sending a command. After this, the remote id will appear in +::comm::comm interps.

+
+
+

Eval Semantics

+

The evaluation semantics of ::comm::comm send are intended to +match Tk's send exactly. This means that comm +evaluates arguments on the remote side.

+

If you find that ::comm::comm send doesn't work for a +particular command, try the same thing with Tk's send and see if the +result is different. If there is a problem, please report it. For +instance, there was had one report that this command produced an +error. Note that the equivalent send command also produces the +same error.

+
+    % ::comm::comm send id llength {a b c}
+    wrong # args: should be "llength list"
+    % send name llength {a b c}
+    wrong # args: should be "llength list"
+
+

The eval hook (described below) can be used to change from +send's double eval semantics to single eval semantics.

+
+

Multiple Channels

+

More than one comm channel (or listener) can be created +in each Tcl interpreter. This allows flexibility to create full and +restricted channels. For instance, hook scripts are specific +to the channel they are defined against.

+
+
::comm::comm new chan ?name value ...?
+

This creates a new channel and Tcl command with the given channel +name. This new command controls the new channel and takes all the +same arguments as ::comm::comm. Any remaining arguments are +passed to the config method. The fully qualified channel +name is returned.

+
::comm::comm channels
+

This lists all the channels allocated in this Tcl interpreter.

+
+

The default configuration parameters for a new channel are:

+
+    "-port 0 -local 1 -listen 0 -silent 0"
+
+

The default channel ::comm::comm is created with:

+
+    "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
+
+
+

Channel Configuration

+

The config method acts similar to fconfigure in that it +sets or queries configuration variables associated with a channel.

+
+
::comm::comm config
+
+
::comm::comm config name
+
+
::comm::comm config ?name value ...?
+

When given no arguments, config returns a list of all variables +and their value With one argument, config returns the value of +just that argument. With an even number of arguments, the given +variables are set to the given values.

+
+

These configuration variables can be changed (descriptions of them are +elsewhere in this manual page):

+
+
-listen ?0|1?
+
+
-local ?0|1?
+
+
-port ?port?
+
+
-silent ?0|1?
+
+
-socketcmd ?commandname?
+
+
-interp ?interpreter?
+
+
-events ?eventlist?
+
+
+

These configuration variables are read only:

+
+
-chan chan
+
+
-serial n
+
+
-socket sockIn
+
+
+

When config changes the parameters of an existing channel (with +the exception of -interp and -events), it closes and +reopens the listening socket. +An automatically assigned channel id will change when this +happens. +Recycling the socket is done by invoking ::comm::comm abort, +which causes all active sends to terminate.

+
+

Id/port Assignments

+

comm uses a TCP port for endpoint id. The +interps (or ids) method merely lists all the TCP ports +to which the channel is connected. By default, each channel's +id is randomly assigned by the operating system (but usually +starts at a low value around 1024 and increases each time a new socket +is opened). This behavior is accomplished by giving the +-port config option a value of 0. Alternately, a specific +TCP port number may be provided for a given channel. As a special +case, comm contains code to allocate a a high-numbered TCP port +(>10000) by using -port {}. Note that a channel won't be +created and initialized unless the specific port can be allocated.

+

As a special case, if the channel is configured with +-listen 0, then it will not create a listening socket and +will use an id of 0 for itself. Such a channel is only good +for outgoing connections (although once a connection is established, +it can carry send traffic in both directions). +As another special case, if the channel is configured with +-silent 0, then the listening side will ignore connection +attempts where the protocol negotiation phase failed, instead of +throwing an error.

+
+

Execution Environment

+

A communication channel in its default configuration will use the +current interpreter for the execution of all received scripts, and of +the event scripts associated with the various hooks.

+

This insecure setup can be changed by the user via the two options +-interp, and -events.

+

When -interp is set all received scripts are executed in the +slave interpreter specified as the value of the option. This +interpreter is expected to exist before configuration. I.e. it is the +responsibility of the user to create it. However afterward the +communication channel takes ownership of this interpreter, and will +destroy it when the communication channel is destroyed. +Note that reconfiguration of the communication channel to either a +different interpreter or the empty string will release the ownership +without destroying the previously configured interpreter. The +empty string has a special meaning, it restores the default behaviour +of executing received scripts in the current interpreter.

+

Also of note is that replies and callbacks (a special form of +reply) are not considered as received scripts. They are +trusted, part of the internal machinery of comm, and therefore always +executed in the current interpreter.

+

Even if an interpreter has been configured as the execution +environment for received scripts the event scripts associated with the +various hooks will by default still be executed in the current +interpreter. To change this use the option -events to declare +a list of the events whose scripts should be executed in the declared +interpreter as well. The contents of this option are ignored if the +communication channel is configured to execute received scripts in the +current interpreter.

+
+

Remote Interpreters

+

By default, each channel is restricted to accepting connections from +the local system. This can be overridden by using the +-local 0 configuration option For such channels, the +id parameter takes the form { id host }.

+

WARNING: The host must always be specified in the same +form (e.g., as either a fully qualified domain name, plain hostname or +an IP address).

+
+

Closing Connections

+

These methods give control over closing connections:

+
+
::comm::comm shutdown id
+

This closes the connection to id, aborting all outstanding +commands in progress. Note that nothing prevents the connection from +being immediately reopened by another incoming or outgoing command.

+
::comm::comm abort
+

This invokes shutdown on all open connections in this comm channel.

+
::comm::comm destroy
+

This aborts all connections and then destroys the this comm channel +itself, including closing the listening socket. Special code allows +the default ::comm::comm channel to be closed such that the +::comm::comm command it is not destroyed. Doing so closes the +listening socket, preventing both incoming and outgoing commands on +the channel. This sequence reinitializes the default channel:

+
+    "::comm::comm destroy; ::comm::comm new ::comm::comm"
+
+
+
+

When a remote connection is lost (because the remote exited or called +shutdown), comm can invoke an application callback. +This can be used to cleanup or restart an ancillary process, for +instance. See the lost callback below.

+
+

Callbacks

+

This is a mechanism for setting hooks for particular events:

+
+
::comm::comm hook event ?+? ?script?
+

This uses a syntax similar to Tk's bind command. Prefixing +script with a + causes the new script to be appended. +Without this, a new script replaces any existing script. When +invoked without a script, no change is made. In all cases, the new +hook script is returned by the command.

+

When an event occurs, the script associated with it is +evaluated with the listed variables in scope and available. The +return code (not the return value) of the script is commonly +used decide how to further process after the hook.

+

Common variables include:

+
+
chan
+

the name of the comm channel (and command)

+
id
+

the id of the remote in question

+
fid
+

the file id for the socket of the connection

+
+
+

These are the defined events:

+
+
connecting
+

Variables: +chan, id

+

This hook is invoked before making a connection to the remote named in +id. An error return (via error) will abort the connection +attempt with the error. Example:

+
+    % ::comm::comm hook connecting {
+        if {[string match {*[02468]} $id]} {
+            error "Can't connect to even ids" 
+        }
+    }
+    % ::comm::comm send 10000 puts ok
+    Connect to remote failed: Can't connect to even ids
+    %
+
+
+
connected
+

Variables: +chan, fid, id, host, and port.

+

This hook is invoked immediately after making a remote connection to +id, allowing arbitrary authentication over the socket named by +fid. An error return (via error ) will close the +connection with the error. host and port are merely +extracted from the id; changing any of these will have no effect +on the connection, however. It is also possible to substitute and +replace fid.

+
incoming
+

Variables: +chan, fid, addr, and remport.

+

Hook invoked when receiving an incoming connection, allowing arbitrary +authentication over socket named by fid. An error return (via +error) will close the connection with the error. Note that the +peer is named by remport and addr but that the remote +id is still unknown. Example:

+
+    ::comm::comm hook incoming {
+        if {[string match 127.0.0.1 $addr]} {
+            error "I don't talk to myself"
+        }
+    }
+
+
+
eval
+

Variables: +chan, id, cmd, and buffer.

+

This hook is invoked after collecting a complete script from a remote +but before evaluating it. This allows complete control over +the processing of incoming commands. cmd contains either +send or async. buffer holds the script to +evaluate. At the time the hook is called, $chan remoteid is +identical in value to id.

+

By changing buffer, the hook can change the script to be +evaluated. The hook can short circuit evaluation and cause a value to +be immediately returned by using return result (or, from +within a procedure, return -code return result). An +error return (via error) will return an error result, as is if +the script caused the error. Any other return will evaluate the +script in buffer as normal. For compatibility with 3.2, +break and return -code break result is supported, +acting similarly to return {} and return -code return +result.

+

Examples:

+
    +

  1. augmenting a command

    +
    +    % ::comm::comm send [::comm::comm self] pid
+    5013
+    % ::comm::comm hook eval {puts "going to execute $buffer"}
+    % ::comm::comm send [::comm::comm self] pid
+    going to execute pid
+    5013
+
    +
    2. +

  2. short circuiting a command

    +
    +    % ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
+    % ::comm::comm send [::comm::comm self] pid
+    would have executed pid
+    0
+
    +
    3. +

  3. Replacing double eval semantics

    +
    +    % ::comm::comm send [::comm::comm self] llength {a b c}
+    wrong # args: should be "llength list"
+    % ::comm::comm hook eval {return [uplevel #0 $buffer]}
+    return [uplevel #0 $buffer]
+    % ::comm::comm send [::comm::comm self] llength {a b c}
+    3
+
    +
    4. +

  4. Using a slave interpreter

    +
    +    % interp create foo
+    % ::comm::comm hook eval {return [foo eval $buffer]}
+    % ::comm::comm send [::comm::comm self] set myvar 123
+    123
+    % set myvar
+    can't read "myvar": no such variable
+    % foo eval set myvar
+    123
+
    +
    5. +

  5. Using a slave interpreter (double eval)

    +
    +    % ::comm::comm hook eval {return [eval foo eval $buffer]}
+
    +
    6. +

  6. Subverting the script to execute

    +
    +    % ::comm::comm hook eval {
+        switch -- $buffer {
+            a {return A-OK}
+            b {return B-OK}
+            default {error "$buffer is a no-no"}
+        }
+    }
+    % ::comm::comm send [::comm::comm self] pid
+    pid is a no-no
+    % ::comm::comm send [::comm::comm self] a
+    A-OK
+
    +
    7. +
+
reply
+

Variables: +chan, id, buffer, ret, and return().

+

This hook is invoked after collecting a complete reply script from a +remote but before evaluating it. This allows complete +control over the processing of replies to sent commands. The reply +buffer is in one of the following forms

+
    +

  • return result

    • +

  • return -code code result

    • +

  • return -code code -errorinfo info -errorcode ecode msg

    • +
+

For safety reasons, this is decomposed. The return result is in +ret, and the return switches are in the return array:

+
    +

  • return(-code)

    • +

  • return(-errorinfo)

    • +

  • return(-errorcode)

    • +
+

Any of these may be the empty string. Modifying these four variables +can change the return value, whereas modifying buffer has no +effect.

+
callback
+

Variables: +chan, id, buffer, ret, and return().

+

Similar to reply, but used for callbacks.

+
lost
+

Variables: +chan, id, and reason.

+

This hook is invoked when the connection to id is lost. Return +value (or thrown error) is ignored. reason is an explanatory +string indicating why the connection was lost. Example:

+
+    ::comm::comm hook lost {
+        global myvar
+        if {$myvar(id) == $id} {
+            myfunc
+            return
+        }
+    }
+
+
+
+
+

Unsupported

+

These interfaces may change or go away in subsequence releases.

+
+
::comm::comm remoteid
+

Returns the id of the sender of the last remote command +executed on this channel. If used by a proc being invoked remotely, +it must be called before any events are processed. Otherwise, another +command may get invoked and change the value.

+
::comm::comm_send
+

Invoking this procedure will substitute the Tk send and +winfo interps commands with these equivalents that use +::comm::comm.

+
+    proc send {args} {
+        eval ::comm::comm send $args
+    }
+    rename winfo tk_winfo
+    proc winfo {cmd args} {
+        if {![string match in* $cmd]} {
+            return [eval [list tk_winfo $cmd] $args]
+        }
+        return [::comm::comm interps]
+    }
+
+
+
+
+

Security

+

Starting with version 4.6 of the package an option -socketcmd +is supported, allowing the user of a comm channel to specify which +command to use when opening a socket. Anything which is API-compatible +with the builtin ::socket (the default) can be used.

+

The envisioned main use is the specification of the tls::socket +command, see package tls, to secure the communication.

+
+	# Load and initialize tls
+	package require tls
+	tls::init  -cafile /path/to/ca/cert -keyfile ...
+	# Create secured comm channel
+	::comm::comm new SECURE -socketcmd tls::socket -listen 1
+	...
+
+

The sections Execution Environment and Callbacks +are also relevant to the security of the system, providing means to +restrict the execution to a specific environment, perform additional +authentication, and the like.

+
+

Blocking Semantics

+

There is one outstanding difference between comm and +send. When blocking in a synchronous remote command, send +uses an internal C hook (Tk_RestrictEvents) to the event loop to look +ahead for send-related events and only process those without +processing any other events. In contrast, comm uses the +vwait command as a semaphore to indicate the return message has +arrived. The difference is that a synchronous send will block +the application and prevent all events (including window related ones) +from being processed, while a synchronous ::comm::comm send +will block the application but still allow other events to get +processed. In particular, after idle handlers will fire +immediately when comm blocks.

+

What can be done about this? First, note that this behavior will come +from any code using vwait to block and wait for an event to +occur. At the cost of multiple channel support, comm could +be changed to do blocking I/O on the socket, giving send-like blocking +semantics. However, multiple channel support is a very useful feature +of comm that it is deemed too important to lose. The remaining +approaches involve a new loadable module written in C (which is +somewhat against the philosophy of comm) One way would be to +create a modified version of the vwait command that allow the +event flags passed to Tcl_DoOneEvent to be specified. For comm, +just the TCL_FILE_EVENTS would be processed. Another way would be to +implement a mechanism like Tk_RestrictEvents, but apply it to the Tcl +event loop (since comm doesn't require Tk). One of these +approaches will be available in a future comm release as an +optional component.

+
+

Asynchronous Result Generation

+

By default the result returned by a remotely invoked command is the +result sent back to the invoker. This means that the result is +generated synchronously, and the server handling the call is blocked +for the duration of the command.

+

While this is tolerable as long as only short-running commands are +invoked on the server long-running commands, like database queries +make this a problem. One command can prevent the processing requests +of all other clients for an arbitrary period of time.

+

Before version 4.5 of comm the only solution was to rewrite the server +command to use the Tcl builtin command vwait, or one of its +relatives like tkwait, to open a new event loop which processes +requests while the long-running operation is executed. This however +has its own perils, as this makes it possible to both overflow the Tcl +stack with a large number of event loop, and to have a newer requests +block the return of older ones, as the eventloop have to be unwound in +the order of their creation.

+

The proper solution is to have the invoked command indicate to +comm that it cannot or will not deliver an immediate, +synchronous result, but will do so later. At that point the framework +can put sending the actual result on hold and continue processing +requests using the main event loop. No blocking, no nesting of event +loops. At some future date the long running operation delivers the +result to comm, via the future object, which is then forwarded to the +invoker as usual.

+

The necessary support for this solution has been added to comm since +version 4.5, in the form of the new method return_async.

+
+
::comm::comm return_async
+

This command is used by a remotely invoked script to notify the comm +channel which invoked it that the result to send back to the invoker +is not generated synchronously. If this command is not called the +default/standard behaviour of comm is to send the synchronously +generated result of the script itself to the invoker.

+

The result of return_async is an object. This object, called a +future is where the result of the script has to be delivered to +when it becomes ready. When that happens it will take all the +necessary actions to deliver the result to the invoker of the script, +and then destroy itself. Should comm have lost the connection to the +invoker while the result is being computed the future will not try to +deliver the result it got, but just destroy itself. The future can be +configured with a command to call when the invoker is lost. This +enables the user to implement an early abort of the long-running +operation, should this be supported by it.

+

An example:

+
+# Procedure invoked by remote clients to run database operations.
+proc select {sql} {
+    # Signal the async generation of the result
+    set future [::comm::comm return_async]
+    # Generate an async db operation and tell it where to deliver the result.
+    set query [db query -command [list $future return] $sql]
+    # Tell the database system which query to cancel if the connection
+    # goes away while it is running.
+    $future configure -command [list db cancel $query]
+    # Note: The above will work without problem only if the async
+    # query will nover run its completion callback immediately, but
+    # only from the eventloop. Because otherwise the future we wish to
+    # configure may already be gone. If that is possible use 'catch'
+    # to prevent the error from propagating.
+    return
+}
+
+

The API of a future object is:

+
+
$future return ?-code code? ?value?
+

Use this method to tell the future that long-running operation has +completed. Arguments are an optional return value (defaults to the +empty string), and the Tcl return code (defaults to OK).

+

The future will deliver this information to invoker, if the connection +was not lost in the meantime, and then destroy itself. If the +connection was lost it will do nothing but destroy itself.

+
$future configure ?-command ?cmdprefix??
+
+
$future cget -command
+

These methods allow the user to retrieve and set a command to be +called if the connection the future belongs to has been lost.

+
+
+
+

Compatibility

+

comm exports itself as a package. The package version number +is in the form major . minor, where the major version will +only change when a non-compatible change happens to the API or +protocol. Minor bug fixes and changes will only affect the minor +version. To load comm this command is usually used:

+
+    package require comm 3
+
+

Note that requiring no version (or a specific version) can also be done.

+

The revision history of comm includes these releases:

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

+
+
+
+

Author

+

John LoVerso, John@LoVerso.Southborough.MA.US

+

http://www.opengroup.org/~loverso/tcl-tk/#comm

+
+

License

+

Please see the file comm.LICENSE that accompanied this source, +or +http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html.

+

This license for comm, new as of version 3.2, allows it to be +used for free, without any licensing fee or royalty.

+
+

Bugs

+
    +

  • If there is a failure initializing a channel created with +::comm::comm new, then the channel should be destroyed. +Currently, it is left in an inconsistent state.

    • +

  • There should be a way to force a channel to quiesce when changing the +configuration.

    • +
+

The following items can be implemented with the existing hooks and are +listed here as a reminder to provide a sample hook in a future +version.

+
    +

  • Allow easier use of a slave interp for actual command execution +(especially when operating in "not local" mode).

    • +

  • Add host list (xhost-like) or "magic cookie" (xauth-like) +authentication to initial handshake.

    • +
+

The following are outstanding todo items.

+
    +

  • Add an interp discovery and name->port mapping. This is likely to be +in a separate, optional nameserver. (See also the related work, +below.)

    • +

  • Fix the {id host} form so as not to be dependent upon +canonical hostnames. This requires fixes to Tcl to resolve hostnames!

    • +
+

This man page is bigger than the source file.

+
+

On Using Old Versions Of Tcl

+

Tcl7.5 under Windows contains a bug that causes the interpreter to +hang when EOF is reached on non-blocking sockets. This can be +triggered with a command such as this:

+
+    "comm send $other exit"
+
+

Always make sure the channel is quiescent before closing/exiting or +use at least Tcl7.6 under Windows.

+

Tcl7.6 on the Mac contains several bugs. It is recommended you use +at least Tcl7.6p2.

+

Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended +you use Tcl8.0p1 (or Tcl7.6p2).

+
+

Related Work

+

Tcl-DP provides an RPC-based remote execution interface, but is a +compiled Tcl extension. See +http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.

+

Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP +RPC interface using standard Tcl sockets, much like comm.

+

Andreas Kupries <andreas_kupries@users.sourceforge.net> uses +comm and has built a simple nameserver as part of his Pool +library. See http://www.purl.org/net/akupries/soft/pool/index.htm.

+
+

Bugs, Ideas, Feedback

+

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

+
+

See Also

+

send(n)

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/comm/comm_wire.html Index: embedded/www/tcllib/files/modules/comm/comm_wire.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/comm/comm_wire.html @@ -0,0 +1,280 @@ + +comm_wire - Remote communication + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

comm_wire(n) 3 tcllib "Remote communication"

+

Name

+

comm_wire - The comm wire protocol

+
+ +

Synopsis

+
+
    +
  • package require comm
    • +
+
+
+

Description

+

The comm command provides an inter-interpreter remote +execution facility much like Tk's send(n), except that it uses +sockets rather than the X server for the communication path. As a +result, comm works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path.

+

This document contains a specification of the various versions of the +wire protocol used by comm internally for the communication between +its endpoints. It has no relevance to users of comm, only to +developers who wish to modify the package, write a compatible facility +in a different language, or some other facility based on the same +protocol.

+
+

Wire Protocol Version 3

+

Basic Layer

+

The basic encoding for all data is UTF-8. Because of this +binary data, including the NULL character, can be sent over the wire +as is, without the need for armoring it.

+
+

Basic Message Layer

+

On top of the Basic Layer we have a +message oriented exchange of data. +The totality of all characters written to the channel is a Tcl list, +with each element a separate message, each itself a list. The +messages in the overall list are separated by EOL. Note that EOL +characters can occur within the list as well. They can be +distinguished from the message-separating EOL by the fact that the +data from the beginning up to their location is not a valid Tcl list.

+

EOL is signaled through the linefeed character, i.e LF, or, +hex 0x0a. This is following the unix convention for +line-endings.

+

As a list each message is composed of words. Their meaning +depends on when the message was sent in the overall exchange. This is +described in the upcoming sections.

+
+

Negotiation Messages - Initial Handshake

+

The command protocol is defined like this:

+
    +

  • The first message send by a client to a server, when opening the +connection, contains two words. The first word is a list as well, and +contains the versions of the wire protocol the client is willing to +accept, with the most preferred version first. The second word is the +TCP port the client is listening on for connections to itself. The +value 0 is used here to signal that the client will not listen +for connections, i.e. that it is purely for sending commands, and not +receiving them.

    • +

  • The first message sent by the server to the client, in response to the +message above contains only one word. This word is a list, containing +the string vers as its first element, and the version of the +wire protocol the server has selected from the offered versions as the +second.

    • +
+
+

Script/Command Messages

+

All messages coming after the initial handshake +consist of three words. These are an instruction, a transaction id, +and the payload. The valid instructions are shown below. The +transaction ids are used by the client to match any incoming replies +to the command messages it sent. This means that a server has to copy +the transaction id from a command message to the reply it sends for +that message.

+
+
send
+
+
async
+
+
command
+

The payload is the Tcl script to execute on the server. It is actually +a list containing the script fragments. These fragment are +concatenated together by the server to form the full script to +execute on the server side. +This emulates the Tcl "eval" semantics. +In most cases it is best to have only one word in the list, a list +containing the exact command.

+

Examples:

+
+    (a)     {send 1 {{array get tcl_platform}}}
+    (b)     {send 1 {array get tcl_platform}}
+    (c)     {send 1 {array {get tcl_platform}}}
+    are all valid representations of the same command. They are
+    generated via
+    (a')    send {array get tcl_platform}
+    (b')    send array get tcl_platform
+    (c')    send array {get tcl_platform}
+    respectively
+
+

Note that (a), generated by (a'), is the usual form, if only single +commands are sent by the client. +For example constructed using list, if the command contains +variable arguments. Like

+
+    send [list array get $the_variable]
+
+

These three instructions all invoke the script on the server +side. Their difference is in the treatment of result values, and thus +determines if a reply is expected.

+
+
send
+

A reply is expected. The sender is waiting for the result.

+
async
+

No reply is expected, the sender has no interest in the result and is +not waiting for any.

+
command
+

A reply is expected, but the sender is not waiting for it. It has +arranged to get a process-internal notification when the result +arrives.

+
+
reply
+

Like the previous three command, however the tcl script in the payload +is highly restricted. +It has to be a syntactically valid Tcl return command. This +contains result code, value, error code, and error info.

+

Examples:

+
+    {reply 1 {return -code 0 {}}}
+    {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
+
+
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/control/control.html Index: embedded/www/tcllib/files/modules/control/control.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/control/control.html @@ -0,0 +1,256 @@ + +control - Tcl Control Flow Commands + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

control(n) 0.1.3 tcllib "Tcl Control Flow Commands"

+

Name

+

control - Procedures for control flow structures.

+
+ + +

Description

+

The control package provides a variety of commands that provide +additional flow of control structures beyond the built-in ones +provided by Tcl. These are commands that in many programming +languages might be considered keywords, or a part of the +language itself. In Tcl, control flow structures are just commands +like everything else.

+
+

COMMANDS

+
+
control::control command option ?arg arg ...?
+

The control command is used as a configuration command for +customizing the other public commands of the control package. The +command argument names the command to be customized. The set of +valid option and subsequent arguments are determined by the +command being customized, and are documented with the command.

+
control::assert expr ?arg arg ...?
+

When disabled, the assert command behaves exactly like the +no-op command.

+

When enabled, the assert command evaluates expr as an +expression (in the same way that expr evaluates its argument). +If evaluation reveals that expr is not a valid boolean +expression (according to [string is boolean -strict]), +an error is raised. If expr evaluates to a true boolean value +(as recognized by if), then assert returns an empty +string. Otherwise, the remaining arguments to assert are used +to construct a message string. If there are no arguments, the message +string is "assertion failed: $expr". If there are arguments, they are +joined by join to form the message string. The message string +is then appended as an argument to a callback command, and the +completed callback command is evaluated in the global namespace.

+

The assert command can be customized by the control +command in two ways:

+

[control::control assert enabled ?boolean?] +queries or sets whether control::assert is enabled. When called +without a boolean argument, a boolean value is returned +indicating whether the control::assert command is enabled. When +called with a valid boolean value as the boolean argument, the +control::assert command is enabled or disabled to match the +argument, and an empty string is returned.

+

[control::control assert callback ?command?] +queries or sets the callback command that will be called by an enabled +assert on assertion failure. When called without a +command argument, the current callback command is returned. +When called with a command argument, that argument becomes the +new assertion failure callback command. Note that an assertion +failure callback command is always defined, even when assert +is disabled. The default callback command is +[return -code error].

+

Note that control::assert has been written so that in +combination with [namespace import], it is possible to +use enabled assert commands in some namespaces and disabled +assert commands in other namespaces at the same time. This +capability is useful so that debugging efforts can be independently +controlled module by module.

+
+% package require control
+% control::control assert enabled 1
+% namespace eval one namespace import ::control::assert
+% control::control assert enabled 0
+% namespace eval two namespace import ::control::assert
+% one::assert {1 == 0}
+assertion failed: 1 == 0
+% two::assert {1 == 0}
+
+
+
control::do body ?option test?
+

The do command evaluates the script body repeatedly +until the expression test becomes true or as long as +(while) test is true, depending on the value of +option being until or while. If +option and test are omitted the body is evaluated exactly +once. After normal completion, do returns an empty string. +Exceptional return codes (break, continue, error, +etc.) during the evaluation of body are handled in the same way +the while command handles them, except as noted in +LIMITATIONS, below.

+
control::no-op ?arg arg ...?
+

The no-op command takes any number of arguments and does +nothing. It returns an empty string.

+
+
+

LIMITATIONS

+

Several of the commands provided by the control package accept +arguments that are scripts to be evaluated. Due to fundamental +limitations of Tcl's catch and return commands, it is not +possible for these commands to properly evaluate the command +[return -code $code] within one of those script +arguments for any value of $code other than ok. In this +way, the commands of the control package are limited as compared +to Tcl's built-in control flow commands (such as if, +while, etc.) and those control flow commands that can be +provided by packages coded in C. An example of this difference:

+
+% package require control
+% proc a {} {while 1 {return -code error a}}
+% proc b {} {control::do {return -code error b} while 1}
+% catch a
+1
+% catch b
+0
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

break, continue, expr, if, join, namespace, return, string, while

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/coroutine/coro_auto.html Index: embedded/www/tcllib/files/modules/coroutine/coro_auto.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/coroutine/coro_auto.html @@ -0,0 +1,174 @@ + + +coroutine::auto - Coroutine utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

coroutine::auto(n) 1 tcllib "Coroutine utilities"

+

Name

+

coroutine::auto - Automatic event and IO coroutine awareness

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require coroutine::auto 1.1
    • +
  • 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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Coroutine

+
+ +
ADDED embedded/www/tcllib/files/modules/coroutine/coroutine.html Index: embedded/www/tcllib/files/modules/coroutine/coroutine.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/coroutine/coroutine.html @@ -0,0 +1,219 @@ + + +coroutine - Coroutine utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

coroutine(n) 1 tcllib "Coroutine utilities"

+

Name

+

coroutine - Coroutine based event and IO handling

+
+ + +

Description

+

The coroutine package provides coroutine-aware +implementations of various event- and channel related commands. It can +be in multiple modes:

+
    +

  1. Call the commands through their ensemble, in code which is +explicitly written for use within coroutines.

    2. +

  2. Import the commands into a namespace, either directly, or +through namespace path. This allows the use from within code +which is not coroutine-aware per se and restricted to specific +namespaces.

    3. +
+

A more agressive form of making code coroutine-oblivious than point 2 +above is available through the package coroutine::auto, +which intercepts the relevant builtin commands and changes their +implementation dependending on the context they are run in, i.e. +inside or outside of a coroutine.

+
+

API

+

All the commands listed below are synchronous with respect to the +coroutine invoking them, i.e. this coroutine blocks until the result +is available. The overall eventloop is not blocked however.

+
+
coroutine::util after delay
+

This command delays the coroutine invoking it by delay +milliseconds.

+
coroutine::util await varname...
+

This command is an extension form of the coroutine::util vwait +command (see below) which waits on a write to one of many named +namespace variables.

+
coroutine::util create arg...
+

This command creates a new coroutine with an automatically assigned +name and causes it to run the code specified by the arguments.

+
coroutine::util exit ?status?
+

This command exits the current coroutine, causing it to return +status. If no status was specified the default 0 is +returned.

+
coroutine::util gets chan ?varname?
+

This command reads a line from the channel chan and returns it +either as its result, or, if a varname was specified, writes it +to the named variable and returns the number of characters read.

+
coroutine::util global varname...
+

This command imports the named global variables of the coroutine into +the current scope. From the technical point of view these variables +reside in level #1 of the Tcl stack. I.e. these are not the +regular global variable in to the global namespace, and each coroutine +can have their own set, independent of all others.

+
coroutine::util read -nonewline chan ?n?
+

This command reads n characters from the channel chan and +returns them as its result. If n is not specified the command +will read the channel until EOF is reached.

+
coroutine::util update ?idletasks?
+

This command causes the coroutine invoking it to run pending events or +idle handlers before proceeding.

+
coroutine::util vwait varname
+

This command causes the coroutine calling it to wait for a write to +the named namespace variable varname.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Coroutine

+
+ +
ADDED embedded/www/tcllib/files/modules/counter/counter.html Index: embedded/www/tcllib/files/modules/counter/counter.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/counter/counter.html @@ -0,0 +1,297 @@ + + +counter - Counters and Histograms + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

counter(n) 2.0.4 tcllib "Counters and Histograms"

+

Name

+

counter - Procedures for counters and histograms

+
+ + +

Description

+

The counter package provides a counter facility and can +compute statistics and histograms over the collected data.

+
+
::counter::init tag args
+

This defines a counter with the name tag. The args +determines the characteristics of the counter. The args are

+
+
-group name
+

Keep a grouped counter where the name of the histogram bucket is +passed into ::counter::count.

+
-hist bucketsize
+

Accumulate the counter into histogram buckets of size +bucketsize. For example, if the samples are millisecond time +values and bucketsize is 10, then each histogram bucket +represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec, +and so on.

+
-hist2x bucketsize
+

Accumulate the statistic into histogram buckets. The size of the +first bucket is bucketsize, each other bucket holds values 2 +times the size of the previous bucket. For example, if +bucketsize is 10, then each histogram bucket represents time +values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec, +and so on.

+
-hist10x bucketsize
+

Accumulate the statistic into histogram buckets. The size of the +first bucket is bucketsize, each other bucket holds values 10 +times the size of the previous bucket. For example, if +bucketsize is 10, then each histogram bucket represents time +values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.

+
-lastn N
+

Save the last N values of the counter to maintain a "running +average" over the last N values.

+
-timehist secsPerMinute
+

Keep a time-based histogram. The counter is summed into a histogram +bucket based on the current time. There are 60 per-minute buckets +that have a size determined by secsPerMinute, which is normally +60, but for testing purposes can be less. Every "hour" (i.e., 60 +"minutes") the contents of the per-minute buckets are summed into the +next hourly bucket. Every 24 "hours" the contents of the per-hour +buckets are summed into the next daily bucket. The counter package +keeps all time-based histograms in sync, so the first +secsPerMinute value seen by the package is used for all +subsequent time-based histograms.

+
+
::counter::count tag ?delta? ?instance?
+

Increment the counter identified by tag. The default increment +is 1, although you can increment by any value, integer or real, by +specifying delta. You must declare each counter with +::counter::init to define the characteristics of counter before +you start to use it. If the counter type is -group, then the +counter identified by instance is incremented.

+
::counter::start tag instance
+

Record the starting time of an interval. The tag is the name of +the counter defined as a -hist value-based histogram. The +instance is used to distinguish this interval from any other +intervals that might be overlapping this one.

+
::counter::stop tag instance
+

Record the ending time of an interval. The delta time since the +corresponding ::counter::start call for instance is +recorded in the histogram identified by tag.

+
::counter::get tag args
+

Return statistics about a counter identified by tag. The +args determine what value to return:

+
+
-total
+

Return the total value of the counter. This is the default if +args is not specified.

+
-totalVar
+

Return the name of the total variable. Useful for specifying with +-textvariable in a Tk widget.

+
-N
+

Return the number of samples accumulated into the counter.

+
-avg
+

Return the average of samples accumulated into the counter.

+
-avgn
+

Return the average over the last N samples taken. The N +value is set in the ::counter::init call.

+
-hist bucket
+

If bucket is specified, then the value in that bucket of the +histogram is returned. Otherwise the complete histogram is returned +in array get format sorted by bucket.

+
-histVar
+

Return the name of the histogram array variable.

+
-histHour
+

Return the complete hourly histogram in array get format sorted by +bucket.

+
-histHourVar
+

Return the name of the hourly histogram array variable.

+
-histDay
+

Return the complete daily histogram in array get format sorted by +bucket.

+
-histDayVar
+

Return the name of the daily histogram array variable.

+
-resetDate
+

Return the clock seconds value recorded when the +counter was last reset.

+
-all
+

Return an array get of the array used to store the counter. This +includes the total, the number of samples (N), and any type-specific +information. This does not include the histogram array.

+
+
::counter::exists tag
+

Returns 1 if the counter is defined.

+
::counter::names
+

Returns a list of all counters defined.

+
::counter::histHtmlDisplay tag args
+

Generate HTML to display a histogram for a counter. The args +control the format of the display. They are:

+
+
-title string
+

Label to display above bar chart

+
-unit unit
+

Specify minutes, hours, or days for the +time-base histograms. For value-based histograms, the unit is +used in the title.

+
-images url
+

URL of /images directory.

+
-gif filename
+

Image for normal histogram bars. The filename is relative to +the -images directory.

+
-ongif filename
+

Image for the active histogram bar. The filename is relative to +the -images directory.

+
-max N
+

Maximum number of value-based buckets to display.

+
-height N
+

Pixel height of the highest bar.

+
-width N
+

Pixel width of each bar.

+
-skip N
+

Buckets to skip when labeling value-based histograms.

+
-format string
+

Format used to display labels of buckets.

+
-text boolean
+

If 1, a text version of the histogram is dumped, otherwise a graphical +one is generated.

+
+
::counter::reset tag args
+

Resets the counter with the name tag to an initial state. The +args determine the new characteristics of the counter. They have +the same meaning as described for ::counter::init.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/crc/cksum.html Index: embedded/www/tcllib/files/modules/crc/cksum.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/crc/cksum.html @@ -0,0 +1,238 @@ + +cksum - Cyclic Redundancy Checks + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

cksum(n) 1.1.3 tcllib "Cyclic Redundancy Checks"

+

Name

+

cksum - Calculate a cksum(1) compatible checksum

+
+ + +

Description

+

This package provides a Tcl implementation of the cksum(1) algorithm +based upon information provided at in the GNU implementation of this +program as part of the GNU Textutils 2.0 package.

+
+

COMMANDS

+
+
::crc::cksum ?-format format? ?-chunksize size? [ -channel chan | -filename file | string ]
+

The command takes string data or a channel or file name and returns a +checksum value calculated using the cksum(1) algorithm. The +result is formatted using the format(n) specifier provided or as +an unsigned integer (%u) by default.

+
+
+

OPTIONS

+
+
-channel name
+

Return a checksum for the data read from a channel. The command will +read data from the channel until the eof is true. If you need +to be able to process events during this calculation see the +PROGRAMMING INTERFACE section

+
-filename name
+

This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the -channel option had +been used. The file is closed on completion.

+
-format string
+

Return the checksum using an alternative format template.

+
+
+

PROGRAMMING INTERFACE

+

The cksum package implements the checksum using a context variable to +which additional data can be added at any time. This is expecially +useful in an event based environment such as a Tk application or a web +server package. Data to be checksummed may be handled incrementally +during a fileevent handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption.

+
+
::crc::CksumInit
+

Begins a new cksum context. Returns a token ID that must be used for the +remaining functions. An optional seed may be specified if required.

+
::crc::CksumUpdate token data
+

Add data to the checksum identified by token. Calling +CksumUpdate $token "abcd" is equivalent to calling +CksumUpdate $token "ab" followed by +CksumUpdate $token "cb". See EXAMPLES.

+
::crc::CksumFinal token
+

Returns the checksum value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a 32 bit integer value.

+
+
+

EXAMPLES

+
+% crc::cksum "Hello, World!"
+2609532967
+
+
+% crc::cksum -format 0x%X "Hello, World!"
+0x9B8A5027
+
+
+% crc::cksum -file cksum.tcl
+1828321145
+
+
+% set tok [crc::CksumInit]
+% crc::CksumUpdate $tok "Hello, "
+% crc::CksumUpdate $tok "World!"
+% crc::CksumFinal $tok
+2609532967
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/crc16.html Index: embedded/www/tcllib/files/modules/crc/crc16.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/crc/crc16.html @@ -0,0 +1,249 @@ + +crc16 - Cyclic Redundancy Checks + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

crc16(n) 1.1.2 tcllib "Cyclic Redundancy Checks"

+

Name

+

crc16 - Perform a 16bit Cyclic Redundancy Check

+
+ + +

Description

+

This package provides a Tcl-only implementation of the CRC +algorithms based upon information provided at +http://www.microconsultants.com/tips/crc/crc.txt +There are a number of permutations available for calculating CRC +checksums and this package can handle all of them. Defaults are set up +for the most common cases.

+
+

COMMANDS

+
+
::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -filename file
+
+
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -filename file
+
+
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -filename file
+

The command takes either string data or a file name and returns a checksum +value calculated using the CRC algorithm. The command used sets up the +CRC polynomial, initial value and bit ordering for the desired +standard checksum calculation. The result is formatted +using the format(n) specifier provided or as an unsigned integer +(%u) by default.

+

A number of common polynomials are in use with the CRC algorithm and +the most commonly used of these are included in this package. For +convenience each of these has a command alias in the crc namespace.

+

It is possible to implement the CRC-32 checksum using this crc16 +package as the implementation is sufficiently generic to extend to 32 +bit checksums. As an example this has been done already - however this +is not the fastest method to implement this algorithm in Tcl and a +separate crc32 package is available.

+
+
+

OPTIONS

+
+
-filename name
+

Return a checksum for the file contents instead of for parameter data.

+
-format string
+

Return the checksum using an alternative format template.

+
-seed value
+

Select an alternative seed value for the CRC calculation. The default +is 0 for the CRC16 calculation and 0xFFFF for the CCITT version. +This can be useful for calculating the CRC for data +structures without first converting the whole structure into a +string. The CRC of the previous member can be used as the seed for +calculating the CRC of the next member. It is also used for +accumulating a checksum from fragments of a large message (or file)

+
-implementation procname
+

This hook is provided to allow users to provide their own +implementation (perhaps a C compiled extension). The +procedure specfied is called with two parameters. The first is the +data to be checksummed and the second is the seed value. An +integer is expected as the result.

+

The package provides some implementations of standard CRC polynomials +for the XMODEM, CCITT and the usual CRC-16 checksum. For convenience, +additional commands have been provided that make use of these +implementations.

+
--
+

Terminate option processing.

+
+
+

EXAMPLES

+
+% crc::crc16 "Hello, World!"
+64077
+
+
+% crc::crc-ccitt "Hello, World!"
+26586
+
+
+% crc::crc16 -format 0x%X "Hello, World!"
+0xFA4D
+
+
+% crc::crc16 -file crc16.tcl
+51675
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/crc32.html Index: embedded/www/tcllib/files/modules/crc/crc32.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/crc/crc32.html @@ -0,0 +1,253 @@ + +crc32 - Cyclic Redundancy Checks + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

crc32(n) 1.3 tcllib "Cyclic Redundancy Checks"

+

Name

+

crc32 - Perform a 32bit Cyclic Redundancy Check

+
+ + +

Description

+

This package provides a Tcl implementation of the CRC-32 +algorithm based upon information provided at +http://www.naaccr.org/standard/crc32/document.html +If either the critcl package or the Trf package +are available then a compiled version may be used internally to +accelerate the checksum calculation.

+
+

COMMANDS

+
+
::crc::crc32 ?-format format? ?-seed value? [ -channel chan | -filename file | message ]
+

The command takes either string data or a channel or file name and +returns a checksum value calculated using the CRC-32 algorithm. The +result is formatted using the format(n) specifier provided. The +default is to return the value as an unsigned integer (format %u).

+
+
+

OPTIONS

+
+
-channel name
+

Return a checksum for the data read from a channel. The command will +read data from the channel until the eof is true. If you need +to be able to process events during this calculation see the +PROGRAMMING INTERFACE section

+
-filename name
+

This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the -channel option had +been used. The file is closed on completion.

+
-format string
+

Return the checksum using an alternative format template.

+
-seed value
+

Select an alternative seed value for the CRC calculation. The default +is 0xffffffff. This can be useful for calculating the CRC for data +structures without first converting the whole structure into a +string. The CRC of the previous member can be used as the seed for +calculating the CRC of the next member. +Note that the crc32 algorithm includes a final XOR step. If +incremental processing is desired then this must be undone before +using the output of the algorithm as the seed for further +processing. A simpler alternative is to use the +PROGRAMMING INTERFACE which is intended for this mode of +operation.

+
+
+

PROGRAMMING INTERFACE

+

The CRC-32 package implements the checksum using a context variable to +which additional data can be added at any time. This is expecially +useful in an event based environment such as a Tk application or a web +server package. Data to be checksummed may be handled incrementally +during a fileevent handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption.

+
+
::crc::Crc32Init ?seed?
+

Begins a new CRC32 context. Returns a token ID that must be used for the +remaining functions. An optional seed may be specified if required.

+
::crc::Crc32Update token data
+

Add data to the checksum identified by token. Calling +Crc32Update $token "abcd" is equivalent to calling +Crc32Update $token "ab" followed by +Crc32Update $token "cb". See EXAMPLES.

+
::crc::Crc32Final token
+

Returns the checksum value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a 32 bit integer value.

+
+
+

EXAMPLES

+
+% crc::crc32 "Hello, World!"
+3964322768
+
+
+% crc::crc32 -format 0x%X "Hello, World!"
+0xEC4AC3D0
+
+
+% crc::crc32 -file crc32.tcl
+483919716
+
+
+% set tok [crc::Crc32Init]
+% crc::Crc32Update $tok "Hello, "
+% crc::Crc32Update $tok "World!"
+% crc::Crc32Final $tok
+3964322768
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/sum.html Index: embedded/www/tcllib/files/modules/crc/sum.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/crc/sum.html @@ -0,0 +1,213 @@ + +sum - Cyclic Redundancy Checks + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

sum(n) 1.1.0 tcllib "Cyclic Redundancy Checks"

+

Name

+

sum - Calculate a sum(1) compatible checksum

+
+ + +

Description

+

This package provides a Tcl-only implementation of the sum(1) command +which calculates a 16 bit checksum value from the input data. The BSD +sum algorithm is used by default but the SysV algorithm is also +available.

+
+

COMMANDS

+
+
::crc::sum ?-bsd | -sysv? ?-format fmt? ?-chunksize size? [ -filename file | -channel chan | string ]
+

The command takes string data or a file name or a channel and returns +a checksum value calculated using the sum(1) algorithm. The +result is formatted using the format(n) specifier provided or as +an unsigned integer (%u) by default.

+
+
+

OPTIONS

+
+
-sysv
+

The SysV algorithm is fairly naive. The byte values are summed and any +overflow is discarded. The lowest 16 bits are returned as the +checksum. Input with the same content but different ordering will +give the same result.

+
-bsd
+

This algorithm is similar to the SysV version but includes a bit rotation +step which provides a dependency on the order of the data values.

+
-filename name
+

Return a checksum for the file contents instead of for parameter data.

+
-channel chan
+

Return a checksum for the contents of the specified channel. The +channel must be open for reading and should be configured for binary +translation. The channel will no be closed on completion.

+
-chunksize size
+

Set the block size used when reading data from either files or +channels. This value defaults to 4096.

+
-format string
+

Return the checksum using an alternative format template.

+
+
+

EXAMPLES

+
+% crc::sum "Hello, World!"
+37287
+
+
+% crc::sum -format 0x%X "Hello, World!"
+0x91A7
+
+
+% crc::sum -file sum.tcl
+13392
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/csv/csv.html Index: embedded/www/tcllib/files/modules/csv/csv.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/csv/csv.html @@ -0,0 +1,319 @@ + + +csv - CSV processing + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

csv(n) 0.8 tcllib "CSV processing"

+

Name

+

csv - Procedures to handle CSV data.

+
+ + +

Description

+

The csv package provides commands to manipulate information +in CSV FORMAT (CSV = Comma Separated Values).

+
+

COMMANDS

+

The following commands are available:

+
+
::csv::iscomplete data
+

A predicate checking if the argument data is a complete csv +record. The result is a boolean flag indicating the completeness of +the data. The result is true if the data is complete.

+
::csv::join values ?sepChar? ?delChar? ?delMode?
+

Takes a list of values and returns a string in CSV format containing +these values. The separator character can be defined by the caller, +but this is optional. The default is ",". The quoting aka delimiting character can +be defined by the caller, but this is optional. The default is '"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead.

+
::csv::joinlist values ?sepChar? ?delChar? ?delMode?
+

Takes a list of lists of values and returns a string in CSV format +containing these values. The separator character can be defined by the +caller, but this is optional. The default is ",". The quoting character +can be defined by the caller, but this is optional. The default is '"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead. +Each element of the outer list is considered a record, these are +separated by newlines in the result. The elements of each record are +formatted as usual (via ::csv::join).

+
::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?
+

Takes a matrix object following the API specified for the +struct::matrix package and returns a string in CSV format containing +these values. The separator character can be defined by the caller, +but this is optional. The default is ",". The quoting character +can be defined by the caller, but this is optional. The default is +'"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead. +Each row of the matrix is considered a record, these are +separated by newlines in the result. The elements of each record are +formatted as usual (via ::csv::join).

+
::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
+

A wrapper around ::csv::split2matrix (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given matrix. For an explanation of the expand +argument see ::csv::split2matrix.

+
::csv::read2queue ?-alternate? chan q {sepChar ,}
+

A wrapper around ::csv::split2queue (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given queue.

+
::csv::report cmd matrix ?chan?
+

A report command which can be used by the matrix methods +format 2string and format 2chan. For the latter this +command delegates the work to ::csv::writematrix. cmd is +expected to be either printmatrix or +printmatrix2channel. The channel argument, chan, has +to be present for the latter and must not be present for the first.

+
::csv::split ?-alternate? line ?sepChar? ?delChar?
+

converts a line in CSV format into a list of the values +contained in the line. The character used to separate the values from +each other can be defined by the caller, via sepChar, but this +is optional. The default is ",". The quoting character can be defined +by the caller, but this is optional. The default is '"'.

+

If the option -alternate is specified a slightly different +syntax is used to parse the input. This syntax is explained below, in +the section FORMAT.

+
::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
+

The same as ::csv::split, but appends the resulting list as a +new row to the matrix m, using the method add row. The +expansion mode specified via expand determines how the command +handles a matrix with less columns than contained in line. The +allowed modes are:

+
+
none
+

This is the default mode. In this mode it is the responsibility of the +caller to ensure that the matrix has enough columns to contain the +full line. If there are not enough columns the list of values is +silently truncated at the end to fit.

+
empty
+

In this mode the command expands an empty matrix to hold all columns +of the specified line, but goes no further. The overall effect is that +the first of a series of lines determines the number of columns in the +matrix and all following lines are truncated to that size, as if mode +none was set.

+
auto
+

In this mode the command expands the matrix as needed to hold all +columns contained in line. The overall effect is that after +adding a series of lines the matrix will have enough columns to hold +all columns of the longest line encountered so far.

+
+
::csv::split2queue ?-alternate? q line {sepChar ,}
+

The same as ::csv::split, but appending the resulting list as a +single item to the queue q, using the method put.

+
::csv::writematrix m chan ?sepChar? ?delChar?
+

A wrapper around ::csv::join taking all rows in the matrix +m and writing them CSV formatted into the channel chan.

+
::csv::writequeue q chan ?sepChar? ?delChar?
+

A wrapper around ::csv::join taking all items in the queue +q (assumes that they are lists) and writing them CSV formatted +into the channel chan.

+
+
+

FORMAT

+

The format of regular CSV files is specified as

+
    +

  1. Each record of a csv file (comma-separated values, as exported e.g. by +Excel) is a set of ASCII values separated by ",". For other languages +it may be ";" however, although this is not important for this case as +the functions provided here allow any separator character.

    2. +

  2. If and only if a value contains itself the separator ",", then it (the +value) has to be put between "". If the value does not contain the +separator character then quoting is optional.

    3. +

  3. If a value contains the character ", that character is represented by "".

    4. +

  4. The output string "" represents the value ". In other words, it is +assumed that it was created through rule 3, and only this rule, +i.e. that the value was not quoted.

    5. +
+

An alternate format definition mainly used by MS products specifies +that the output string "" is a representation of the empty +string. In other words, it is assumed that the output was generated +out of the empty string by quoting it (i.e. rule 2), and not through +rule 3. This is the only difference between the regular and the +alternate format.

+

The alternate format is activated through specification of the option +-alternate to the various split commands.

+
+

EXAMPLE

+

Using the regular format the record

+
+123,"123,521.2","Mary says ""Hello, I am Mary""",""
+
+

is parsed into the items

+
+a) 123
+b) 123,521.2
+c) Mary says "Hello, I am Mary"
+d) "
+
+

Using the alternate format the result is

+
+a) 123
+b) 123,521.2
+c) Mary says "Hello, I am Mary"
+d) (the empty string)
+
+

instead. As can be seen only item (d) is different, now the empty string +instead of a ".

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/des/des.html Index: embedded/www/tcllib/files/modules/des/des.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/des/des.html @@ -0,0 +1,292 @@ + + +des - Data Encryption Standard (DES) + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

des(n) 1.1 tcllib "Data Encryption Standard (DES)"

+

Name

+

des - Implementation of the DES and triple-DES ciphers

+
+ + +

Description

+

This is an implementation in Tcl of the Data Encryption Standard (DES) +as published by the U.S. National Institute of Standards and +Technology (NIST) [1]. This implementation also supports triple +DES (3DES) extension to DES. DES is a 64-bit block cipher that uses a +56-bit key. 3DES uses a 168-bit key. DES has now officially been +superceeded by AES but is in common use in many protocols.

+

The tcllib implementation of DES and 3DES uses an implementation by +Mac Cody and is available as a separate download from [2]. For +anyone concerned about the details of exporting this code please see +the TclDES web pages. The tcllib specific code is a wrapper to the +TclDES API that presents same API for the DES cipher as for other +ciphers in the library.

+
+

COMMANDS

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

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

+

The -key option must be given. This parameter takes a binary +string of 8 bytes in length and is used to generate the key schedule. +In DES only 56 bits of key data are used. The highest bit from each +byte is discarded.

+

The -mode and -dir options are optional and default to cbc +mode and encrypt respectively. The initialization vector -iv +takes an 8 byte binary argument. This defaults to all zeros. See +MODES OF OPERATION for more about -mode and the use +of the initialization vector.

+

DES is a 64-bit block cipher. This means that the data must be +provided in units that are a multiple of 8 bytes.

+
+
+

PROGRAMMING INTERFACE

+

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

+
+
::DES::Init mode keydata iv ?weak?
+

Construct a new DES key schedule using the specified key data and the +given initialization vector. The initialization vector is not used +with ECB mode but is important for other usage modes. +See MODES OF OPERATION.

+

There are a small number of keys that are known to be weak when used +with DES. By default if such a key is passed in then an error will be +raised. If there is a need to accept such keys then the weak +parameter can be set true to avoid the error being thrown.

+
::DES::Encrypt Key data
+

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

+
::DES::Decrypt Key data
+

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

+
::DES::Reset Key iv
+

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

+
::DES::Final Key
+

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

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

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

+
Cipher Block Chaining (CBC)
+

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

+
Cipher Feedback (CFB)
+

CFB mode can be used to convert block ciphers into stream ciphers. In +CFB mode the initialization vector is encrypted and the output is then +xor'd with the plaintext stream. The result is then used as the +initialization vector for the next round. Errors will affect the +current block and the next block.

+
Output Feedback (OFB)
+

OFB is similar to CFB except that the output of the cipher is fed back +into the next round and not the xor'd plain text. This means that +errors only affect a single block but the cipher is more vulnerable to +attack.

+
+
+

EXAMPLES

+
+% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
+% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]
+
+
+set iv [string repeat \\0 8]
+set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
+set ciphertext [DES::Encrypt $Key "somedata"]
+append ciphertext [DES::Encrypt $Key "moredata"]
+DES::Reset $Key $iv
+set plaintext [DES::Decrypt $Key $ciphertext]
+DES::Final $Key
+
+
+

REFERENCES

+
    +

  1. "Data Encryption Standard", + Federal Information Processing Standards Publication 46-3, 1999, + (http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf)

    2. +

  2. "TclDES: munitions-grade Tcl scripting" + http://tcldes.sourceforge.net/

    3. +
+
+

AUTHORS

+

Jochen C Loewer, +Mac Cody, +Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/dns/tcllib_dns.html Index: embedded/www/tcllib/files/modules/dns/tcllib_dns.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/dns/tcllib_dns.html @@ -0,0 +1,332 @@ + +dns - Domain Name Service + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

dns(n) 1.3.3 tcllib "Domain Name Service"

+

Name

+

dns - Tcl Domain Name Service Client

+
+ + +

Description

+

The dns package provides a Tcl only Domain Name Service client. You +should refer to (1) and (2) for information about the DNS protocol or +read resolver(3) to find out how the C library resolves domain names. +The intention of this package is to insulate Tcl scripts +from problems with using the system library resolver for slow name servers. +It may or may not be of practical use. Internet name resolution is a +complex business and DNS is only one part of the resolver. You may +find you are supposed to be using hosts files, NIS or WINS to name a +few other systems. This package is not a substitute for the C library +resolver - it does however implement name resolution over DNS. +The package also extends the package uri to support DNS URIs +(4) of the form dns:what.host.com or +dns://my.nameserver/what.host.com. The dns::resolve +command can handle DNS URIs or simple domain names as a query.

+

Note: The package defaults to using DNS over TCP +connections. If you wish to use UDP you will need to have the +tcludp package installed and have a version that +correctly handles binary data (> 1.0.4). +This is available at http://tcludp.sourceforge.net/. +If the udp package is present then UDP will be used by default.

+
+

COMMANDS

+
+
::dns::resolve query ?options?
+

Resolve a domain name using the DNS protocol. query is +the domain name to be lookup up. This should be either a fully +qualified domain name or a DNS URI.

+
+
-nameserver hostname or -server hostname
+

Specify an alternative name server for this request.

+
-protocol tcp|udp
+

Specify the network protocol to use for this request. Can be one of + tcp or udp.

+
-port portnum
+

Specify an alternative port.

+
-search domainlist
+
+
-timeout milliseconds
+

Override the default timeout.

+
-type TYPE
+

Specify the type of DNS record you are interested in. Valid values + are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, + MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. + See RFC1035 for details about the return values. + See http://spf.pobox.com/ about SPF. + See (3) about AAAA records and RFC2782 for details of SRV records.

+
-class CLASS
+

Specify the class of domain name. This is usually IN but may be one + of IN for internet domain names, CS, CH, HS or * for any class.

+
-recurse boolean
+

Set to false if you do not want the name server to recursively + act upon your request. Normally set to true.

+
-command procname
+

Set a procedure to be called upon request completion. The procedure + will be passed the token as its only argument.

+
+
::dns::configure ?options?
+

The ::dns::configure command is used to setup the dns +package. The server to query, the protocol and domain search path are +all set via this command. If no arguments are provided then a list of +all the current settings is returned. If only one argument then it +must the the name of an option and the value for that option is +returned.

+
+
-nameserver hostname
+

Set the default name server to be used by all queries. The default is + localhost.

+
-protocol tcp|udp
+

Set the default network protocol to be used. Default is tcp.

+
-port portnum
+

Set the default port to use on the name server. The default is 53.

+
-search domainlist
+

Set the domain search list. This is currently not used.

+
-timeout milliseconds
+

Set the default timeout value for DNS lookups. Default is 30 seconds.

+
-loglevel level
+

Set the log level used for emitting diagnostic messages from this + package. The default is warn. See the log package + for details of the available levels.

+
+
::dns::name token
+

Returns a list of all domain names returned as an answer to your query.

+
::dns::address token
+

Returns a list of the address records that match your query.

+
::dns::cname token
+

Returns a list of canonical names (usually just one) matching your query.

+
::dns::result token
+

Returns a list of all the decoded answer records provided for your + query. This permits you to extract the result for more unusual query types.

+
::dns::status token
+

Returns the status flag. For a successfully completed query this will be + ok. May be error or timeout or eof. + See also ::dns::error

+
::dns::error token
+

Returns the error message provided for requests whose status is error. + If there is no error message then an empty string is returned.

+
::dns::reset token
+

Reset or cancel a DNS query.

+
::dns::wait token
+

Wait for a DNS query to complete and return the status upon completion.

+
::dns::cleanup token
+

Remove all state variables associated with the request.

+
::dns::nameservers
+

Attempts to return a list of the nameservers currently configured +for the users system. On a unix machine this parses the +/etc/resolv.conf file for nameservers (if it exists) and on Windows +systems we examine certain parts of the registry. If no nameserver can +be found then the loopback address (127.0.0.1) is used as a default.

+
+
+

EXAMPLES

+
+% set tok [dns::resolve www.tcl.tk]
+::dns::1
+% dns::status $tok
+ok
+% dns::address $tok
+199.175.6.239
+% dns::name $tok
+www.tcl.tk
+% dns::cleanup $tok
+
+

Using DNS URIs as queries:

+
+% set tok [dns::resolve "dns:tcl.tk;type=MX"]
+% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]
+
+

Reverse address lookup:

+
+% set tok [dns::resolve 127.0.0.1]
+::dns::1
+% dns::name $tok
+localhost
+% dns::cleanup $tok
+
+
+

REFERENCES

+
    +

  1. Mockapetris, P., "Domain Names - Concepts and Facilities", + RFC 1034, November 1987. + (http://www.ietf.org/rfc/rfc1034.txt)

    2. +

  2. Mockapetris, P., "Domain Names - Implementation and Specification", + RFC 1035, November 1087. + (http://www.ietf.org/rfc/rfc1035.txt)

    3. +

  3. Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", + RFC 1886, December 1995. + (http://www.ietf.org/rfc/rfc1886.txt)

    4. +

  4. Josefsson, S., "Domain Name System Uniform Resource Identifiers", + Internet-Draft, October 2003, + (http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt)

    5. +

  5. Gulbrandsen, A., Vixie, P. and Esibov, L., + "A DNS RR for specifying the location of services (DNS SRV)", + RFC 2782, February 2000, + (http://www.ietf.org/rfc/rfc2782.txt)

    6. +

  6. Ohta, M. "Incremental Zone Transfer in DNS", + RFC 1995, August 1996, + (http://www.ietf.org/rfc/rfc1995.txt)

    7. +
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

resolver(5)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/dns/tcllib_ip.html Index: embedded/www/tcllib/files/modules/dns/tcllib_ip.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/dns/tcllib_ip.html @@ -0,0 +1,459 @@ + +tcllib_ip - Domain Name Service + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcllib_ip(n) 1.3 tcllib "Domain Name Service"

+

Name

+

tcllib_ip - IPv4 and IPv6 address manipulation

+
+ + +

Description

+

This package provides a set of commands to help in parsing, displaying +and comparing internet addresses. The package can handle both IPv4 (1) +and IPv6 (2) address types.

+
+

COMMANDS

+
+
::ip::version address
+

Returns the protocol version of the address (4 or 6) or 0 if the +address is neither IPv4 or IPv6.

+
::ip::is class address
+

Returns true if the address is a member of the given protocol +class. The class parameter may be either ipv4 or ipv6 +This is effectively a boolean equivalent of the version +command. The class argument may be shortened to 4 or +6.

+
::ip::equal address address
+

Compare two address specifications for equivalence. The arguments are +normalized and the address prefix determined (if a mask is +supplied). The normalized addresses are then compared bit-by-bit and +the procedure returns true if they match.

+
::ip::normalize address
+

Convert an IPv4 or IPv6 address into a fully expanded version. There +are various shorthand ways to write internet addresses, missing out +redundant parts or digts.. 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::prefix address
+

Returns the address prefix generated by masking the address part with +the mask if provided. If there is no mask then it is equivalent to +calling normalize

+
::ip::type address
+
+
::ip::mask address
+

If the address supplied includes a mask then this is returned +otherwise returns an empty string.

+
::ip::prefixToNative prefix
+

This command converts the string prefix from dotted form +(<ipaddr>/<mask> format) to native (hex) form. Returns a list +containing two elements, ipaddress and mask, in this order, in +hexadecimal notation.

+
+   % ip::prefixToNative 1.1.1.0/24
+   0x01010100 0xffffff00
+
+
+
::ip::nativeToPrefix nativeList|native ?-ipv4?
+

This command converts from native (hex) form to dotted form. +It is the complement of ::ip::prefixToNative.

+
+
list nativeList (in)
+

List of several ip addresses in native form. The native form is a list +as returned by ::ip::prefixToNative.

+
list native (in)
+

A list as returned by ::ip::prefixToNative.

+
+

The command returns a list of addresses in dotted form if it was +called with a list of addresses. Otherwise a single address in dotted +form is returned.

+
+   % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
+   1.1.1.0/24
+
+
+
::ip::intToString number ?-ipv4?
+

This command converts from an ip address specified as integer number +to dotted form.

+
+       ip::intToString 4294967295
+       255.255.255.255
+
+
+
::ip::toInteger ipaddr
+

This command converts a dotted form ip into an integer number.

+
+   % ::ip::toInteger 1.1.1.0
+   16843008
+
+
+
::ip::toHex ipaddr
+

This command converts dotted form ip into a hexadecimal number.

+
+   % ::ip::toHex 1.1.1.0
+   0x01010100
+
+
+
::ip::maskToInt ipmask
+

This command convert an ipmask in either dotted (255.255.255.0) form +or mask length form (24) into an integer number.

+
+   ::ip::maskToInt 24
+   4294967040
+
+
+
::ip::broadcastAddress prefix ?-ipv4?
+

This commands returns a broadcast address in dotted form for the given +route prefix, either in the form "addr/mask", or in native +form. The result is in dotted form.

+
+   ::ip::broadcastAddress 1.1.1.0/24
+   1.1.1.255
+   ::ip::broadcastAddress {0x01010100 0xffffff00}
+   0x010101ff
+
+
+
::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
+

This command converts the dotted or integer form of an ipmask to +the mask length form.

+
+   ::ip::maskToLength 0xffffff00 -ipv4
+   24
+   % ::ip::maskToLength 255.255.255.0
+   24
+
+
+
::ip::lengthToMask maskLength ?-ipv4?
+

This command converts an ipmask in mask length form to its dotted +form.

+
+   ::ip::lengthToMask 24
+   255.255.255.0
+
+
+
::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
+

This command returns an ipaddress in the same position in the +count next network. The default value for count is +1.

+

The address can be specified as either integer number or in dotted +form. The mask can be specified as either integer number, dotted form, +or mask length form.

+

The result is in hex form.

+
::ip::isOverlap prefix prefix...
+

This command checks if the given ip prefixes overlap. All arguments +are in dotted "addr/mask" form. All arguments after the first prefix +are compared against the first prefix. The result is a boolean +value. It is true if an overlap was found for any of the prefixes.

+
+  % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
+  0
+  ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
+  1
+
+
+
::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hexiplist
+

This command is similar to ::ip::isOverlap, however the +arguments are in the native form, and the form of the result is under +greater control of the caller. +If the option -all is specified it checks all addresses for +overlap, not only until the first one is found. +If the option -inline is specified the command returns the +overlapping prefix instead of index values.

+

The result of the command is, depending on the specified options,

+
+
no options
+

The index of the first overlap found, or 0 if there is none.

+
-all
+

A list containing the indices of all overlaps found, or an empty list +if there are none.

+
-inline
+

The first overlapping prefix, or an empoty string if there is none.

+
-all -inline
+

A list containing the prefixes of all overlaps found, or an empty list +if there are none.

+
+
+  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
+  0
+  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
+  2
+
+
+
::ip::ipToLayer2Multicast ipaddr
+

This command an converts ipv4 address in dotted form into a layer 2 +multicast address, also in dotted form.

+
+  % ::ip::ipToLayer2Multicast 224.0.0.2
+  01.00.5e.00.00.02
+
+
+
::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
+

This command returns a host address from a prefix in the form +"ipaddr/masklen", also making sure that the result is not an address +found in the prefixExcludeList. +The result is an ip address in dotted form.

+
+  %::ip::ipHostFromPrefix  1.1.1.5/24
+  1.1.1.1
+  %::ip::ipHostFromPrefix  1.1.1.1/32
+  1.1.1.1
+
+
+
::ip::reduceToAggregates prefixlist
+

This command finds nets that overlap and filters out the more specific +nets. The prefixes are in either addr/mask form or in native format. +The result is a list containing the non-overlapping ip prefixes from +the input.

+
+  % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8  2.1.1.0/24 1.1.1.1/32 }
+  1.0.0.0/8 2.1.1.0/24
+
+
+
::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
+

This command finds longest prefix match from set of prefixes, given a +specific host address. The prefixes in the list are in either native +or dotted form, whereas the host address is in either ipprefix format, +dotted form, or integer form. +The result is the prefix which is the most specific match to the host +address.

+
+  % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8  2.1.1.0/24 1.1.1.0/28 }
+  1.1.1.0/28
+
+
+
::ip::collapse prefixlist
+

This commands takes a list of prefixes and returns a list prefixes +with the largest possible subnet masks covering the input, in this +manner collapsing adjacent prefixes into larger ranges.

+

This is different from ::ip::reduceToAggregates in that +the latter only removes specific nets from a list when they are +covered by other elements of the input whereas this command actively +merges nets into larger ranges when they are adjacent to each other.

+
+% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
+1.2.2.0/23
+
+
+
::ip::subtract prefixlist
+

This command takes a list of prefixes, some of which are prefixed by a +dash. These latter negative prefixes are used to punch holes +into the ranges described by the other, positive, +prefixes. I.e. the negative prefixes are subtracted frrom the positive +ones, resulting in a larger list of describes describing the covered +ranges only as positives.

+
+
+

EXAMPLES

+
+% ip::version ::1
+6
+% ip::version 127.0.0.1
+4
+
+
+% ip::normalize 127/8
+127.0.0.0/8
+% ip::contract 192.168.0.0
+192.168
+%
+% ip::normalize fec0::1
+fec0:0000:0000:0000:0000:0000:0000:0001
+% ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
+fec0::1
+
+
+% ip::equal 192.168.0.4/16 192.168.0.0/16
+1
+% ip::equal fec0::1/10 fec0::fe01/10
+1
+
+
+

REFERENCES

+
    +

  1. Postel, J. "Internet Protocol." RFC 791, September 1981, + (http://www.ietf.org/rfc/rfc791.txt)

    2. +

  2. Hinden, R. and Deering, S., + "Internet Protocol Version 6 (IPv6) Addressing Architecture", + RFC 3513, April 2003 + (http://www.ietf.org/rfc/rfc3513.txt)

    3. +
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+

See Also

+

inet(3), ip(7), ipv6(7)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/docstrip/docstrip.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/docstrip/docstrip.html @@ -0,0 +1,524 @@ + +docstrip - Literate programming tool + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docstrip(n) 1.2 tcllib "Literate programming tool"

+

Name

+

docstrip - Docstrip style source code extraction

+
+ + +

Description

+

Docstrip is a tool created to support a brand of Literate +Programming. It is most common in the (La)TeX community, where it +is being used for pretty much everything from the LaTeX core and up, +but there is nothing about docstrip which prevents using it +for other types of software.

+

In short, the basic principle of literate programming is that program +source should primarily be written and structured to suit the +developers (and advanced users who want to peek "under the hood"), not +to suit the whims of a compiler or corresponding source code consumer. +This means literate sources often need some kind of "translation" to an +illiterate form that dumb software can understand. +The docstrip Tcl package handles this translation.

+

Even for those who do not whole-hartedly subscribe to the philosophy +behind literate programming, docstrip can bring greater +clarity to in particular:

+
    + +

  • programs employing non-obvious mathematics

    • +

  • projects where separate pieces of code, perhaps in + different languages, need to be closely coordinated.

    • +
+

The first is by providing access to much more powerful typographical +features for source code comments than are possible in plain text. +The second is because all the separate pieces of code can be kept +next to each other in the same source file.

+

The way it works is that the programmer edits directly only one or +several "master" source code files, from which docstrip +generates the more traditional "source" files compilers or the like +would expect. The master sources typically contain a large amount of +documentation of the code, sometimes even in places where the code +consumers would not allow any comments. The etymology of "docstrip" +is that this documentation was stripped away (although +"code extraction" might be a better description, as it has always +been a matter of copying selected pieces of the master source rather +than deleting text from it). +The docstrip Tcl package contains a reimplementation of +the basic extraction functionality from the docstrip +program, and thus makes it possible for a Tcl interpreter to read +and interpret the master source files directly.

+

Readers who are not previously familiar with docstrip but +want to know more about it may consult the following sources.

+
    +

  1. The tclldoc package and class, + http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/.

    2. +

  2. The DocStrip utility, + http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx.

    3. +

  3. The doc and shortvrb Packages, + http://ctan.org/tex-archive/macros/latex/base/doc.dtx.

    4. +

  4. Chapter 14 of + The LaTeX Companion (second edition), + Addison-Wesley, 2004; ISBN 0-201-36299-6.

    5. +
+
+

File format

+

The basic unit docstrip operates on are the lines of +a master source file. Extraction consists of selecting some of these +lines to be copied from input text to output text. The basic +distinction is that between code lines (which are copied and +do not begin with a percent character) and comment lines +(which begin with a percent character and are not copied).

+
+   docstrip::extract [join {
+     {% comment}
+     {% more comment !"#$%&/(}
+     {some command}
+     { % blah $blah "Not a comment."}
+     {% abc; this is comment}
+     {# def; this is code}
+     {ghi}
+     {% jkl}
+   } \n] {}
+
+

returns the same sequence of lines as

+
+   join {
+     {some command}
+     { % blah $blah "Not a comment."}
+     {# def; this is code}
+     {ghi} ""
+   } \n
+
+

It does not matter to docstrip what format is used for the +documentation in the comment lines, but in order to do better than +plain text comments, one typically uses some markup language. Most +commonly LaTeX is used, as that is a very established standard and +also provides the best support for mathematical formulae, but the +docstrip::util package also gives some support for +doctools-like markup.

+

Besides the basic code and comment lines, there are also +guard lines, which begin with the two characters '%<', and +meta-comment lines, which begin with the two characters +'%%'. Within guard lines there is furthermore the distinction between +verbatim guard lines, which begin with '%<<', and ordinary +guard lines, where the '%<' is not followed by another '<'. The last +category is by far the most common.

+

Ordinary guard lines conditions extraction of the code line(s) they +guard by the value of a boolean expression; the guarded block of +code lines will only be included if the expression evaluates to true. +The syntax of an ordinary guard line is one of

+
+    '%' '<' STARSLASH EXPRESSION '>'
+    '%' '<' PLUSMINUS EXPRESSION '>' CODE
+
+

where

+
+    STARSLASH  ::=  '*' | '/'
+    PLUSMINUS  ::=  | '+' | '-'
+    EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION
+                 | SECONDARY '|' EXPRESSION
+    SECONDARY  ::= PRIMARY | PRIMARY '&' SECONDARY
+    PRIMARY    ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')'
+    CODE       ::= { any character except end-of-line }
+
+

Comma and vertical bar both denote 'or'. Ampersand denotes 'and'. +Exclamation mark denotes 'not'. A TERMINAL can be any nonempty string +of characters not containing '>', '&', '|', comma, '(', or ')', +although the docstrip manual is a bit restrictive and only +guarantees proper operation for strings of letters (although even +the LaTeX core sources make heavy use also of digits in TERMINALs). +The second argument of docstrip::extract is the list of those +TERMINALs that should count as having the value 'true'; all other +TERMINALs count as being 'false' when guard expressions are evaluated.

+

In the case of a '%<*EXPRESSION>' guard, the lines guarded are +all lines up to the next '%</EXPRESSION>' guard with the same +EXPRESSION (compared as strings). The blocks of code delimited +by such '*' and '/' guard lines must be properly nested.

+
+   set text [join {
+      {begin}
+      {%<*foo>}
+      {1}
+      {%<*bar>}
+      {2}
+      {%</bar>}
+      {%<*!bar>}
+      {3}
+      {%</!bar>}
+      {4}
+      {%</foo>}
+      {5}
+      {%<*bar>}
+      {6}
+      {%</bar>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text foo]
+   append res [docstrip::extract $text {foo bar}]
+   append res [docstrip::extract $text bar]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      {1}
+      {3}
+      {4}
+      {5}
+      {end}
+      {begin}
+      {1}
+      {2}
+      {4}
+      {5}
+      {6}
+      {end}
+      {begin}
+      {5}
+      {6}
+      {end} ""
+   } \n
+
+

In guard lines without a '*', '/', '+', or '-' modifier after the +'%<', the guard applies only to the CODE following the '>' on that +single line. A '+' modifier is equivalent to no modifier. A '-' +modifier is like the case with no modifier, but the expression is +implicitly negated, i.e., the CODE of a '%<-' guard line is only +included if the expression evaluates to false.

+

Metacomment lines are "comment lines which should not be stripped +away", but be extracted like code lines; these are sometimes used for +copyright notices and similar material. The '%%' prefix is however +not kept, but substituted by the current -metaprefix, which +is customarily set to some "comment until end of line" character (or +character sequence) of the language of the code being extracted.

+
+   set text [join {
+      {begin}
+      {%<foo> foo}
+      {%<+foo>plusfoo}
+      {%<-foo>minusfoo}
+      {middle}
+      {%% some metacomment}
+      {%<*foo>}
+      {%%another metacomment}
+      {%</foo>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text foo -metaprefix {# }]
+   append res [docstrip::extract $text bar -metaprefix {#}]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      { foo}
+      {plusfoo}
+      {middle}
+      {#  some metacomment}
+      {# another metacomment}
+      {end}
+      {begin}
+      {minusfoo}
+      {middle}
+      {# some metacomment}
+      {end} ""
+   } \n
+
+

Verbatim guards can be used to force code line +interpretation of a block of lines even if some of them happen to look +like any other type of lines to docstrip. A verbatim guard has the +form '%<<END-TAG' and the verbatim block is terminated by the +first line that is exactly '%END-TAG'.

+
+   set text [join {
+      {begin}
+      {%<*myblock>}
+      {some stupid()}
+      {   #computer<program>}
+      {%<<QQQ-98765}
+      {% These three lines are copied verbatim (including percents}
+      {%% even if -metaprefix is something different than %%).}
+      {%</myblock>}
+      {%QQQ-98765}
+      {   using*strange@programming<language>}
+      {%</myblock>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text myblock -metaprefix {# }]
+   append res [docstrip::extract $text {}]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      {some stupid()}
+      {   #computer<program>}
+      {% These three lines are copied verbatim (including percents}
+      {%% even if -metaprefix is something different than %%).}
+      {%</myblock>}
+      {   using*strange@programming<language>}
+      {end}
+      {begin}
+      {end} ""
+   } \n
+
+

The processing of verbatim guards takes place also inside blocks of +lines which due to some outer block guard will not be copied.

+

The final piece of docstrip syntax is that extraction +stops at a line that is exactly "\endinput"; this is often used to +avoid copying random whitespace at the end of a file. In the unlikely +case that one wants such a code line, one can protect it with a +verbatim guard.

+
+

Commands

+

The package defines two commands.

+
+
docstrip::extract text terminals ?option value ...?
+

The extract command docstrips the text and returns the + extracted lines of code, as a string with each line terminated with + a newline. The terminals is the list of those guard + expression terminals which should evaluate to true. + The available options are:

+
+ +
-annotate lines
+

Requests the specified number of lines of annotation to follow + each extracted line in the result. Defaults to 0. Annotation lines + are mostly useful when the extracted lines are to undergo some + further transformation. A first annotation line is a list of three + elements: line type, prefix removed in extraction, and prefix + inserted in extraction. The line type is one of: 'V' (verbatim), + 'M' (metacomment), '+' (+ or no modifier guard line), '-' (- + modifier guard line), '.' (normal line). A second annotation line + is the source line number. A third annotation line is the current + stack of block guards. Requesting more than three lines of + annotation is currently not supported.

+
-metaprefix string
+

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

+
-onerror keyword
+

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

+
+ +
ignore
+

Just ignore the error; continue as if nothing happened.

+
puts
+

Write an error message to stderr, then continue + processing.

+
throw
+

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

+
+
-trimlines boolean
+

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

+
+

It should be remarked that the terminals are often called + "options" in the context of the docstrip program, since + these specify which optional code fragments should be included.

+
docstrip::sourcefrom filename terminals ?option value ...?
+

The sourcefrom command is a docstripping emulation of + source. It opens the file filename, reads it, closes it, + docstrips the contents as specified by the terminals, and + evaluates the result in the local context of the caller, during + which time the info script value will be the + filename. The options are passed on to fconfigure to + configure the file before its contents are read. The + -metaprefix is set to '#', all other extract + options have their default values.

+
+
+

Document structure

+

The file format (as described above) determines whether a master +source code file can be processed correctly by docstrip, +but the usefulness of the format is to no little part also dependent +on that the code and comment lines together constitute a well-formed +document.

+

For a document format that does not require any non-Tcl software, see +the ddt2man command in the docstrip::util package. It +is suggested that files employing that document format are given the +suffix ".ddt", to distinguish them from the more traditional +LaTeX-based ".dtx" files.

+

Master source files with ".dtx" extension are usually set up so +that they can be typeset directly by latex without any +support from other files. This is achieved by beginning the file +with the lines

+
+   % \iffalse
+   %<*driver>
+   \documentclass{tclldoc}
+   \begin{document}
+   \DocInput{filename.dtx}
+   \end{document}
+   %</driver>
+   % \fi
+
+

or some variation thereof. The trick is that the file gets read twice. +With normal LaTeX reading rules, the first two lines are comments and +therefore ignored. The third line is the document preamble, the fourth +line begins the document body, and the sixth line ends the document, +so LaTeX stops there — non-comments below that point in +the file are never subjected to the normal LaTeX reading rules. Before +that, however, the \DocInput command on the fifth line is processed, +and that does two things: it changes the interpretation of '%' from +"comment" to "ignored", and it inputs the file specified in the +argument (which is normally the name of the file the command is in). +It is this second time that the file is being read that the comments +and code in it are typeset.

+

The function of the \iffalse ... \fi is to skip lines two to seven +on this second time through; this is similar to the "if 0 { ... }" +idiom for block comments in Tcl code, and it is needed here because +(amongst other things) the \documentclass command may only be +executed once. The function of the <driver> guards is to prevent this +short piece of LaTeX code from being extracted by docstrip. +The total effect is that the file can function both as a LaTeX +document and as a docstrip master source code file.

+

It is not necessary to use the tclldoc document class, but that does +provide a number of features that are convenient for ".dtx" +files containing Tcl code. More information on this matter can be +found in the references above.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/docstrip/docstrip_util.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip_util.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/docstrip/docstrip_util.html @@ -0,0 +1,677 @@ + +docstrip_util - Literate programming tool + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docstrip_util(n) 1.3 tcllib "Literate programming tool"

+

Name

+

docstrip_util - Docstrip-related utilities

+
+ + +

Description

+

The docstrip::util package is meant for collecting various +utility procedures that are mainly useful at installation or +development time. It is separate from the base package to avoid +overhead when the latter is used to source code.

+
+

Package indexing commands

+

Like raw ".tcl" files, code lines in docstrip source files can +be searched for package declarations and corresponding indices +constructed. A complication is however that one cannot tell from the +code blocks themselves which will fit together to make a working +package; normally that information would be found in an accompanying +".ins" file, but parsing one of those is not an easy task. +Therefore docstrip::util introduces an alternative encoding +of such information, in the form of a declarative Tcl script: the +catalogue (of the contents in a source file).

+

The special commands which are available inside a catalogue are:

+
+
pkgProvide name version terminals
+

Declares that the code for a package with name name and + version version is made up from those modules in the source + file which are selected by the terminals list of guard + expression terminals. This code should preferably not contain a + package provide command for the package, as one + will be provided by the package loading mechanisms.

+
pkgIndex ?terminal ...?
+

Declares that the code for a package is made up from those modules + in the source file which are selected by the listed guard + expression terminals. The name and version of this package is + determined from package provide command(s) found + in that code (hence there must be such a command in there).

+
fileoptions ?option value ...?
+

Declares the fconfigure options that should be in force when + reading the source; this can usually be ignored for pure ASCII + files, but if the file needs to be interpreted according to some + other -encoding then this is how to specify it. The + command should normally appear first in the catalogue, as it takes + effect only for commands following it.

+
+

Other Tcl commands are supported too — a catalogue is +parsed by being evaluated in a safe interpreter — but they +are rarely needed. To allow for future extensions, unknown commands +in the catalogue are silently ignored.

+

To simplify distribution of catalogues together with their source +files, the catalogue is stored in the source file itself as +a module selected by the terminal 'docstrip.tcl::catalogue'. +This supports both the style of collecting all catalogue lines in one +place and the style of putting each catalogue line in close proximity +of the code that it declares.

+

Putting catalogue entries next to the code they declare may look as +follows

+
+%    First there's the catalogue entry
+%    \begin{tcl}
+%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
+%    \end{tcl}
+%    second a metacomment used to include a copyright message
+%    \begin{macrocode}
+%<*foobar>
+%% This file is placed in the public domain.
+%    \end{macrocode}
+%    third the package implementation
+%    \begin{tcl}
+namespace eval foo::bar {
+   # ... some clever piece of Tcl code elided ...
+%    \end{tcl}
+%    which at some point may have variant code to make use of a
+%    |load|able extension
+%    \begin{tcl}
+%<*load>
+   load [file rootname [info script]][info sharedlibextension]
+%</load>
+%<*!load>
+   # ... even more clever scripted counterpart of the extension
+   # also elided ...
+%</!load>
+}
+%</foobar>
+%    \end{tcl}
+%    and that's it!
+
+

The corresponding set-up with pkgIndex would be

+
+%    First there's the catalogue entry
+%    \begin{tcl}
+%<docstrip.tcl::catalogue>pkgIndex foobar load
+%    \end{tcl}
+%    second a metacomment used to include a copyright message
+%    \begin{tcl}
+%<*foobar>
+%% This file is placed in the public domain.
+%    \end{tcl}
+%    third the package implementation
+%    \begin{tcl}
+package provide foo::bar 1.0
+namespace eval foo::bar {
+   # ... some clever piece of Tcl code elided ...
+%    \end{tcl}
+%    which at some point may have variant code to make use of a
+%    |load|able extension
+%    \begin{tcl}
+%<*load>
+   load [file rootname [info script]][info sharedlibextension]
+%</load>
+%<*!load>
+   # ... even more clever scripted counterpart of the extension
+   # also elided ...
+%</!load>
+}
+%</foobar>
+%    \end{tcl}
+%    and that's it!
+
+
+
docstrip::util::index_from_catalogue dir pattern ?option value ...?
+

This command is a sibling of the standard pkg_mkIndex + command, in that it adds package entries to "pkgIndex.tcl" + files. The difference is that it indexes docstrip-style + source files rather than raw ".tcl" or loadable library files. + Only packages listed in the catalogue of a file are considered.

+

The dir argument is the directory in which to look for files + (and whose "pkgIndex.tcl" file should be amended). + The pattern argument is a glob pattern of files to look + into; a typical value would be *.dtx or + *.{dtx,ddt}. Remaining arguments are option-value pairs, + where the supported options are:

+
+ +
-recursein dirpattern
+

If this option is given, then the index_from_catalogue + operation will be repeated in each subdirectory whose name + matches the dirpattern. -recursein * will + cause the entire subtree rooted at dir to be indexed.

+
-sourceconf dictionary
+

Specify fileoptions to use when reading the catalogues of + files (and also for reading the packages if the catalogue does + not contain a fileoptions command). Defaults to being + empty. Primarily useful if your system encoding is very different + from that of the source file (e.g., one is a two-byte encoding + and the other is a one-byte encoding). ascii and + utf-8 are not very different in that sense.

+
-options terminals
+

The terminals is a list of terminals in addition to + docstrip.tcl::catalogue that should be held as true when + extracting the catalogue. Defaults to being empty. This makes it + possible to make use of "variant sections" in the catalogue + itself, e.g. gaurd some entries with an extra "experimental" and + thus prevent them from appearing in the index unless that is + generated with "experimental" among the -options.

+
-report boolean
+

If the boolean is true then the return value will be a + textual, probably multiline, report on what was done. Defaults + to false, in which case there is no particular return value.

+
-reportcmd commandPrefix
+

Every item in the report is handed as an extra argument to the + command prefix. Since index_from_catalogue would typically + be used at a rather high level in installation scripts and the + like, the commandPrefix defaults to + "puts stdout". + Use list to effectively disable this feature. The return + values from the prefix are ignored.

+
+

The package ifneeded scripts that are generated contain + one package require docstrip command and one + docstrip::sourcefrom command. If the catalogue entry was + of the pkgProvide kind then the package ifneeded + script also contains the package provide command.

+

Note that index_from_catalogue never removes anything from an + existing "pkgIndex.tcl" file. Hence you may need to delete it + (or have pkg_mkIndex recreate it from scratch) before running + index_from_catalogue to update some piece of information, such + as a package version number.

+
docstrip::util::modules_from_catalogue target source ?option value ...?
+

This command is an alternative to index_from_catalogue which + creates Tcl Module (".tm") files rather than + "pkgIndex.tcl" entries. Since this action is more similar to + what docstrip classically does, it has features for + putting pre- and postambles on the generated files.

+

The source argument is the name of the source file to + generate ".tm" files from. The target argument is the + directory which should count as a module path, i.e., this is what + the relative paths derived from package names are joined to. The + supported options are:

+
+ +
-preamble message
+

A message to put in the preamble (initial block of comments) of + generated files. Defaults to a space. May be several lines, which + are then separated by newlines. Traditionally used for copyright + notices or the like, but metacomment lines provide an alternative + to that.

+
-postamble message
+

Like -preamble, but the message is put at the end of the + file instead of the beginning. Defaults to being empty.

+
-sourceconf dictionary
+

Specify fileoptions to use when reading the catalogue of + the source (and also for reading the packages if the + catalogue does not contain a fileoptions command). Defaults + to being empty. Primarily useful if your system encoding is very + different from that of the source file (e.g., one is a two-byte + encoding and the other is a one-byte encoding). ascii and + utf-8 are not very different in that sense.

+
-options terminals
+

The terminals is a list of terminals in addition to + docstrip.tcl::catalogue that should be held as true when + extracting the catalogue. Defaults to being empty. This makes it + possible to make use of "variant sections" in the catalogue + itself, e.g. gaurd some entries with an extra "experimental" guard + and thus prevent them from contributing packages unless those are + generated with "experimental" among the -options.

+
-formatpreamble commandPrefix
+

Command prefix used to actually format the preamble. Takes four + additional arguments message, targetFilename, + sourceFilename, and terminalList and returns a fully + formatted preamble. Defaults to using classical_preamble + with a metaprefix of '##'.

+
-formatpostamble commandPrefix
+

Command prefix used to actually format the postamble. Takes four + additional arguments message, targetFilename, + sourceFilename, and terminalList and returns a fully + formatted postamble. Defaults to using classical_postamble + with a metaprefix of '##'.

+
-report boolean
+

If the boolean is true (which is the default) then the return + value will be a textual, probably multiline, report on what was + done. If it is false then there is no particular return value.

+
-reportcmd commandPrefix
+

Every item in the report is handed as an extra argument to this + command prefix. Defaults to list, which effectively disables + this feature. The return values from the prefix are ignored. Use + for example "puts stdout" to get report items + written immediately to the terminal.

+
+

An existing file of the same name as one to be created will be + overwritten.

+
docstrip::util::classical_preamble metaprefix message target ?source terminals ...?
+

This command returns a preamble in the classical + docstrip style

+
+##
+## This is `TARGET',
+## generated by the docstrip::util package.
+##
+## The original source files were:
+##
+## SOURCE (with options: `foo,bar')
+##
+## Some message line 1
+## line2
+## line3
+
+

if called as

+
+docstrip::util::classical_preamble {##}\
+  "\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar}
+
+

The command supports preambles for files generated from multiple + sources, even though modules_from_catalogue at present does + not need that.

+
docstrip::util::classical_postamble metaprefix message target ?source terminals ...?
+

This command returns a postamble in the classical + docstrip style

+
+## Some message line 1
+## line2
+## line3
+##
+## End of file `TARGET'.
+
+

if called as

+
+docstrip::util::classical_postamble {##}\
+  "Some message line 1\nline2\nline3" TARGET SOURCE {foo bar}
+
+

In other words, the source and terminals arguments are + ignored, but supported for symmetry with classical_preamble.

+
docstrip::util::packages_provided text ?setup-script?
+

This command returns a list where every even index element is the + name of a package provided by text when that is + evaluated as a Tcl script, and the following odd index element is + the corresponding version. It is used to do package indexing of + extracted pieces of code, in the manner of pkg_mkIndex.

+

One difference to pkg_mkIndex is that the text gets + evaluated in a safe interpreter. package require commands + are silently ignored, as are unknown commands (which includes + source and load). Other errors cause + processing of the text to stop, in which case only those + package declarations that had been encountered before the error + will be included in the return value.

+

The setup-script argument can be used to customise the + evaluation environment, if the code in text has some very + special needs. The setup-script is evaluated in the local + context of the packages_provided procedure just before the + text is processed. At that time, the name of the slave + command for the safe interpreter that will do this processing is + kept in the local variable c. To for example copy the + contents of the ::env array to the safe interpreter, one + might use a setup-script of

+
  $c eval [list array set env [array get ::env]]
+
+
+
+

Source processing commands

+

Unlike the previous group of commands, which would use +docstrip::extract to extract some code lines and then process +those further, the following commands operate on text consisting of +all types of lines.

+
+
docstrip::util::ddt2man text
+

The ddt2man command reformats text from the general + docstrip format to doctools ".man" format + (Tcl Markup Language for Manpages). The different line types are + treated as follows:

+
+ +
comment and metacomment lines
+

The '%' and '%%' prefixes are removed, the rest of the text is + kept as it is.

+
empty lines
+

These are kept as they are. (Effectively this means that they will + count as comment lines after a comment line and as code lines + after a code line.)

+
code lines
+

example_begin and example_end commands are placed + at the beginning and end of every block of consecutive code + lines. Brackets in a code line are converted to lb and + rb commands.

+
verbatim guards
+

These are processed as usual, so they do not show up in the + result but every line in a verbatim block is treated as a code + line.

+
other guards
+

These are treated as code lines, except that the actual guard is + emphasised.

+
+

At the time of writing, no project has employed doctools + markup in master source files, so experience of what works well is + not available. A source file could however look as follows

+
+% [manpage_begin gcd n 1.0]
+% [moddesc {Greatest Common Divisor}]
+% [require gcd [opt 1.0]]
+% [description]
+%
+% [list_begin definitions]
+% [call [cmd gcd] [arg a] [arg b]]
+%   The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
+%   must be integers and returns their greatest common divisor.
+proc gcd {a b} {
+%   The first step is to take the absolute values of the arguments.
+%   This relieves us of having to worry about how signs will be treated
+%   by the remainder operation.
+   set a [expr {abs($a)}]
+   set b [expr {abs($b)}]
+%   The next line does all of Euclid's algorithm! We can make do
+%   without a temporary variable, since $a is substituted before the
+%   [lb]set a $b[rb] and thus continues to hold a reference to the
+%   "old" value of [var a].
+   while {$b>0} { set b [expr { $a % [set a $b] }] }
+%   In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
+%   to get the slight advantage of byte-compilation.
+%<tcl83>  set a
+%<!tcl83>   return $a
+}
+% [list_end]
+%
+% [manpage_end]
+
+

If the above text is fed through docstrip::util::ddt2man then + the result will be a syntactically correct doctools + manpage, even though its purpose is a bit different.

+

It is suggested that master source code files with doctools + markup are given the suffix ".ddt", hence the "ddt" in + ddt2man.

+
docstrip::util::guards subcmd text
+

The guards command returns information (mostly of a + statistical nature) about the ordinary docstrip guards that occur + in the text. The subcmd selects what is returned.

+
+ +
counts
+

List the guard expression terminals with counts. The format of + the return value is a dictionary which maps the terminal name to + the number of occurencies of it in the file.

+
exprcount
+

List the guard expressions with counts. The format of the return + value is a dictionary which maps the expression to the number of + occurencies of it in the file.

+
exprerr
+

List the syntactically incorrect guard expressions (e.g. + parentheses do not match, or a terminal is missing). The return + value is a list, with the elements in no particular order.

+
expressions
+

List the guard expressions. The return value is a list, with the + elements in no particular order.

+
exprmods
+

List the guard expressions with modifiers. The format of the return + value is a dictionary where each index is a guard expression and + each entry is a string with one character for every guard line that + has this expression. The characters in the entry specify what + modifier was used in that line: +, -, *, /, or (for guard without + modifier:) space. This is the most primitive form of the + information gathered by guards.

+
names
+

List the guard expression terminals. The return value is a list, + with the elements in no particular order.

+
rotten
+

List the malformed guard lines (this does not include lines where + only the expression is malformed, though). The format of the return + value is a dictionary which maps line numbers to their contents.

+
+
docstrip::util::patch source-var terminals fromtext diff ?option value ...?
+

This command tries to apply a diff file (for example a + contributed patch) that was computed for a generated file to the + docstrip source. This can be useful if someone has + edited a generated file, thus mistaking it for being the source. + This command makes no presumptions which are specific for the case + that the generated file is a Tcl script.

+

patch requires that the source file to patch is kept as a + list of lines in a variable, and the name of that variable in the + calling context is what goes into the source-var argument. + The terminals is the list of terminals used to extract the + file that has been patched. The diff is the actual diff to + apply (in a format as explained below) and the fromtext is + the contents of the file which served as "from" when the diff was + computed. Options can be used to further control the process.

+

The process works by "lifting" the hunks in the diff from + generated to source file, and then applying them to the elements of + the source-var. In order to do this lifting, it is necessary + to determine how lines in the fromtext correspond to elements + of the source-var, and that is where the terminals come + in; the source is first extracted under the given + terminals, and the result of that is then matched against + the fromtext. This produces a map which translates line + numbers stated in the diff to element numbers in + source-var, which is what is needed to lift the hunks.

+

The reason that both the terminals and the fromtext + must be given is twofold. First, it is very difficult to keep track + of how many lines of preamble are supplied some other way than by + copying lines from source files. Second, a generated file might + contain material from several source files. Both make it impossible + to predict what line number an extracted file would have in the + generated file, so instead the algorithm for computing the line + number map looks for a block of lines in the fromtext which + matches what can be extracted from the source. This matching is + affected by the following options:

+
+ +
-matching mode
+

How equal must two lines be in order to match? The supported + modes are:

+
+ +
exact
+

Lines must be equal as strings. This is the default.

+
anyspace
+

All sequences of whitespace characters are converted to single + spaces before comparing.

+
nonspace
+

Only non-whitespace characters are considered when comparing.

+
none
+

Any two lines are considered to be equal.

+
+
-metaprefix string
+

The -metaprefix value to use when extracting. Defaults + to "%%", but for Tcl code it is more likely that "#" or "##" had + been used for the generated file.

+
-trimlines boolean
+

The -trimlines value to use when extracting. Defaults to + true.

+
+

The return value is in the form of a unified diff, containing only + those hunks which were not applied or were only partially applied; + a comment in the header of each hunk specifies which case is at + hand. It is normally necessary to manually review both the return + value from patch and the patched text itself, as this command + cannot adjust comment lines to match new content.

+

An example use would look like

+
+set sourceL [split [docstrip::util::thefile from.dtx] \n]
+set terminals {foo bar baz}
+set fromtext [docstrip::util::thefile from.tcl]
+set difftext [exec diff --unified from.tcl to.tcl]
+set leftover [docstrip::util::patch sourceL $terminals $fromtext\
+  [docstrip::util::import_unidiff $difftext] -metaprefix {#}]
+set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F
+return $leftover
+
+

Here, "from.dtx" was used as source for "from.tcl", which + someone modified into "to.tcl". We're trying to construct a + "to.dtx" which can be used as source for "to.tcl".

+
docstrip::util::thefile filename ?option value ...?
+

The thefile command opens the file filename, reads it to + end, closes it, and returns the contents (dropping a final newline + if there is one). The option-value pairs are + passed on to fconfigure to configure the open file channel + before anything is read from it.

+
docstrip::util::import_unidiff diff-text ?warning-var?
+

This command parses a unified (diff flags -U and + --unified) format diff into the list-of-hunks format + expected by docstrip::util::patch. The diff-text + argument is the text to parse and the warning-var is, if + specified, the name in the calling context of a variable to which + any warnings about parsing problems will be appended.

+

The return value is a list of hunks. Each hunk is a list of + five elements "start1 end1 start2 end2 + lines". start1 and end1 are line numbers in the + "from" file of the first and last respectively lines of the hunk. + start2 and end2 are the corresponding line numbers in + the "to" file. Line numbers start at 1. The lines is a list + with two elements for each line in the hunk; the first specifies the + type of a line and the second is the actual line contents. The type + is - for lines only in the "from" file, + for lines + that are only in the "to" file, and 0 for lines that are + in both.

+
+
+

See Also

+

docstrip, doctools, doctools_fmt

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/changelog.html Index: embedded/www/tcllib/files/modules/doctools/changelog.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/changelog.html @@ -0,0 +1,210 @@ + + +doctools::changelog - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::changelog(n) 1.1 tcllib "Documentation tools"

+

Name

+

doctools::changelog - Processing text in Emacs ChangeLog format

+
+ + +

Description

+

This package provides Tcl commands for the processing and reformatting +of text in the "ChangeLog" format generated by emacs.

+
+

API

+
+
::doctools::changelog::scan text
+

The command takes the text and parses it under the assumption +that it contains a ChangeLog as generated by emacs. It +returns a data structure describing the contents of this ChangeLog.

+

This data structure is a list where each element describes one entry +in the ChangeLog. Each element/entry is then a list of three elements +describing the date of the entry, its author, and the comments made, +in this order. The last item in each element/entry, the comments, is a +list of sections. Each section is described by a list containing two +elements, a list of file names, and a string containing the true +comment associated with the files of the section.

+
+    {
+	{
+	    date
+	    author
+	    {
+		{
+		    {file ...}
+		    commenttext
+		}
+		...
+	    }
+	}
+	{...}
+    }
+
+
+
::doctools::changelog::flatten entries
+

This command converts a list of entries as generated by +change::scan above into a simpler list of plain +text blocks each containing all the information of a +single entry.

+
::doctools::changelog::toDoctools title module version entries
+

This command converts the pre-parsed ChangeLog entries as +generated by the command ::doctools::changelog::scan into a +document in doctools format and returns it as the result of the +command.

+

The other three arguments supply the information for the header of +that document which is not available from the changelog itself.

+
::doctools::changelog::merge entries...
+

Each argument of the command is assumed to be a pre-parsed Changelog +as generated by the command ::doctools::changelog::scan. This +command merges all of them into a single structure, and collapses +multiple entries for the same date and author into a single entry. The +new structure is returned as the result of the command.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/cvs.html Index: embedded/www/tcllib/files/modules/doctools/cvs.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/cvs.html @@ -0,0 +1,208 @@ + + +doctools::cvs - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::cvs(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::cvs - Processing text in 'cvs log' format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil
    • +
  • package require doctools::cvs ?1?
    • +
+ +
+
+

Description

+

This package provides Tcl commands for the processing and reformatting +text in the format generated by the cvs log command.

+

The commands ::doctools::cvs::scanLog +and ::doctools::cvs::toChangeLog are derived from code found on +the Tcl'ers Wiki. See the references at the +end of the page.

+
+

API

+
+
::doctools::cvs::scanLog text evar cvar fvar
+

The command takes the text and parses it under the assumption +that it contains a CVS log as generated by cvs log. The +resulting information is stored in the variables whose names were +specified via evar, cvar, and fvar.

+

Already existing information in the referenced variables is preserved, +allowing the caller to merge data from multiple logs into one +database.

+
+
varname evar (in)
+

Has to refer to a scalar variable. After the call this variable will +contain a list of all the entries found in the log file. An entry is +identified through the combination of date and author, and can be +split over multiple physical entries, one per touched file.

+

It should be noted that the entries are listed in the same order as +they were found in the text. This is not necessarily sorted by +date or author.

+

Each item in the list is a list containing two elements, the date of +the entry, and its author, in this order. The date is formatted as +year/month/day.

+
varname cvar (in)
+

Has to refer to an array variable. Keys are strings containing the +date and author of log entries, in this order, separated by a comma.

+

The values are lists of comments made for the entry.

+
varname fvar (in)
+

Has to refer to an array variable. Keys are strings containing +date, author of a log entry, and a comment for that entry, in this +order, separated by commas.

+

The values are lists of the files the entry is touching.

+
+
::doctools::cvs::toChangeLog evar cvar fvar
+

] +The three arguments for this command are the same as the last three +arguments of the command ::doctools::cvs::scanLog. This command +however expects them to be filled with information about one or more +logs. It takes this information and converts it into a text in the +format of a ChangeLog as accepted and generated by emacs. The +constructed text is returned as the result of the command.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx.html Index: embedded/www/tcllib/files/modules/doctools/docidx.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx.html @@ -0,0 +1,413 @@ + + +doctools::idx - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx(n) 1.0.4 tcllib "Documentation tools"

+

Name

+

doctools::idx - docidx - Processing indices

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the docidx markup language +into any output format X for which a formatting engine is +available.

+

A reader interested in the markup language itself should start with +the docidx language introduction and proceed from there to +the formal specifications, i.e. the docidx language syntax +and the docidx language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the docidx plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::idx::new objectName ?-option value ...?
+

This command creates a new docidx object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::idx::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::idx::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::idx::new have the following +general form and may be used to invoke various operations on their +docidx converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in docidx format as +specified in the companion document docidx_fmt. Errors will be +thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +docidx plugin API reference which specifies the interaction +between the objects created by this package and index formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for index +formatting engines. See also the command ::doctools::idx::search +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All docidx objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_file. +This command is described in more detail in the companion document +docidx_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "idx.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "idx.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::idx::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. In other words, if the +package implementation "docidx.tcl" is installed in the directory +"/usr/local/lib/tcllib/doctools" then it will by default search +the directory "/usr/local/lib/tcllib/doctools/mpformats" for +format implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_intro.html @@ -0,0 +1,194 @@ + + +docidx_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_intro - docidx introduction

+
+ +

Description

+

docidx (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of keyword-based +indices for documentation. These are

+
    +

  1. A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

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

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +docidx language introduction first. Having digested this +the formal docidx language syntax specification should +become understandable. A writer experienced with docidx may only +need the docidx language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them.

    2. +

  2. A processor of documentation written in the docidx +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose docidx to the +user. +At the bottom level, common to both applications, however sits the +package doctoools::idx, providing the basic facilities to +read and process files containing text in the docidx format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools::idx package and its +plugins, as described in the docidx plugin API reference.

    4. +
+
+

RELATED FORMATS

+

docidx does not stand alone, it has two companion formats. These are +called doctoc and doctools, and they are for the markup +of tables of contents, and general documentation, +respectively. +They are described in their own sets of documents, starting at the +doctoc introduction and the doctools introduction, +respectively.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html @@ -0,0 +1,227 @@ + + +docidx_lang_cmdref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_cmdref - docidx language command reference

+
+ + +

Description

+

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

+
+

Commands

+
+
comment plaintext
+

Index markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the docidx markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
index_begin text title
+

Document structure. The command to start an index. The arguments are a +label for the whole group of documents the index refers to +(text) and the overall title text for the index (title), +without markup.

+

The label often is the name of the package (or extension) the +documents belong to.

+
index_end
+

Document structure. Command to end an index. Anything in the document +coming after this command is in error.

+
key text
+

Index structure. This command adds the keyword text to the +index.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands.

+
manpage file text
+

Index structure. This command adds an element to the index which +refers to a document. The document is specified through the symbolic +name file. The text argument is used to label the +reference.

+

Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of the file will be inserted by +the chosen formatting engine when converting the input. This will be +based on a mapping from symbolic to actual names given to the engine.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands.

+
url url label
+

Index structure. This is the second command to add an element to the +index. To refer to a document it is not using a symbolic name however, +but a (possibly format-specific) url describing the exact location of +the document indexed here.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html @@ -0,0 +1,183 @@ + + +docidx_lang_faq - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_faq - docidx language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the docidx markup language and +companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document in the category doctools of the +Tcllib SF Trackers.

+
+
+

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 +keyword indices when processing a set of documents written in doctools +markup. The intermediate files use docidx markup and are not deleted +when generation completes. These files can therefore serve as +examples.

+

dtplite is distributed as part of Tcllib, so to get it you +need one of

+
    +

  1. A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +http://sourceforge.net/cvs/?group_id=12883

    2. +

  2. A Tcllib release archive. They are available at +http://sourceforge.net/project/showfiles.php?group_id=12883

    3. +
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html @@ -0,0 +1,292 @@ + + +docidx_lang_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_intro - docidx language introduction

+
+ +

Description

+

This document is an informal introduction to version 1 of the docidx +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the docidx language syntax specification +and the docidx language command reference.

+

Fundamentals

+

While the docidx markup language is quite similar to the +doctools markup language, in the broadest terms possible, +there is one key difference. An index consists essentially only of +markup commands, with no plain text interspersed between them, except +for whitespace.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

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

Basic structure

+

The most simple document which can be written in docidx is

+
+    [index_begin GROUPTITLE TITLE]
+    [index_end]
+
+

Not very useful, but valid. This also shows us that all docidx +documents consist of only one part where we will list all keys and +their references.

+

A more useful index will contain at least keywords, or short 'keys', +i.e. the phrases which were indexed. So:

+
+[index_begin GROUPTITLE TITLE]
+[key markup]
+[key {semantic markup}]]
+[key {docidx markup}]
+[key {docidx language}]
+[key {docidx commands}]
+[index_end]
+
+

In the above example the command key is used to declare the +keyword phrases we wish to be part of the index.

+

However a truly useful index does not only list the keyword phrases, +but will also contain references to documents associated with the +keywords. Here is a made-up index for all the manpages in the module +base64:

+
+[index_begin tcllib/base64 {De- & Encoding}]
+[key base64]
+[manpage base64]
+[key encoding]
+[manpage base64]
+[manpage uuencode]
+[manpage yencode]
+[key uuencode]
+[manpage uuencode]
+[key yEnc]
+[manpage yencode]
+[key ydecode]
+[manpage yencode]
+[key yencode]
+[manpage yencode]
+[index_end]
+
+

In the above example the command manpage is used to insert +references to documents, using symbolic file names, with each command +belonging to the last key command coming before it.

+

The other command to insert references is url. In contrast to +manpage it uses explicit (possibly format-specific) urls to +describe the location of the referenced document. As such this command +is intended for the creation of references to external documents which +could not be handled in any other way.

+
+

Advanced structure

+

In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the index_begin command opening the +document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[index_begin GROUPTITLE TITLE]
+...
+[index_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure.

+
+[index_begin GROUPTITLE TITLE]
+[include FILE]
+[vset VAR VALUE]
+...
+[index_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before index_begin may contain only the templating +commands vset and include, a file included after a key +may contain only manape or url references, and other keys, etc.

+
+

Escapes

+

Beyond the 6 commands shown so far we have two more available. +However their function is not the marking up of index structure, but +the insertion of characters, namely [ and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal docidx language syntax +specification as well. From here on out the +docidx language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +dtp.

+

On the other hand, docidx is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple dtplite goes, creating an index for a set of +documents behind the scenes, without the writer having to do so on +their own.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html @@ -0,0 +1,212 @@ + + +docidx_lang_syntax - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_syntax - docidx language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +docidx markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +docidx language command reference. +A beginner should read the much more informally written +docidx language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the docidx markup language is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +docidx language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of docidx documents. The +lexical level of the language was covered in the previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +
+

The syntax:

+
+index     = defs
+            INDEX_BEGIN
+            [ contents ]
+            INDEX_END  
+            { <WHITE> }
+defs      = { INCLUDE | VSET | <WHITE> }
+contents  = keyword { keyword }
+keyword   = defs KEY ref { ref }
+ref       = MANPAGE | URL | defs
+
+

At last a rule we were unable to capture in the EBNF syntax, as it is +about the arguments of the markup commands, something which is not +modeled here.

+
    +

  1. The arguments of all markup commands have to be plain text, and/or text +markup commands, i.e. one of

    +
      +

    1. lb,

      2. +

    2. rb, or

      3. +

    3. vset (1-argument form).

      4. +
    +
    2. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html @@ -0,0 +1,441 @@ + + +docidx_plugin_apiref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

docidx_plugin_apiref(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_plugin_apiref - docidx plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write an index formatting engine for some output +format X.

+

It specifies the interaction between the doctools::idx +package and its plugins, i.e. the interface any index formatting +engine has to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +docidx language introduction and proceed from there to the +formal specifications, i.e. the docidx language syntax and +the docidx language command reference.

+
+

OVERVIEW

+

The API for an index formatting engine consists of two major sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as an index formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. an index formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools::idx.

+
dt_format
+

Query command. It returns the name of the format associated with the +index formatting engine.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the index formatting +engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    idx_numpasses -> n
+    idx_listvariables -> vars
+    idx_varset var1 value1
+    idx_varset var2 value2
+    ...
+    idx_varset varK valueK
+    idx_initialize
+    idx_setup 1
+    ...
+    idx_setup 2
+    ...
+    ...
+    idx_setup n
+    ...
+    idx_postprocess
+    idx_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at idx_varset.

+

In each of the passes, i.e. after the calls of idx_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the docidx markup language, +as specified in the docidx language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first idx_varset to +idx_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with idx_setup and going until either the next +idx_setup or idx_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
idx_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
idx_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after idx_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
idx_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
idx_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
idx_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
idx_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
idx_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by idx_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the docidx markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the five markup commands specified in the +docidx language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +docidx language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the docidx +markup language, as specified in the docidx language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc.html Index: embedded/www/tcllib/files/modules/doctools/doctoc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc.html @@ -0,0 +1,413 @@ + + +doctools::toc - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc(n) 1.1.3 tcllib "Documentation tools"

+

Name

+

doctools::toc - doctoc - Processing tables of contents

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the doctoc markup language +into any output format X for which a formatting engine is +available.

+

A reader interested in the markup language itself should start with +the doctoc language introduction and proceed from there to +the formal specifications, i.e. the doctoc language syntax +and the doctoc language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the doctoc plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::toc::new objectName ?-option value ...?
+

This command creates a new doctoc object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::toc::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::toc::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::toc::new have the following +general form and may be used to invoke various operations on their +doctoc converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in doctoc format as +specified in the companion document doctoc_fmt. Errors will be +thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +doctoc plugin API reference which specifies the interaction +between the objects created by this package and toc formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for toc +formatting engines. See also the command ::doctools::toc::search +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All doctoc objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_file. +This command is described in more detail in the companion document +doctoc_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "toc.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "toc.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::toc::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. In other words, if the +package implementation "doctoc.tcl" is installed in the directory +"/usr/local/lib/tcllib/doctools" then it will by default search +the directory "/usr/local/lib/tcllib/doctools/mpformats" for +format implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_intro.html @@ -0,0 +1,193 @@ + + +doctoc_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_intro - doctoc introduction

+
+ +

Description

+

doctoc (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables of +contents for documentation. These are

+
    +

  1. A tcl based language for the semantic markup of a table of +contents. Markup is represented by Tcl commands.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

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

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +doctoc language introduction first. Having digested this +the formal doctoc language syntax specification should +become understandable. A writer experienced with doctoc may only +need the doctoc language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them.

    2. +

  2. A processor of documentation written in the doctoc +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose doctoc to the +user. +At the bottom level, common to both applications, however sits the +package doctoools::toc, providing the basic facilities to +read and process files containing text in the doctoc format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools::toc package and its +plugins, as described in the doctoc plugin API reference.

    4. +
+
+

RELATED FORMATS

+

doctoc does not stand alone, it has two companion formats. These are +called docidx and doctools, and they are for the markup +of keyword indices, and general documentation, respectively. +They are described in their own sets of documents, starting at the +docidx introduction and the doctools introduction, +respectively.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html @@ -0,0 +1,232 @@ + + +doctoc_lang_cmdref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_cmdref - doctoc language command reference

+
+ + +

Description

+

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

+
+

Commands

+
+
comment plaintext
+

Toc markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
division_end
+

Toc structure. This command closes the division opened by the last +division_begin command coming before it, and not yet closed.

+
division_start text ?symfile?
+

Toc structure. This command opens a division in the table of +contents. Its counterpart is division_end. Together they allow a +user to give a table of contents additional structure.

+

The title of the new division is provided by the argument text.

+

If the symbolic filename symfile is present then the section +title should link to the referenced document, if links are supported +by the output format.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the doctoc markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
item file text desc
+

Toc structure. This command adds an individual element to the table of +contents. Each such element refers to a document. The document is +specified through the symbolic name file. The text +argument is used to label the reference, whereas the desc +provides a short descriptive text of that document.

+

The symbolic names are used to preserve the convertibility of this +format to any output format. The actual name of the file will be +inserted by the chosen formatting engine when converting the +input. This will be based on a mapping from symbolic to actual names +given to the engine.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands.

+
toc_begin text title
+

Document structure. The command to start a table of contents. The +arguments are a label for the whole group of documents the index +refers to (text) and the overall title text for the index +(title), without markup.

+

The label often is the name of the package (or extension) the +documents belong to.

+
toc_end
+

Document structure. Command to end a table of contents. Anything in +the document coming after this command is in error.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html @@ -0,0 +1,183 @@ + + +doctoc_lang_faq - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_faq - doctoc language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the doctoc markup language and +companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document in the category doctools of the +Tcllib SF Trackers.

+
+
+

EXAMPLES

+

Where do I find doctoc examples?

+

We have no direct examples of documents written using doctoc +markup. However the doctools processor dtplite does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses doctoc markup and +is not deleted when generation completes. Such files can therefore +serve as examples.

+

dtplite is distributed as part of Tcllib, so to get it you +need one of

+
    +

  1. A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +http://sourceforge.net/cvs/?group_id=12883

    2. +

  2. A Tcllib release archive. They are available at +http://sourceforge.net/project/showfiles.php?group_id=12883

    3. +
+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html @@ -0,0 +1,357 @@ + + +doctoc_lang_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_intro - doctoc language introduction

+
+ +

Description

+

This document is an informal introduction to version 1.1 of the doctoc +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the doctoc language syntax specification +and the doctoc language command reference.

+

Fundamentals

+

While the doctoc markup language is quite similar to the +doctools markup language, in the broadest terms possible, +there is one key difference. A table of contents consists essentially +only of markup commands, with no plain text interspersed between them, +except for whitespace.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

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

Basic structure

+

The most simple document which can be written in doctoc is

+
+    [toc_begin GROUPTITLE TITLE]
+    [toc_end]
+
+

This also shows us that all doctoc documents consist of only one +part where we will list items and divisions.

+

The user is free to mix these as she sees fit. This is a change from +version 1 of the language, which did not allow this mixing, but only +the use of either a series of items or a series of divisions.

+

We will discuss the commands for each of these two possibilities in +the next sections.

+
+

Items

+

Use the command item to put an item into a table of +contents. This is essentially a reference to a section, subsection, +etc. in the document, or set of documents, the table of contents is +for. The command takes three arguments, a symbolic name for the file +the item is for and two text to label the item and describe the +referenced section.

+

Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of any file will be inserted by +the chosen formatting engine when converting the input, based on a +mapping from symbolic to actual names given to the engine.

+

Here a made up example for a table of contents of this document:

+
+[toc_begin Doctoc {Language Introduction}]
+[item 1 DESCRIPTION]
+[item 1.1 {Basic structure}]
+[item 1.2 Items]
+[item 1.3 Divisions]
+[item 2 {FURTHER READING}]
+[toc_end]
+
+
+

Divisions

+

One thing of notice in the last example in the previous section is +that the referenced sections actually had a nested structure, +something which was expressed in the item labels, by using a common +prefix for all the sections nested under section 1.

+

This kind of structure can be made more explicit in the doctoc +language by using divisions. Instead of using a series of plain items +we use a series of divisions for the major references, and then place +the nested items inside of these.

+

Of course, instead of the nested items we can again use divisions and +thus nest arbitrarily deep.

+

A division is marked by two commands instead of one, one to start it, +the other to close the last opened division. They are:

+
+
division_start
+

This command opens a new division. It takes one or two arguments, the +title of the division, and the symbolic name of the file it refers +to. The latter is optional. +If the symbolic filename is present then the section title should link +to the referenced document, if links are supported by the output +format.

+
division_end
+

This command closes the last opened and not yet closed division.

+
+

Using this we can recast the last example like this

+
+[toc_begin Doctoc {Language Introduction}]
+[division_start DESCRIPTION]
+[item 1 {Basic structure}]
+[item 2 Items]
+[item 3 Divisions]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+

Or, to demonstrate deeper nesting

+
+[toc_begin Doctoc {Language Introduction}]
+[division_start DESCRIPTION]
+[division_start {Basic structure}]
+[item 1 Do]
+[item 2 Re]
+[division_end]
+[division_start Items]
+[item a Fi]
+[item b Fo]
+[item c Fa]
+[division_end]
+[division_start Divisions]
+[item 1 Sub]
+[item 1 Zero]
+[division_end]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+

And do not forget, it is possible to freely mix items and divisions, +and to have empty divisions.

+
+[toc_begin Doctoc {Language Introduction}]
+[item 1 Do]
+[division_start DESCRIPTION]
+[division_start {Basic structure}]
+[item 2 Re]
+[division_end]
+[item a Fi]
+[division_start Items]
+[item b Fo]
+[item c Fa]
+[division_end]
+[division_start Divisions]
+[division_end]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+
+

Advanced structure

+

In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the toc_begin command opening the +document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[toc_begin GROUPTITLE TITLE]
+...
+[toc_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure.

+
+[toc_begin GROUPTITLE TITLE]
+[include FILE]
+[vset VAR VALUE]
+...
+[toc_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before toc_begin may contain only the templating +commands vset and include, a file included in a division +may contain only items or divisions commands, etc.

+
+

Escapes

+

Beyond the 6 commands shown so far we have two more available. +However their function is not the marking up of toc structure, but the +insertion of characters, namely [ and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal doctoc language syntax +specification as well. From here on out the +doctoc language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +dtp.

+

On the other hand, doctoc is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple dtplite goes, creating a table of contents +for a set of documents behind the scenes, without the writer having to +do so on their own.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html @@ -0,0 +1,201 @@ + + +doctoc_lang_syntax - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_syntax - doctoc language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +doctoc markup language, version 1.1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +doctoc language command reference. +A beginner should read the much more informally written +doctoc language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the doctoc markup language is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +doctoc language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of doctoc documents. The +lexical level of the language was covered in the previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +
+

The syntax:

+
+toc       = defs
+            TOC_BEGIN
+            contents
+            TOC_END  
+            { <WHITE> }
+defs      = { INCLUDE | VSET | <WHITE> }
+contents  = { defs entry } [ defs ]
+entry     = ITEM | division
+division  = DIVISION_START
+            contents
+            DIVISION_END
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html @@ -0,0 +1,441 @@ + + +doctoc_plugin_apiref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctoc_plugin_apiref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_plugin_apiref - doctoc plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write a toc formatting engine for some output +format X.

+

It specifies the interaction between the doctools::toc +package and its plugins, i.e. the interface any toc formatting engine +has to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +doctoc language introduction and proceed from there to the +formal specifications, i.e. the doctoc language syntax and +the doctoc language command reference.

+
+

OVERVIEW

+

The API for a toc formatting engine consists of two major sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as a toc formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. a toc formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools::toc.

+
dt_format
+

Query command. It returns the name of the format associated with the +toc formatting engine.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the toc formatting +engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    toc_numpasses -> n
+    toc_listvariables -> vars
+    toc_varset var1 value1
+    toc_varset var2 value2
+    ...
+    toc_varset varK valueK
+    toc_initialize
+    toc_setup 1
+    ...
+    toc_setup 2
+    ...
+    ...
+    toc_setup n
+    ...
+    toc_postprocess
+    toc_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at toc_varset.

+

In each of the passes, i.e. after the calls of toc_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctoc markup language, +as specified in the doctoc language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first toc_varset to +toc_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with toc_setup and going until either the next +toc_setup or toc_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
toc_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
toc_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after toc_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
toc_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
toc_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
toc_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
toc_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
toc_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by toc_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctoc markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the five markup commands specified in the +doctoc language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +doctoc language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctoc +markup language, as specified in the doctoc language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools.html Index: embedded/www/tcllib/files/modules/doctools/doctools.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools.html @@ -0,0 +1,501 @@ + + +doctools - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools(n) 1.4.14 tcllib "Documentation tools"

+

Name

+

doctools - doctools - Processing documents

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the doctools markup +language into any output format X for which a +formatting engine is available.

+

A reader interested in the markup language itself should start with +the doctools language introduction and proceed from there to +the formal specifications, i.e. the doctools language syntax +and the doctools language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the doctools plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::new objectName ?option value...?
+

This command creates a new doctools object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::new have the following +general form and may be used to invoke various operations on their +doctools converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in doctools format as +specified in the companion document doctools_fmt. Errors will +be thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +doctools plugin API reference which specifies the interaction +between the objects created by this package and doctools formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for doctools +formatting engines. See also the command ::doctools::search on +how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All doctools objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the commands dt_file +and dt_mainfile. +These commands are described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-ibase file
+

The argument of this option is stored in the object and used as the +base path for resolution of relative include paths. If this option is +not set (empty string) the value of -file is used instead.

+

Note that -file and -ibase, while similar looking, +are actually very different. The value of -file is used by +some engines for the generation of proper relative references between +output documents (HTML). As such this is a destination +path. The -ibase on the other hand is used to resolve +relative include paths, and as such deals with source paths.

+

The default value of this option is the empty string.

+
-module text
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_module. +This command is described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the module the file containing the document which is currently +processed belongs to.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
-deprecated boolean
+

This option is a boolean flag. The object will generate warnings if +this flag is set and the text given to method format contains +the deprecated markup command strong. +Its default value is FALSE. In other words, no warnings will +be generated.

+
-copyright text
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_copyright. +This command is described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as a +copyright assignment for the document which is currently processed, or +the package described by it.

+

This information must be used if and only if the engine is unable to +find any copyright assignments within the document itself. Such are +specified by the formatting command copyright. This command is +described in more detail in the companion document doctools_fmt +which specifies the doctools format itself.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "fmt.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "fmt.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. +In other words, if the package implementation "doctools.tcl" is +installed in the directory "/usr/local/lib/tcllib/doctools" then +it will by default search the +directory "/usr/local/lib/tcllib/doctools/mpformats" for format +implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined engines for the following +formats. Some of the engines support parameters. These will be +explained below as well.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports four parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
xref
+

The value for this parameter has to be a list of triples specifying +cross-reference information. This information is used by the engine to +create more hyperlinks. Each triple is a list containing a pattern, +symbolic filename and fragment reference, in this order. If a pattern +is specified multiple times the last occurence of the pattern will be +used.

+

The engine will consult the xref database when encountering specific +commands and will create a link if the relevant text matches one of +the patterns. No link will be created if no match was found. The link +will go to the uri file#fragment listed in the relevant +triple, after conversion of the symbolic file name to the actual uri +via dt_fmap (see the doctools plugin API reference). +This file-to-uri mapping was build by calls to the method map +of the doctools object (See section OBJECT METHODS).

+

The following formatting commands will consult the xref database:

+
+
cmd word
+

The command will look for the patterns sa,word, and +word, in this order. If this fails if it will convert word +to all lowercase and try again.

+
syscmd word
+

The command will look for the patterns sa,word, and +word, in this order. If this fails if it will convert word +to all lowercase and try again.

+
term word
+

The command will look for the patterns kw,word, +sa,word, and word, in this order. If this fails if +it will convert word to all lowercase and try again.

+
package word
+

The command will look for the patterns sa,word, +kw,word, and word, in this order. If this fails if +it will convert word to all lowercase and try again.

+
see_also word...
+

The command will look for the patterns sa,word, and +word, in this order, for each word given to the +command. If this fails if it will convert word to all lowercase +and try again.

+
keywords word...
+

The command will look for the patterns kw,word, and +word, in this order, for each word given to the +command. If this fails if it will convert word to all lowercase +and try again.

+
+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

BUGS, IDEAS, FEEDBACK

+

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

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_intro.html @@ -0,0 +1,192 @@ + + +doctools_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_intro - doctools introduction

+
+ +

Description

+

doctools (short for documentation tools) stands for +a set of related, yet different, entities which are working together +for the easy creation and transformation of documentation. These are

+
    +

  1. A tcl based language for the semantic markup of text. Markup is +represented by Tcl commands interspersed with the actual text.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctools should read the more informally written +doctools language introduction first. Having digested this +the formal doctools language syntax specification should +become understandable. A writer experienced with doctools may only +need the doctools language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtplite application can be +used to validate it, and after completion it also performs the +conversion into the chosen system of visual markup, be it *roff, HTML, +plain text, wiki, etc.

    2. +

  2. A processor of documentation written in the doctools +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtplite application +provided by Tcllib. A more powerful one (in terms of options and +ability to configure it) is the dtp application, provided by +Tclapps. +At the bottom level, common to both applications, however sits the +package doctools, providing the basic facilities to read and +process files containing text in the doctools format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools package and its plugins, as +described in the doctools plugin API reference.

    4. +
+
+

RELATED FORMATS

+

doctools does not stand alone, it has two companion formats. These are +called docidx and doctoc, and they are for the markup of +keyword indices, and tables of contents, +respectively. +They are described in their own sets of documents, starting at the +docidx introduction and the doctoc introduction, +respectively.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html @@ -0,0 +1,534 @@ + + +doctools_lang_cmdref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_cmdref - doctools language command reference

+
+ + +

Description

+

This document specifies both names and syntax of all the commands +which together are the doctools markup language, version 1. +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. +A beginner should read the much more informally written +doctools language introduction first.

+
+

Commands

+
+
arg text
+

Text markup. The argument text is marked up as the argument of +a command. Main uses are the highlighting of command arguments in +free-form text, and for the argument parameters of the markup commands +call and usage.

+
arg_def type name ?mode?
+

Text structure. List element. Argument list. Automatically closes the +previous list element. Specifies the data-type of the described +argument of a command, its name and its i/o-mode. The +latter is optional.

+
bullet
+

Deprecated. Text structure. List element. Itemized list. See +item for the canonical command to open a list item in an +itemized list.

+
call args
+

Text structure. List element. Definition list. Automatically closes +the previous list element. Defines the term as a command and its +arguments. +The first argument is the name of the command described by the +following free-form text, and all arguments coming after that are +descriptions of the command's arguments. +It is expected that the arguments are marked up with arg, +method, option etc., as is appropriate, and that the +command itself is marked up with cmd. +It is expected that the formatted term is not only printed in place, +but also in the table of contents of the document, or synopsis, +depending on the output format.

+
category text
+

Document information. Anywhere. This command registers its plain text +arguments as the category this document belongs to. If this command is +used multiple times the last value specified is used.

+
class text
+

Text markup. The argument is marked up as the name of a +class. The text may have other markup already applied to +it. Main use is the highlighting of class names in free-form text.

+
cmd text
+

Text markup. The argument text is marked up as the name of a +Tcl command. The text may have other markup already applied +to it. Main uses are the highlighting of commands in free-form text, +and for the command parameters of the markup commands call and +usage.

+
cmd_def command
+

Text structure. List element. Command list. Automatically closes the +previous list element. The argument specifies the name of the +Tcl command to be described by the list element. Expected to +be marked up in the output as if it had been formatted with cmd.

+
comment plaintext
+

Text markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
const text
+

Text markup. The argument is marked up as a constant value. The +text may have other markup already applied to it. Main use is the +highlighting of constants in free-form text.

+
copyright text
+

Document information. Anywhere. The command registers the plain text +argument as a copyright assignment for the manpage. When invoked more +than once the assignments are accumulated.

+
def text
+

Text structure. List element. Definition list. Automatically closes +the previous list element. The argument text is the term defined by +the new list element. Text markup can be applied to it.

+
description
+

Document structure. This command separates the header from the +document body. Implicitly starts a section named "DESCRIPTION" (See +command section).

+
enum
+

Text structure. List element. Enumerated list. Automatically closes +the previous list element.

+
emph text
+

Text markup. The argument text is marked up as emphasized. Main use is +for general highlighting of pieces of free-form text without attaching +special meaning to the pieces.

+
example text
+

Text structure, Text markup. This command marks its argument up as an +example. Main use is the simple embedding of examples in +free-form text. It should be used if the example does not need +special markup of its own. Otherwise use a sequence of +example_begin ... example_end.

+
example_begin
+

Text structure. This commands starts an example. All text until the +next example_end belongs to the example. Line breaks, spaces, +and tabs have to be preserved literally. Examples cannot be nested.

+
example_end
+

Text structure. This command closes the example started by the last +example_begin.

+
file text
+

Text markup. The argument is marked up as a file or +directory, i.e. in general a path. The text may have +other markup already applied to it. Main use is the highlighting of +paths in free-form text.

+
fun text
+

Text markup. The argument is marked up as the name of a +function. The text may have other markup already applied to +it. Main use is the highlighting of function names in free-form text.

+
image name ?label?
+

Text markup. The argument is the symbolic name of an image +and replaced with the image itself, if a suitable variant is found +by the backend. The second argument, should it be present, will be +interpreted the human-readable description of the image, and put +into the output in a suitable position, if such is supported by the +format. The HTML format, for example, can place it into the alt +attribute of image references.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the doctools markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
item
+

Text structure. List element. Itemized list. Automatically closes the +previous list element.

+
keywords args
+

Document information. Anywhere. This command registers all its plain text +arguments as keywords applying to this document. Each argument is a single +keyword. If this command is used multiple times all the arguments accumulate.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form text. +Required to avoid interpretation of a left bracket as the start of a markup +command.

+
list_begin what
+

Text structure. This command starts a list. The exact nature of the +list is determined by the argument what of the command. This +further determines which commands are have to be used to start the +list elements. Lists can be nested, i.e. it is allowed to start a new +list within a list element.

+

The allowed types (and their associated item commands) are:

+
+
arguments
+

arg_def.

+
commands
+

cmd_def.

+
definitions
+

def and call.

+
enumerated
+

enum

+
itemized
+

item

+
options
+

opt_def

+
tkoptions
+

tkoption_def

+
+

Additionally the following names are recognized as shortcuts for some +of the regular types:

+
+
args
+

Short for arguments.

+
cmds
+

Short for commands.

+
enum
+

Short for enumerated.

+
item
+

Short for itemized.

+
opts
+

Short for options.

+
+

At last the following names are still recognized for backward +compatibility, but are otherwise considered to be deprecated.

+
+
arg
+

Deprecated. See arguments.

+
bullet
+

Deprecated. See itemized.

+
cmd
+

Deprecated. See commands.

+
opt
+

Deprecated. See options.

+
tkoption
+

Deprecated. See tkoptions.

+
+
list_end
+

Text structure. This command closes the list opened by the last +list_begin command coming before it.

+
lst_item text
+

Deprecated. Text structure. List element. Definition list. See +def for the canonical command to open a general list item in a +definition list.

+
manpage_begin command section version
+

Document structure. The command to start a manpage. The arguments are +the name of the command described by the manpage, the +section of the manpages this manpage resides in, and the +version of the module containing the command. All arguments have +to be plain text, without markup.

+
manpage_end
+

Document structure. Command to end a manpage/document. Anything in the document +coming after this command is in error.

+
method text
+

Text markup. The argument text is marked up as the name of an +object method, i.e. subcommand of a Tcl command. The +text may have other markup already applied to it. Main uses are the +highlighting of method names in free-form text, and for the command +parameters of the markup commands call and usage.

+
moddesc text
+

Document information. Header. Registers the plain text argument as a short +description of the module the manpage resides in.

+
namespace text
+

Text markup. The argument text is marked up as a namespace name. The +text may have other markup already applied to it. Main use is the +highlighting of namespace names in free-form text.

+
nl
+

Deprecated. Text structure. See para for the canonical +command to insert paragraph breaks into the text.

+
opt text
+

Text markup. The argument text is marked up as optional. The text may +have other markup already applied to it. Main use is the highlighting of +optional arguments, see the command arg arg.

+
opt_def name ?arg?
+

Text structure. List element. Option list. Automatically closes the +previous list element. Specifies name and arguments of the +option described by the list element. It is expected that the +name is marked up using option.

+
option text
+

Text markup. The argument is marked up as option. The text may +have other markup already applied to it. Main use is the highlighting +of options, also known as command-switches, in either free-form text, +or the arguments of the call and usage commands.

+
package text
+

Text markup. The argument is marked up as the name of a +package. The text may have other markup already applied to +it. Main use is the highlighting of package names in free-form text.

+
para
+

Text structure. This command breaks free-form text into +paragraphs. Each command closes the paragraph coming before it and +starts a new paragraph for the text coming after it. Higher-level +forms of structure are sections and subsections.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form text. +Required to avoid interpretation of a right bracket as the end of a markup +command.

+
require package ?version?
+

Document information. Header. This command registers its argument +package as the name of a package or application required by the +described package or application. A minimum version can be provided as +well. This argument can be marked up. The usual markup is opt.

+
section name
+

Text structure. This command starts a new named document section. The +argument has to be plain text. Implicitly closes the last paragraph +coming before it and also implicitly opens the first paragraph of the +new section.

+
sectref id ?text?
+

Text markup. Formats a reference to the section identified by id. +If no text is specified the title of the referenced section is +used in the output, otherwise text is used.

+
sectref-external text
+

Text markup. Like sectref, except that the section is assumed to +be in a different document and therefore doesn't need to be identified, +nor are any checks for existence made. Only the text to format is needed.

+
see_also args
+

Document information. Anywhere. The command defines direct cross-references +to other documents. Each argument is a plain text label identifying the +referenced document. If this command is used multiple times all the arguments +accumulate.

+
strong text
+

Deprecated. Text markup. See emph for the canonical +command to emphasize text.

+
subsection name
+

Text structure. This command starts a new named subsection of a +section. The argument has to be plain text. Implicitly closes the last +paragraph coming before it and also implicitly opens the first +paragraph of the new subsection.

+
syscmd text
+

Text markup. The argument text is marked up as the name of an external +command. The text may have other markup already applied to it. Main +use is the highlighting of external commands in free-form text.

+
term text
+

Text markup. The argument is marked up as unspecific terminology. The +text may have other markup already applied to it. Main use is the +highlighting of important terms and concepts in free-form text.

+
titledesc desc
+

Document information. Header. Optional. Registers the plain text +argument as the title of the manpage. Defaults to the value registered +by moddesc.

+
tkoption_def name dbname dbclass
+

Text structure. List element. Widget option list. Automatically closes +the previous list element. Specifies the name of the option as +used in scripts, the name used by the option database (dbname), +and its class (dbclass), i.e. its type. It is expected that the +name is marked up using option.

+
type text
+

Text markup. The argument is marked up as the name of a +data type. The text may have other markup already applied to +it. Main use is the highlighting of data types in free-form text.

+
uri text ?text?
+

Text markup. The argument is marked up as an uri (i.e. a +uniform resource identifier. The text may have other markup +already applied to it. Main use is the highlighting of uris in +free-form text. The second argument, should it be present, will be +interpreted the human-readable description of the uri. In other words, +as its label. Without an explicit label the uri will be its own label.

+
usage args
+

Text markup. See call for the full description, this command is +syntactically identical, as it is in its expectations for the markup +of its arguments. +In contrast to call it is however not allowed to generate output +where this command occurs in the text. The command is silent. +The formatted text may only appear in a different section of the +output, for example a table of contents, or synopsis, depending on the +output format.

+
var text
+

Text markup. The argument is marked up as the name of a +variable. The text may have other markup already applied to +it. Main use is the highlighting of variables in free-form text.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
widget text
+

Text markup. The argument is marked up as the name of a +widget. The text may have other markup already applied to +it. Main use is the highlighting of widget names in free-form text.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html @@ -0,0 +1,182 @@ + + +doctools_lang_faq - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_faq - doctools language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the doctools markup language and +companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document in the category doctools of the +Tcllib SF Trackers.

+
+
+

EXAMPLES

+

Where do I find doctools examples?

+

The most examples of doctools markup currently known can be found in +the Tcllib and Tklib package bundles where basically the documentation +of all packages is written in it. +In Tcllib you will also find the sources for the doctools +documentation themselves, which makes use of nearly all of the +available markup commands. +You need one of

+
    +

  1. A CVS snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +http://sourceforge.net/cvs/?group_id=12883

    2. +

  2. A Tcllib release archive. They are available at +http://sourceforge.net/project/showfiles.php?group_id=12883

    3. +
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report any such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +the package and/or the documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html @@ -0,0 +1,617 @@ + + +doctools_lang_intro - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_intro - doctools language introduction

+
+ +

Description

+

This document is an informal introduction to version 1 of the doctools +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the doctools language syntax specification +and the doctools language command reference.

+

Fundamentals

+

In the broadest terms possible the doctools markup language +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

+
+  ... [list_begin enumerated] ...
+
+
+  ... [call [cmd foo] \\
+          [arg bar]] ...
+
+
+  ... [term {complex concept}] ...
+
+
+  ... [opt "[arg key] [arg value]"] ...
+
+
+

Basic structure

+

The most simple document which can be written in doctools is

+
+    [manpage_begin NAME SECTION VERSION]
+    [description]
+    [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]
+    [manpage_end]
+
+

has the same meaning as the example before.

+

On the other hand, if whitespace is present it consists not +only of any sequence of characters containing the space character, +horizontal and vertical tabs, carriage return, and newline, but it may +contain comment markup as well, in the form of the comment +command.

+
+[comment { ... }]
+[manpage_begin NAME SECTION VERSION]
+[copyright {YEAR AUTHOR}]
+[titledesc TITLE]
+[moddesc   MODULE_TITLE][comment { ... }]
+[require   PACKAGE VERSION]
+[require   PACKAGE]
+[description]
+[manpage_end]
+[comment { ... }]
+
+
+

Advanced structure

+

In the simple examples of the last section we fudged a bit regarding +the markup actually allowed to be used before the manpage_begin +command opening the document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the document. I.e. it +is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[manpage_begin NAME SECTION VERSION]
+[description]
+[manpage_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. I.e. for example in the header as well.

+
+[manpage_begin NAME SECTION VERSION]
+[include FILE]
+[vset VAR VALUE]
+[description]
+[manpage_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before manpage_begin may contain only the +templating commands vset and include, a file included in +the header may contain only header commands, etc.

+
+

Text structure

+

The body of the document consists mainly of text, possibly split into +sections, subsections, and paragraphs, with parts marked up to +highlight various semantic categories of text, and additional +structure through the use of examples and (nested) lists.

+

This section explains the high-level structural commands, with +everything else deferred to the following sections.

+

The simplest way of structuring the body is through the introduction +of paragraphs. The command for doing so is para. Each occurrence +of this command closes the previous paragraph and automatically opens +the next. The first paragraph is automatically opened at the beginning +of the body, by description. In the same manner the last +paragraph automatically ends at manpage_end.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[para]
+ ...
+[para]
+ ...
+[manpage_end]
+
+

Empty paragraphs are ignored.

+

A structure coarser than paragraphs are sections, which allow the +writer to split a document into larger, and labeled, pieces. The +command for doing so is section. Each occurrence of this command +closes the previous section and automatically opens the next, +including its first paragraph. The first section is automatically +opened at the beginning of the body, by description (This +section is labeled "DESCRIPTION"). In the same manner the last section +automatically ends at manpage_end.

+

Empty sections are not ignored. We are free to (not) use +paragraphs within sections.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[section {Section A}]
+ ...
+[para]
+ ...
+[section {Section B}]
+ ...
+[manpage_end]
+
+

Between sections and paragraphs we have subsections, to split sections. +The command for doing so is subsection. Each occurrence of this +command closes the previous subsection and automatically opens the +next, including its first paragraph. A subsection is automatically +opened at the beginning of the body, by description, and at the +beginning of each section. In the same manner the last subsection +automatically ends at manpage_end.

+

Empty subsections are not ignored. We are free to (not) use +paragraphs within subsections.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[section {Section A}]
+ ...
+[subsection {Sub 1}]
+ ...
+[para]
+ ...
+[subsection {Sub 2}]
+ ...
+[section {Section B}]
+ ...
+[manpage_end]
+
+
+

Text markup

+

Having handled the overall structure a writer can impose on the +document we now take a closer at the text in a paragraph.

+

While most often this is just the unadorned content of the document we +do have situations where we wish to highlight parts of it as some type +of thing or other, like command arguments, command names, concepts, +uris, etc.

+

For this we have a series of markup commands which take the text to +highlight as their single argument. It should be noted that while +their predominant use is the highlighting of parts of a paragraph they +can also be used to mark up the arguments of list item commands, and +of other markup commands.

+

The commands available to us are

+
+
arg
+

Its argument is a the name of a command argument.

+
class
+

Its argument is a class name.

+
cmd
+

Its argument is a command name (Tcl command).

+
const
+

Its argument is a constant.

+
emph
+

General, non-semantic emphasis.

+
file
+

Its argument is a filename / path.

+
fun
+

Its argument is a function name.

+
method
+

Its argument is a method name

+
namespace
+

Its argument is namespace name.

+
opt
+

Its argument is some optional syntax element.

+
option
+

Its argument is a command line switch / widget option.

+
package
+

Its argument is a package name.

+
sectref
+

Its argument is the title of a section or subsection, + i.e. a section reference.

+
syscmd
+

Its argument is a command name (external, system command).

+
term
+

Its argument is a concept, or general terminology.

+
type
+

Its argument is a type name.

+
uri
+

Its argument is a uniform resource identifier, i.e an + external reference. A second argument can be used + to specify an explicit label for the reference in + question.

+
usage
+

The arguments describe the syntax of a Tcl command.

+
var
+

Its argument is a variable.

+
widget
+

Its argument is a widget name.

+
+

The example demonstrating the use of text markup is an excerpt from +the doctools language command reference, with some +highlighting added. +It shows their use within a block of text, as the arguments of a list +item command (call), and our ability to nest them.

+
+  ...
+  [call [cmd arg_def] [arg type] [arg name]] [opt [arg mode]]]
+  Text structure. List element. Argument list. Automatically closes the
+  previous list element. Specifies the data-[arg type] of the described
+  argument of a command, its [arg name] and its i/o-[arg mode]. The
+  latter is optional.
+  ...
+
+
+

Escapes

+

Beyond the 20 commands for simple markup shown in the previous section +we have two more available which are technically simple markup. +However their function is not the marking up of phrases as specific +types of things, but the insertion of characters, namely [ +and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+

Cross-references

+

The last two commands we have to discuss are for the declaration of +cross-references between documents, explicit and implicit. They are +keywords and see_also. Both take an arbitrary number of +arguments, all of which have to be plain unmarked text. I.e. it is not +allowed to use markup on them. Both commands can be used multiple +times in a document. If that is done all arguments of all occurrences +of one of them are put together into a single set.

+
+
keywords
+

The arguments of this command are interpreted as keywords describing +the document. A processor can use this information to create an index +indirectly linking the containing document to all documents with the +same keywords.

+
see_also
+

The arguments of this command are interpreted as references to other +documents. A processor can format them as direct links to these +documents.

+
+

All the cross-reference commands can occur anywhere in the document +between manpage_begin and manpage_end. As such the writer +can choose whether she wants to have them at the beginning of the +body, or at its end, maybe near the place a keyword is actually +defined by the main content, or considers them as meta data which +should be in the header, etc.

+

Our example shows the sources for the cross-references of this +document, with some highlighting added. Incidentally they are found +at the end of the body.

+
+  ...
+  [see_also doctools_intro]
+  [see_also doctools_lang_syntax]
+  [see_also doctools_lang_cmdref]
+  [keywords markup {semantic markup}]
+  [keywords {doctools markup} {doctools language}]
+  [keywords {doctools syntax} {doctools commands}]
+  [manpage_end]
+
+
+

Examples

+

Where ever we can write plain text we can write examples too. For +simple examples we have the command example which takes a single +argument, the text of the argument. The example text must not contain +markup. If we wish to have markup within an example we have to use the +2-command combination example_begin / example_end instead.

+

The first opens an example block, the other closes it, and in between +we can write plain text and use all the regular text markup commands. +Note that text structure commands are not allowed. This also means +that it is not possible to embed examples and lists within an example. +On the other hand, we can use templating commands within +example blocks to read their contents from a file (Remember section +Advanced structure).

+

The source for the very first example in this document (see section +Fundamentals), with some highlighting added, is

+
+  [example {
+    ... [list_begin enumerated] ...
+  }]
+
+

Using example_begin / example_end this would look like

+
+  [example_begin]
+    ... [list_begin enumerated] ...
+  [example_end]
+
+
+

Lists

+

Where ever we can write plain text we can write lists too. The main +commands are list_begin to start a list, and list_end to +close one. The opening command takes an argument specifying the type +of list started it, and this in turn determines which of the eight +existing list item commands are allowed within the list to start list +items.

+

After the opening command only whitespace is allowed, until the first +list item command opens the first item of the list. Each item is a +regular series of paragraphs and is closed by either the next list +item command, or the end of the list. If closed by a list item command +this command automatically opens the next list item. A consequence of +a list item being a series of paragraphs is that all regular text +markup can be used within a list item, including examples and other +lists.

+

The list types recognized by list_begin and their associated +list item commands are:

+
+
arguments
+

(arg_def) This opens an argument (declaration) list. It +is a specialized form of a term definition list where the term is an +argument name, with its type and i/o-mode.

+
commands
+

(cmd_def) This opens a command (declaration) list. It +is a specialized form of a term definition list where the term is a +command name.

+
definitions
+

(def and call) This opens a general +term definition list. The terms defined by the list items are +specified through the argument(s) of the list item commands, either +general terms, possibly with markup (def), or Tcl commands with +their syntax (call).

+
enumerated
+

(enum) This opens a general enumerated list.

+
itemized
+

(item) +This opens a general itemized list.

+
options
+

(opt_def) This opens an option (declaration) list. It +is a specialized form of a term definition list where the term is an +option name, possibly with the option's arguments.

+
tkoptions
+

(tkoption_def) This opens a +widget option (declaration) list. It is a specialized form of +a term definition list where the term is the name of a configuration +option for a widget, with its name and class in the option database.

+
+

Our example is the source of the definition list in the previous +paragraph, with most of the content in the middle removed.

+
+  ...
+  [list_begin definitions]
+  [def [const arg]]
+  ([cmd arg_def]) This opens an argument (declaration) list. It is a
+  specialized form of a definition list where the term is an argument
+  name, with its type and i/o-mode.
+  [def [const itemized]]
+  ([cmd item])
+  This opens a general itemized list.
+  ...
+  [def [const tkoption]]
+  ([cmd tkoption_def]) This opens a widget option (declaration) list. It
+  is a specialized form of a definition list where the term is the name
+  of a configuration option for a widget, with its name and class in the
+  option database.
+  [list_end]
+  ...
+
+

Note that a list cannot begin in one (sub)section and end in +another. Differently said, (sub)section breaks are not allowed within +lists and list items. An example of this illegal construct is

+
+  ...
+  [list_begin itemized]
+  [item]
+  ...
+  [section {ILLEGAL WITHIN THE LIST}]
+  ...
+  [list_end]
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal doctools language syntax +specification as well. From here on out the +doctools language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with one of the applications for +the processing and conversion of doctools documents, i.e. either +Tcllib's easy and simple dtplite, or Tclapps' +ultra-configurable dtp.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html @@ -0,0 +1,229 @@ + + +doctools_lang_syntax - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_syntax - doctools language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +doctools markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +doctools language command reference. +A beginner should read the much more informally written +doctools language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the doctools markup language +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +doctools language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of doctools +documents. The lexical level of the language was covered in the +previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +

  3. The construct LIST_BEGIN<X> stands for the markup command +list_begin with X as its type argument.

    4. +
+

The syntax:

+
+manpage = defs
+          MANPAGE_BEGIN
+          header
+          DESCRIPTION
+          body
+          MANPAGE_END
+          { <WHITE> }
+defs    = { INCLUDE | VSET | <WHITE> }
+header  = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
+xref    = KEYWORDS | SEE_ALSO | CATEGORY
+body    = paras { SECTION    sbody  }
+sbody   = paras { SUBSECTION ssbody }
+ssbody  = paras
+paras   = tblock { (PARA | NL) tblock }
+tblock  = { <TEXT> | defs | markup | xref | an_example | a_list }
+markup  = ARG     | CLASS | CMD     | CONST     | EMPH   | FILE
+        | FUN     | LB    | METHOD  | NAMESPACE | OPT    | OPTION
+        | PACKAGE | RB    | SECTREF | STRONG    | SYSCMD | TERM
+        | TYPE    | URI   | USAGE   | VAR       | WIDGET
+example = EXAMPLE
+        | EXAMPLE_BEGIN extext EXAMPLE_END
+extext  = { <TEXT> | defs | markup }
+a_list  = LIST_BEGIN<arguments>   argd_list   LIST_END
+        | LIST_BEGIN<commands>    cmdd_list   LIST_END
+        | LIST_BEGIN<definitions> def_list    LIST_END
+        | LIST_BEGIN<enumerated>  enum_list   LIST_END
+        | LIST_BEGIN<itemized>    item_list   LIST_END
+        | LIST_BEGIN<options>     optd_list   LIST_END
+        | LIST_BEGIN<tkoptions>   tkoptd_list LIST_END
+argd_list   = [ <WHITE> ] { ARG_DEF      paras }
+cmdd_list   = [ <WHITE> ] { CMD_DEF      paras }
+def_list    = [ <WHITE> ] { (DEF|CALL)   paras }
+enum_list   = [ <WHITE> ] { ENUM         paras }
+item_list   = [ <WHITE> ] { ITEM         paras }
+optd_list   = [ <WHITE> ] { OPT_DEF      paras }
+tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html @@ -0,0 +1,489 @@ + + +doctools_plugin_apiref - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools_plugin_apiref(n) 1.1 tcllib "Documentation tools"

+

Name

+

doctools_plugin_apiref - doctools plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write a doctools formatting engine for some output +format X.

+

It specifies the interaction between the doctools package +and its plugins, i.e. the interface any doctools formatting engine has +to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +doctools language introduction and proceed from there to the +formal specifications, i.e. the doctools language syntax and +the doctools language command reference.

+
+

OVERVIEW

+

The API for a doctools formatting engine consists of two major +sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as a doctools formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. a doctools formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_copyright
+

Query command. It returns a string containing the copyright +information the doctools processor was configured with. The relevant +option is -copyright).

+
dt_file
+

Query command. It returns the full path of the file containing the +input currently processed by the engine. This may be an included file.

+
dt_mainfile
+

Query command. It returns the full path of the toplevel file containing +the input currently processed by the engine.

+
dt_fileid
+

Query command. It returns the name of the file containing the input +currently processed by the engine, without path, nor extension.

+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools.

+
dt_format
+

Query command. It returns the name of the format associated with the +doctools formatting engine.

+
dt_imgdata key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its data is returned as the result of the +command. Otherwise an empty string is returned.

+
dt_imgdst key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its destination path in the output is returned +as the result of the command. Otherwise an empty string is returned.

+
dt_imgsrc key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its origin path is returned as the result of +the command. Otherwise an empty string is returned.

+
dt_lnesting
+

Query command. It returns the number of lists currently open.

+
dt_module
+

Query command. It returns the name of the module the input currently +processed belongs to.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the doctools +formatting engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_user
+

Query command. It returns the name of the current user as known to the +tcl interpreter the frontend controlling the formatting engine resides +in.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    fmt_numpasses -> n
+    fmt_listvariables -> vars
+    fmt_varset var1 value1
+    fmt_varset var2 value2
+    ...
+    fmt_varset varK valueK
+    fmt_initialize
+    fmt_setup 1
+    ...
+    fmt_setup 2
+    ...
+    ...
+    fmt_setup n
+    ...
+    fmt_postprocess
+    fmt_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at fmt_varset.

+

In each of the passes, i.e. after the calls of fmt_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctools markup language, +as specified in the doctools language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first fmt_varset to +fmt_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with fmt_setup and going until either the next +fmt_setup or fmt_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
fmt_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
fmt_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after fmt_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
fmt_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
fmt_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
fmt_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
fmt_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
fmt_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by fmt_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctools markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the 49 markup commands specified in the +doctools language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +doctools language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctools +markup language, as specified in the doctools language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/mpexpand.html Index: embedded/www/tcllib/files/modules/doctools/mpexpand.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools/mpexpand.html @@ -0,0 +1,190 @@ + + +mpexpand - Documentation toolbox + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

mpexpand(n) 1.0 tcllib "Documentation toolbox"

+

Name

+

mpexpand - Markup processor

+
+ + +

Description

+

This manpage describes a processor / converter for manpages in the +doctools format as specified in doctools_fmt. The processor +is based upon the package doctools.

+
+
mpexpand ?-module module? format infile|- outfile|-
+

The processor takes three arguments, namely the code describing which +formatting to generate as the output, the file to read the markup +from, and the file to write the generated output into. If the +infile is "-" the processor will read from +stdin. If outfile is "-" the processor will +write to stdout.

+

If the option -module is present its value overrides the internal +definition of the module name.

+

The currently known output formats are

+
+
nroff
+

The processor generates *roff output, the standard format for unix +manpages.

+
html
+

The processor generates HTML output, for usage in and display by web +browsers.

+
tmml
+

The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML.

+
latex
+

The processor generates LaTeX output.

+
wiki
+

The processor generates Wiki markup as understood by wikit.

+
list
+

The processor extracts the information provided by manpage_begin.

+
null
+

The processor does not generate any output.

+
+
mpexpand.all ?-verbose? ?module?
+

This command uses mpexpand to generate all possible output +formats for all manpages in the current directory. The manpages are +recognized through the extension ".man". If -verbose is +specified the command will list its actions before executing them.

+

The module information is passed to mpexpand.

+
+
+

NOTES

+

Possible future formats are plain text, pdf and postscript.

+
+

See Also

+

expander(n), format(n), formatter(n)

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html Index: embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html @@ -0,0 +1,167 @@ + + +doctools::html::cssdefaults - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::html::cssdefaults(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::html::cssdefaults - Default CSS style for HTML export plugins

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::html::cssdefaults ?0.1?
    • +
+ +
+
+

Description

+

This package provides a single command providing access to the text of +the default CSS style to use for HTML markup generated by the various +HTML export plugins.

+

This is an internal package of doctools, for use by export plugins, +i.e. the packages converting doctools related documented into other +formats, most notably HTML.

+
+

API

+
+
::doctools::html::cssdefaults::contents
+

This command returns the text of the default CSS style to use for HTML +markup generated by the various HTML export plugins.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html Index: embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html @@ -0,0 +1,167 @@ + + +doctools::nroff::man_macros - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::nroff::man_macros(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::nroff::man_macros - Default CSS style for NROFF export plugins

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::nroff::man_macros ?0.1?
    • +
+ +
+
+

Description

+

This package provides a single command providing access to the +definition of the nroff man macro set to use for NROFF markup +generated by the various NROFF export plugins.

+

This is an internal package of doctools, for use by export plugins, +i.e. the packages converting doctools related documented into other +formats, most notably nroff.

+
+

API

+
+
::doctools::nroff::man_macros::contents
+

This command returns the text of the default CSS style to use for NROFF +generated by the various NROFF export plugins.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html Index: embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html @@ -0,0 +1,269 @@ + + +doctools::tcl::parse - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::tcl::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::tcl::parse - Processing text in 'subst -novariables' format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
  • package require struct::set
    • +
  • package require treeql
    • +
+ +
+
+

Description

+

This package provides commands for parsing text with embedded Tcl +commands as accepted by the Tcl builtin command +subst -novariables. The result of the parsing is an abstract +syntax tree.

+

This is an internal package of doctools, for use by the higher level +parsers processing the docidx, doctoc, and doctools +markup languages.

+
+

API

+
+
::doctools::tcl::parse text tree text ?root?
+

The command takes the text and parses it under the assumption +that it contains a string acceptable to the Tcl builtin command +subst -novariables. Errors are thrown otherwise during the +parsing. The format used for these errors in described in section +Error format.

+

The command returns the empty string as it result. The actual result +of the parsing is entered into the tree structure tree, under +the node root. +If root is not specified the root of tree is used. The +tree has to exist and be the command of a tree object which +supports the same methods as trees created by the package +struct::tree.

+

In case of errors tree will be left in an undefined state.

+
::doctools::tcl::parse file tree path ?root?
+

The same as text, except that the text to parse is read from +the file specified by path.

+
+
+

Error format

+

When the parser encounters a problem in the input +it will throw an error using the format described +here.

+
    +

  1. The message will contain the reason for the problem (unexpected +character or end of input in input), the character in question, if +any, and the line and column the problem was found at, in a human +readable form. This part is not documented further as its format may +change as we see fit. It is intended for human consumption, not +machine.

    2. +

  2. The error code however will contain a machine-readable representation +of the problem, in the form of a 5-element list containing, in the +order listed below

    +
      +

    1. the constant string doctools::tcl::parse

      2. +

    2. the cause of the problem, one of

      +
      +
      char
      +

      Unexpected character in input

      +
      eof
      +

      Unexpected end of the input

      +
      +
      3. +

    3. The location of the problem as offset from the beginning of the input, +counted in characters. Note: Line markers count as one character.

      4. +

    4. The line the problem was found on (counted from 1 (one)),

      5. +

    5. The column the problem was found at (counted from 0 (zero))

      6. +
    +
    3. +
+
+

Tree Structure

+

After successfully parsing a string the generated tree will have the +following structure:

+
    +

  1. In the following items the word 'root' refers to the node which was +specified as the root of the tree when invoking either text +or file. This may be the actual root of the tree.

    2. +

  2. All the following items further ignore the possibility of pre-existing +attributes in the pre-existing nodes. If attributes exists with the +same names as the attributes used by the parser the pre-existing +values are written over. Attributes with names not clashing with the +parser's attributes are not touched.

    3. +

  3. The root node has no attributes.

    4. +

  4. All other nodes have the attributes

    +
    +
    type
    +

    The value is a string from the set { Command , Text , Word }

    +
    range
    +

    The value is either empty or a 2-element list containing integer +numbers. The numbers are the offsets of the first and last character +in the input text, of the token described by the node,.

    +
    line
    +

    The value is an integer, it describes the line in the input the token +described by the node ends on. Lines are counted from 1 (one).

    +
    col
    +

    The value is an integer, it describes the column in the line in the +input the token described by the node ends on. Columns are counted +from 0 (zero).

    +
    +
    5. +

  5. The children of the root, if any, are of type Command and Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node.

    6. +

  6. The children of a Command node, if any, are of type Command, and Text, +and Word, they describe the arguments of the command.

    7. +

  7. The children of a Word node, if any, are of type Command, Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node.

    8. +

  8. A Word node without children represents the empty string.

    9. +

  9. All Text nodes are leaves of the tree.

    10. +

  10. All leaves of the tree are either Text or Command nodes. +Word nodes cannot be leaves.

    11. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html Index: embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html @@ -0,0 +1,183 @@ + + +doctools::msgcat - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat - Message catalog management for the various document parsers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat ?0.1?
    • +
+ +
+
+

Description

+

The package doctools::msgcat is a support module handling +the selection of message catalogs for the various document processing +packages in the doctools system version 2. As such it is an internal +package a regular user (developer) should not be in direct contact +with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the various +parser packages, and is shared by them. Underneath it, but not +explicit dependencies, are the packages providing the message catalogs +for the various languages.

+
+

API

+
+
::doctools::msgcat::init prefix
+

The command locates and loads the message catalogs for all the +languages returned by msgcat::mcpreferences, provided that they +could be found. It returns an integer number describing how many +packages were found and loaded.

+

The names of the packages the command will look for have the form +"doctools::msgcat::prefix::langcode", with prefix +the argument to the command, and the langcode supplied by the +result of msgcat::mcpreferences.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/container.html Index: embedded/www/tcllib/files/modules/doctools2idx/container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/container.html @@ -0,0 +1,445 @@ + + +doctools::idx - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx(n) 2 tcllib "Documentation tools"

+

Name

+

doctools::idx - Holding keyword indices

+
+ + +

Description

+

This package provides a class to contain and programmatically +manipulate keyword indices

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Exporting keyword indices, and

    2. +

  2. Importing keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is used to encode +keyword indices as values see the section +Keyword index serialization format. +This is the only format directly known to this class. Conversions from +and to any other format are handled by export and import manager +objects. These may be attached to a container, but do not have to be, +it is merely a convenience.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx objectName
+

This command creates a new container object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName key add name
+

This method adds the keyword name to the index. If the keyword +is already known nothing is done. The result of the method is the +empty string.

+
objectName key remove name
+

This method removes the keyword name from the index. If the +keyword is already gone nothing is done. Any references for whom this +keyword was the last association are removed as well. The result of +the method is the empty string.

+
objectName key references name
+

This method returns a list containing the names of all references +associated with the keyword name. An error is thrown in the +keyword is not known to the index. The order of the references in the +list is undefined.

+
objectName keys
+

This method returns a list containing the names of all keywords known +to the index. The order of the keywords in the list is undefined.

+
objectName reference add type key name label
+

This method adds the reference name to the index and associates +it with the keyword key. +The other two arguments hold the type and label of the +reference, respectively. +The type has to match the stored information, should the reference +exist already, i.e. this information is immutable after the reference +is known. The only way to change it is delete and recreate the +reference. +The label on the other hand is automatically updated to the value of +the argument, overwriting any previously stored information. +Should the reference exists already it is simply associated with the +key. If that is true already as well nothing is done, but the +label updated to the new value. The result of the method is the +empty string.

+

The type argument has be to one of manpage or url.

+
objectName reference remove name
+

The reference name is removed from the index. All associations +with keywords are released and the relevant reference labels removed. +The result of the method is the empty string.

+
objectName reference label name
+

This method returns the label associated with the reference +name. An error is thrown if the reference is not known.

+
objectName reference keys name
+

This method returns a list containing the names of all keywords +associated with the reference name. An error is thrown in the +reference is not known to the index. The order of the keywords in the +list is undefined.

+
objectName reference type name
+

This method returns the type of the reference name. An error is +thrown in the reference is not known to the index.

+
objectName references
+

This method returns a list containing the names of all references +known to the index. The order of the references in the list is +undefined.

+
objectName title
+

Returns the currently defined title of the keyword index.

+
objectName title text
+

Sets the title of the keyword index to text, and returns it as +the result of the command.

+
objectName label
+

Returns the currently defined label of the keyword index.

+
objectName label text
+

Sets the label of the keyword index to text, and returns it as +the result of the command.

+
objectName importer
+

Returns the import manager object currently attached to the container, +if any.

+
objectName importer object
+

Attaches the object as import manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the keyword index contained in +the text, assuming the given format.

+
objectName exporter
+

Returns the export manager object currently attached to the container, +if any.

+
objectName exporter object
+

Attaches the object as export manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding keyword index stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the keyword index from which to generate the text.

+
objectName deserialize = data ?format?
+

This method replaces the contents of the index object with the index +contained in the data. If no format was specified it is +assumed to be the regular serialization of a keyword index.

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case an error will be thrown if the container has no import +manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the keyword index in the data to its +contents instead of replacing it. +The method will throw an error if merging is not possible, i.e. would +produce an invalid index. The existing content is left unchanged in +that case.

+

The result of the method is the empty string.

+
objectName serialize ?format?
+

This method returns the keyword index contained in the object. If no +format is not specified the returned result is the canonical +serialization of its contents.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. +In that case an error will be thrown if the container has no export +manager attached to it.

+
+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export.html Index: embedded/www/tcllib/files/modules/doctools2idx/export.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export.html @@ -0,0 +1,459 @@ + + +doctools::idx::export - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export - Exporting keyword indices

+
+ +

Synopsis

+
+
    +
  • package require doctools::idx::export ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::config
    • +
  • package require doctools::idx::structure
    • +
  • package require snit
    • +
  • package require pluginmgr
    • +
+ +
+
+

Description

+

This package provides a class to manage the plugins for the export of +keyword indices to other formats, i.e. their conversion to, for +example docidx, HTML, etc.

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Importing keyword indices, and

    2. +

  2. Holding keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is the major input to +the manager objects provided by this package see the section +Keyword index serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_IDX_EXPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_IDX_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/idx/export/plugin"

    5. +

  5. the path "~/.doctools/idx/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/idx/export/plugins"

    8. +

  8. the path "~/.doctools/idx/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with six predefined export plugins, +namely

+
+
docidx
+

See docidx export plugin for details.

+
html
+

See html export plugin for details.

+
json
+

See json export plugin for details.

+
nroff
+

See nroff export plugin for details.

+
text
+

See text export plugin for details.

+
wiki
+

See wiki export plugin for details.

+
+

Readers wishing to write their own export plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Export plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a keyword index +stored in serial and converts it to the specified format, +using the export plugin for the format. An error is thrown if no +plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to docidx.

+

The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

+

The plugin has to conform to the interface specified in section +Export plugin API v2 reference.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +keyword index. It invokes that method, feeds the result into +export serial and returns the resulting string as its own +result.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
+
+
+

Export plugin API v2 reference

+

Plugins are what this package uses to manage the support for any +output format beyond the +Keyword index serialization format. Here we specify the +API the objects created by this package use to interact with their +plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::idx::export::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various export methods of export manager + objects to get a string encoding a keyword index in that + format.

    3. +

  3. The plugin can expect that the package + doctools::idx::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. A plugin has to provide one command, with the signature shown + below.

    +
    +
    export serial configuration
    +

    Whenever an export manager of doctools::idx has to generate +output for an index it will invoke this command.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +index for which to generate the output. +The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    file
    +

    This variable, if defined by the user of the index object + is expected to contain the name of the input file for which + the plugin is generating its output for.

    +
    map
    +

    This variable, if defined by the user of the index object is + expected to contain a dictionary mapping from symbolic file + names used in the references of type manpage to + actual paths (or urls). A plugin has to be able to handle + the possibility that a symbolic name is without entry in + this mapping.

    +
    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of the invokations of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html @@ -0,0 +1,301 @@ + + +doctools::idx::export::docidx - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::docidx(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::docidx - docidx export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::docidx ?0.1?
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of docidx markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates docidx markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Configuration

+

The docidx export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean newlines
+

If this flag is set the plugin will break the generated docidx code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set. This effect is independent of the +value for aligned however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and aligned, and no indenting is +done.

+
boolean aligned
+

If this flag is set the generator ensures that the arguments for the +manpage and url commands in a keyword section are aligned +vertically for a nice table effect. To make this work this also +implies that newlines is set. This effect is independent of the +value for indented however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and indented, and no alignment is +done.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_html.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_html.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_html.html @@ -0,0 +1,363 @@ + + +doctools::idx::export::html - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::html(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::html - HTML export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::html ?0.2?
    • +
  • package require doctools::text
    • +
  • package require doctools::html
    • +
  • package require doctools::html::cssdefaults
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of HTML markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates HTML markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
boolean newlines
+

If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
string meta
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output in +the <head> section of the document, just after the <title> tag.

+
string header
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output +just after the <h1> title tag in the body of the document, in the +class.header <div>'ision.

+
string footer
+

This variable is meant to hold a fragment of HTML (default: +empty). The fragment it contains will be inserted into the generated +output just before the </body> tag, in the class.footer <div>'ision.

+
dictionary kwid
+

The value of this variable (default: empty) maps keywords to the +identifiers to use as their anchor names. Each keyword FOO not +found in the dictionary uses KW-FOO as anchor, +i.e. itself prefixed with the string KW-.

+
string sepline
+

The value of this variable is the string to use for the separator +comments inserted into the output when the outpout is broken across +lines and/or indented. The default string consists of 60 dashes.

+
integer kwidth
+

This variable holds the size of the keyword column in the main table +generated by the plugin, in percent of the total width of the +table. This is an integer number in the range of 1 to 99. Choosing a +value outside of that range causes the generator to switch back to the +defauly setting, 35 percent.

+
string dot
+

This variable contains a HTML fragment inserted between the entries of +the navigation bar, and the references associated with each keyword. +The default is the HTML entity &#183; i.e. the bullet character, also +known as the "Greek middle dot", i.e. the unicode character 00B7.

+
string class.main
+

This variable contains the class name for the main <div>'ivision of +the generated document. The default is doctools.

+
string class.header
+

This variable contains the class name for the header <div>'ision of +the generated document. The default is idx-header. This +division contains the document title, the user specified header, +if any, a visible separator line, and the navigation bar for quick +access to each keyword section.

+
string class.title
+

This variable contains the class name for the <h1> tag enclosing the +document title. The default is idx-title.

+
string class.navsep
+

This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +idx-navsep.

+
string class.navbar
+

This variable contains the class name for the navigation <div>'ision +enclosing the navigation bar of the generated document. The default is +idx-kwnav.

+
string class.contents
+

This variable contains the class name for the <table> holding the +keywords and their references in the generated document. The default +is idx-contents.

+
string class.leader
+

This variable contains the class name for the anchor names the plugin +inserts into the keyword table when switching from one section to the +next (Each section holds all keywords with a particular first +character). The default is idx-leader.

+
string class.row0
+

This variable contains the class name used to label the even rows +(<tr>) of the keyword table. The default is idx-even.

+
string class.row1
+

This variable contains the class name used to label the odd rows +(<tr>) of the keyword table. The default is idx-odd.

+
string class.keyword
+

This variable contains the class name used to label the keyword +cells/column (<td>) in the keyword table of the document. The default +is idx-keyword.

+
string class.refs
+

This variable contains the class name used to label the reference +cells/column (<td>) in the keyword table of the document. The default +is idx-refs.

+
string class.footer
+

This variable contains the class name for the footer <div>'ision of +the generated document. The default is idx-footer. This +division contains a browser-visible separator line and the user +specified footer, if any.

+
+

Note that this plugin ignores the standard configuration +variable format, and its value.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_json.html @@ -0,0 +1,316 @@ + + +doctools::idx::export::json - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::json - JSON export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::json ?0.1?
    • +
  • package require textutil::adjust
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates JSON markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

JSON notation of keyword indices

+

The JSON format used for keyword indices is a direct translation of +the Keyword index serialization format, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::idx {
+	label {Keyword Index}
+	keywords {
+		changelog  {changelog.man cvs.man}
+		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
+		cvs        cvs.man
+	}
+	references {
+		apps/dtplite.man {manpage dtplite}
+		changelog.man    {manpage doctools::changelog}
+		cvs.man          {manpage doctools::cvs}
+		docidx.man       {manpage doctools::idx}
+		doctoc.man       {manpage doctools::toc}
+		doctools.man     {manpage doctools}
+		mpexpand.man     {manpage mpexpand}
+	}
+	title {}
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::idx" : {
+        "label"      : "Keyword Index",
+        "keywords"   : {
+            "changelog"  : ["changelog.man","cvs.man"],
+            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
+            "cvs"        : ["cvs.man"],
+        },
+        "references" : {
+            "apps\/dtplite.man" : ["manpage","dtplite"],
+            "changelog.man"     : ["manpage","doctools::changelog"],
+            "cvs.man"           : ["manpage","doctools::cvs"],
+            "docidx.man"        : ["manpage","doctools::idx"],
+            "doctoc.man"        : ["manpage","doctools::toc"],
+            "doctools.man"      : ["manpage","doctools"],
+            "mpexpand.man"      : ["manpage","mpexpand"]
+        },
+        "title"      : ""
+    }
+}
+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and map and +their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_nroff.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_nroff.html @@ -0,0 +1,270 @@ + + +doctools::idx::export::nroff - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::nroff(n) 0.3 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::nroff - nroff export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::nroff ?0.3?
    • +
  • package require doctools::text
    • +
  • package require doctools::nroff::man_macros
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of nroff markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates nroff markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean inline
+

If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output.

+

If this flag is not set, the plugin will place a reference to the +definitions of the man macro set into the output, but not the macro +definitions themselves.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_text.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_text.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_text.html @@ -0,0 +1,257 @@ + + +doctools::idx::export::text - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::text(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::text - plain text export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::text ?0.2?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of plain text markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates plain text markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file, and format, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_wiki.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/export_wiki.html @@ -0,0 +1,270 @@ + + +doctools::idx::export::wiki - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::export::wiki(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::wiki - wiki export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::wiki ?0.2?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of wiki markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates wiki markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Wiki markup

+

The basic syntax of the wiki markup generated by this plugin are +described at http://wiki.tcl.tk/14.

+

The plugin goes beyond the classic markup to generate proper headers +and either a table or indented list of the keywords and their +references.

+
+

Configuration

+

The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
enum style
+

This variable recognizes two values as legal, list (default), +and table. +Depending on the value the plugin generates either a list- or +table-based wiki page for the index.

+
+

Note that this plugin ignores the standard configuration +variables user, file and format, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/import.html Index: embedded/www/tcllib/files/modules/doctools2idx/import.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/import.html @@ -0,0 +1,518 @@ + + +doctools::idx::import - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::import(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import - Importing keyword indices

+
+ + +

Description

+

This package provides a class to manage the plugins for the import of +keyword indices from other formats, i.e. their conversion from, for +example docidx, json, etc.

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Exporting keyword indices, and

    2. +

  2. Holding keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is the major output of +the manager objects provided by this package see the section +Keyword index serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_IDX_IMPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_IDX_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/idx/import/plugin"

    5. +

  5. the path "~/.doctools/idx/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/idx/import/plugins"

    8. +

  8. the path "~/.doctools/idx/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with two predefined import plugins, +namely

+
+
docidx
+

See docidx import plugin for details.

+
json
+

See json import plugin for details.

+
+

Readers wishing to write their own import plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Import plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a keyword index using +the import plugin for the format. An error is thrown if no plugin +could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to docidx.

+

The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

+

The plugin has to conform to the interface specified in section +Import plugin API v2 reference.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +keyword index. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

Import plugin API v2 reference

+

Plugins are what this package uses to manage the support for any input +format beyond the Keyword index serialization format. Here +we specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::idx::import::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various import methods of import manager + objects to get a string encoding a keyword index in that + format.

    3. +

  3. The plugin can expect that the package + doctools::idx::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. The plugin can expect that a command named IncludeFile is + present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such. An example of +such a format would be docidx.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide one command, with the signature shown + below.

    +
    +
    import text configuration
    +

    Whenever an import manager of doctools::idx has to parse +input for an index it will invoke this command.

    +
    +
    string text
    +

    This argument will contain the text encoding the index per the format +the plugin is for.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of the invokations of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html @@ -0,0 +1,270 @@ + + +doctools::idx::import::docidx - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::import::docidx(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import::docidx - docidx import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::import::docidx ?0.1?
    • +
  • package require doctools::idx::parse
    • +
  • package require doctools::idx::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require struct::stack
    • +
  • package require struct::tree
    • +
  • package require treeql
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index import plugin for +the parsing of docidx markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as docidx +markup encoding a keyword index, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section Keyword index serialization format.

+
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/import_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/import_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/import_json.html @@ -0,0 +1,293 @@ + + +doctools::idx::import::json - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::import::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import::json - JSON import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::import::json ?0.1?
    • +
  • package require doctools::idx::structure
    • +
  • package require json
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index import plugin for +the parsing of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as JSON +markup encoding a keyword index, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section Keyword index serialization format.

+
+
+

JSON notation of keyword indices

+

The JSON format used for keyword indices is a direct translation of +the Keyword index serialization format, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::idx {
+	label {Keyword Index}
+	keywords {
+		changelog  {changelog.man cvs.man}
+		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
+		cvs        cvs.man
+	}
+	references {
+		apps/dtplite.man {manpage dtplite}
+		changelog.man    {manpage doctools::changelog}
+		cvs.man          {manpage doctools::cvs}
+		docidx.man       {manpage doctools::idx}
+		doctoc.man       {manpage doctools::toc}
+		doctools.man     {manpage doctools}
+		mpexpand.man     {manpage mpexpand}
+	}
+	title {}
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::idx" : {
+        "label"      : "Keyword Index",
+        "keywords"   : {
+            "changelog"  : ["changelog.man","cvs.man"],
+            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
+            "cvs"        : ["cvs.man"],
+        },
+        "references" : {
+            "apps\/dtplite.man" : ["manpage","dtplite"],
+            "changelog.man"     : ["manpage","doctools::changelog"],
+            "cvs.man"           : ["manpage","doctools::cvs"],
+            "docidx.man"        : ["manpage","doctools::idx"],
+            "doctoc.man"        : ["manpage","doctools::toc"],
+            "doctools.man"      : ["manpage","doctools"],
+            "mpexpand.man"      : ["manpage","mpexpand"]
+        },
+        "title"      : ""
+    }
+}
+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/introduction.html Index: embedded/www/tcllib/files/modules/doctools2idx/introduction.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/introduction.html @@ -0,0 +1,257 @@ + + +doctools2idx_introduction - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools2idx_introduction(n) 2.0 tcllib "Documentation tools"

+

Name

+

doctools2idx_introduction - DocTools - Keyword indices

+
+ +

Description

+

docidx (short for documentation indices) stands for a +set of related, yet different, entities which are working together for +the easy creation and transformation of keyword indices for +documentation.

+

These are

+
    +

  1. A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands. +Beginners should start with the +docidx language introduction. +The formal specification is split over two documents, one dealing with +the docidx language syntax, the other a +docidx language command reference.

    2. +

  2. A set of packages for the programmatic manipulation of keyword indices +in memory, and their conversion between various formats, reading and +writing. The aforementioned markup language is one of the formats +which can be both read from and written to.

    3. +

  3. The system for the conversion of indices is based on a plugin +mechanism, for this we have two APIs describing the interface between +the packages above and the import/export plugins.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +docidx language introduction first. Having digested this +the formal docidx language syntax specification should +become understandable. A writer experienced with docidx may only +need the docidx language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them.

    2. +

  2. A processor of documentation written in the docidx +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose docidx to the +user. At the bottom level, common to both applications, however we +find the three packages providing the basic facilities to handle +keyword indices, i.e. import from textual formats, programmatic +manipulation in memory, and export to textual formats. These are

    +
    +
    doctools::idx
    +

    Programmatic manipulation of keyword indices in memory.

    +
    doctools::idx::import
    +

    Import of keyword indices from various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    doctools::idx::export
    +

    Export of keyword indices to various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    +

    See also section Package Overview for an overview of the +dependencies between these and other, supporting packages.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the import and export packages and their plugins. +These APIs are described in the documentation for the two relevant +packages, i.e.

    + +
    4. +
+
+

Related formats

+

The docidx format does not stand alone, it has two companion formats. +These are called doctoc and doctools, and they are +intended for the markup of tables of contents, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the DocTools - Tables Of Contents and +the DocTools - General, respectively.

+
+

Package Overview

+
+                                    ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
+                                   ~~                   |               ~~
+                doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
+                        |                               |                       |
+        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
+        |               |                         |     |    |                  |               |                       |               |
+doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
+                        |                         |     |    |                  |
+                doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
+                        docidx                    |     |    |                  docidx, json
+                        json                      |     |    |                  |           \\
+                        html                      |     |    |          doctools::idx::parse \\
+                        nroff                     |     |    |                  |             \\
+                        wiki                      |     |    |  +---------------+              json
+                        text                      |     |    |  |               |
+                                                doctools::idx::structure        |
+                                                                                |
+                                                                        +-------+---------------+
+                                                                        |                       |
+          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
+                |                                                                               |
+          doctools::text  doctools::nroff::man_macros                                           =
+                                                                                                |
+                                                                                        doctools::msgcat::idx::<*>
+                                                                                                c, en, de, fr
+                                                                                                (fr == en for now)
+        ~~      Interoperable objects, without actual package dependencies
+        --      Package dependency, higher requires lower package
+        =       Dynamic dependency through plugin system
+        <*>     Multiple packages following the given form of naming.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

doctools2doc_introduction, doctools2toc_introduction

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2idx/msgcat_c.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/msgcat_c.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::idx::c - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::idx::c(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::c - Message catalog for the docidx parser (C)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::c ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::c is a +support module providing the C language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2idx/msgcat_de.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/msgcat_de.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::idx::de - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::idx::de(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::de - Message catalog for the docidx parser (DE)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::de ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::de is a +support module providing the DE (german) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2idx/msgcat_en.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/msgcat_en.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::idx::en - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::idx::en(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::en - Message catalog for the docidx parser (EN)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::en ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::en is a +support module providing the EN (english) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2idx/msgcat_fr.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/msgcat_fr.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::idx::fr - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::idx::fr(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::fr - Message catalog for the docidx parser (FR)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::fr ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::fr is a +support module providing the FR (french) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/parse.html Index: embedded/www/tcllib/files/modules/doctools2idx/parse.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/parse.html @@ -0,0 +1,347 @@ + + +doctools::idx::parse - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::idx::parse - Parsing text in docidx format

+
+ +

Synopsis

+
+
    +
  • package require doctools::idx::parse ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
+ +
+
+

Description

+

This package provides commands to parse text written in the +docidx markup language and convert it into the canonical +serialization of the keyword index encoded in the text. +See the section Keyword index serialization format for +specification of their format.

+

This is an internal package of doctools, for use by the higher level +packages handling docidx documents.

+
+

API

+
+
::doctools::idx::parse text text
+

The command takes the string contained in text and parses it +under the assumption that it contains a document written using the +docidx markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section Parse errors.

+

When successful the command returns the canonical serialization of the +keyword index which was encoded in the text. +See the section Keyword index serialization format for +specification of that format.

+
::doctools::idx::parse file path
+

The same as text, except that the text to parse is read from +the file specified by path.

+
::doctools::idx::parse includes
+

This method returns the current list of search paths used when looking +for include files.

+
::doctools::idx::parse include add path
+

This method adds the path to the list of paths searched when +looking for an include file. The call is ignored if the path is +already in the list of paths. The method returns the empty string as +its result.

+
::doctools::idx::parse include remove path
+

This method removes the path from the list of paths searched +when looking for an include file. The call is ignored if the path is +not contained in the list of paths. The method returns the empty +string as its result.

+
::doctools::idx::parse include clear
+

This method clears the list of search paths for include files.

+
::doctools::idx::parse vars
+

This method returns a dictionary containing the current set of +predefined variables known to the vset markup command during +processing.

+
::doctools::idx::parse var set name value
+

This method adds the variable name to the set of predefined +variables known to the vset markup command during processing, +and gives it the specified value. The method returns the empty +string as its result.

+
::doctools::idx::parse var unset name
+

This method removes the variable name from the set of predefined +variables known to the vset markup command during +processing. The method returns the empty string as its result.

+
::doctools::idx::parse var clear ?pattern?
+

This method removes all variables matching the pattern from the +set of predefined variables known to the vset markup command +during processing. The method returns the empty string as its result.

+

The pattern matching is done with string match, and the +default pattern used when none is specified, is *.

+
+
+

Parse errors

+

The format of the parse error messages thrown when encountering +violations of the docidx markup syntax is human readable and +not intended for processing by machines. As such it is not documented.

+

However, the errorCode attached to the message is +machine-readable and has the following format:

+
    +

  1. The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more.

    2. +

  2. Each error element will be a list containing six strings describing an +error in detail. The strings will be

    +
      +

    1. The path of the file the error occured in. This may be empty.

      2. +

    2. The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero.

      3. +

    3. The line the first character after the error is on. +Lines are counted from one.

      4. +

    4. The column the first character after the error is at. +Columns are counted from zero.

      5. +

    5. The message code of the error. This value can be used as argument to +msgcat::mc to obtain a localized error message, assuming that +the application had a suitable call of doctools::msgcat::init to +initialize the necessary message catalogs (See package +doctools::msgcat).

      6. +

    6. A list of details for the error, like the markup command involved. In +the case of message code docidx/include/syntax this value is +the set of errors found in the included file, using the format +described here.

      7. +
    +
    3. +
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/structure.html Index: embedded/www/tcllib/files/modules/doctools2idx/structure.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2idx/structure.html @@ -0,0 +1,288 @@ + + +doctools::idx::structure - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::idx::structure(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::structure - Docidx serialization utilities

+
+ + +

Description

+

This package provides commands to work with the serializations of +keyword indices as managed by the doctools system v2, and specified in +section Keyword index serialization format.

+

This is an internal package of doctools, for use by the higher level +packages handling keyword indices and their conversion into and out of +various other formats, like documents written using docidx +markup.

+
+

API

+
+
::doctools::idx::structure verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +regular serialization of a keyword index and will throw an +error if that is not the case. The result of the command is the empty +string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
::doctools::idx::structure verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a keyword index and will throw an +error if that is not the case. The result of the command is the empty +string.

+

For the specification of canonical keyword index serializations see +the section Keyword index serialization format.

+
::doctools::idx::structure canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a keyword index and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained keyword index and return it as its result. If the +input is already canonical it will be returned unchanged.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
::doctools::idx::structure print serial
+

This command assumes that the argument serial contains a valid +regular serialization of a keyword index and returns a string +containing that index in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of regular keyword index serializations see the +section Keyword index serialization format.

+
::doctools::idx::structure merge seriala serialb
+

This command accepts the regular serializations of two keyword indices +and uses them to create their union. The result of the command is the +canonical serialization of this unified keyword index.

+

Title and label of the resulting index are taken from the index +contained in serialb. The set of keys, references and their +connections is the union of the set of keys and references of the two +inputs.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/container.html Index: embedded/www/tcllib/files/modules/doctools2toc/container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/container.html @@ -0,0 +1,510 @@ + + +doctools::toc - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc(n) 2 tcllib "Documentation tools"

+

Name

+

doctools::toc - Holding tables of contents

+
+ + +

Description

+

This package provides a class to contain and programmatically +manipulate tables of contents.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Exporting tables of contents, and

    2. +

  2. Importing tables of contents

    3. +
+

For information about the Concepts of tables of contents, and +their parts, see the same-named section. +For information about the data structure which is used to encode +tables of contents as values see the section +ToC serialization format. +This is the only format directly known to this class. Conversions from +and to any other format are handled by export and import manager +objects. These may be attached to a container, but do not have to be, +it is merely a convenience.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc objectName
+

This command creates a new container object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName + reference id label docid desc
+

This method adds a new reference element to the table of contents, +under the element specified via its handle id. This parent +element has to be a division element, or the root. An error is thrown +otherwise. +The new element will be externally identified by its label, +which has to be be unique within the parent element. An error is +thrown otherwise.

+

As a reference element it will refer to a document identified by the +symbolic docid. This reference must not be the empty string, an +error is thrown otherwise. +Beyond the label the element also has a longer descriptive string, +supplied via desc.

+

The result of the method is the handle (id) of the new element.

+
objectName + division id label ?docid?
+

This method adds a new division element to the table of contents, +under the element specified via its handle id. This parent +element has to be a division element, or the root. An error is thrown +otherwise. +The new element will be externally identified by its label, +which has to be be unique within the parent element. An error is +thrown otherwise.

+

As a division element it is can refer to a document, identified by the +symbolic docid, but may choose not to.

+

The result of the method is the handle (id) of the new element.

+
objectName remove id
+

This method removes the element identified by the handle id from +the table of contents. +If the element is a division all of its children, if any, are removed +as well. The root element/division of the table of contents cannot be +removed however, only its children.

+

The result of the method is the empty string.

+
objectName up id
+

This method returns the handle of the parent for the element +identified by its handle id, or the empty string if id +refered to the root element.

+
objectName next id
+

This method returns the handle of the right sibling for the element +identified by its handle id, or the handle of the parent if the +element has no right sibling, or the empty string if id refered +to the root element.

+
objectName prev id
+

This method returns the handle of the left sibling for the element +identified by its handle id, or the handle of the parent if the +element has no left sibling, or the empty string if id refered +to the root element.

+
objectName child id label ?...?
+

This method returns the handle of a child of the element identified by +its handle id. The child itself is identified by a series of +labels.

+
objectName element ?...?
+

This method returns the handle of the element identified by a series +of labels, starting from the root of the table of contents. The series +of labels is allowed to be empty, in which case the handle of the root +element is returned.

+
objectName children id
+

This method returns a list containing the handles of all children of +the element identified by the handle id, from first to last, in +that order.

+
objectName type id
+

This method returns the type of the element, either reference, +or division.

+
objectName full-label id
+

This method is the complement of the method element, +converting the handle id of an element into a list of labels +full identifying the element within the whole table of contents.

+
objectName elabel id ?newlabel?
+

This method queries and/or changes the label of the element identified +by the handle id. If the argument newlabel is present then +the label is changed to that value. Regardless of this, the result of +the method is the current value of the label.

+

If the label is changed the new label has to be unique within the +containing division, or an error is thrown.

+

Further, of the id refers to the root element of the table of +contents, then using this method is equivalent to using the method +label, i.e. it is accessing the global label for the whole +table.

+
objectName description id ?newdesc?
+

This method queries and/or changes the description of the element +identified by the handle id. If the argument newdesc is +present then the description is changed to that value. Regardless of +this, the result of the method is the current value of the description.

+

The element this method operates on has to be a reference element, or +an error will be thrown.

+
objectName document id ?newdocid?
+

This method queries and/or changes the document reference of the +element identified by the handle id. +If the argument newdocid is present then the description is +changed to that value. Regardless of this, the result of the method is +the current value of the document reference.

+

Setting the reference to the empty string means unsetting it, and is +allowed only for division elements. Conversely, if the result is the +empty string then the element has no document reference, and this can +happen only for division elements.

+
objectName title
+

Returns the currently defined title of the table of contents.

+
objectName title text
+

Sets the title of the table of contents to text, and returns it as +the result of the command.

+
objectName label
+

Returns the currently defined label of the table of contents.

+
objectName label text
+

Sets the label of the table of contents to text, and returns it as +the result of the command.

+
objectName importer
+

Returns the import manager object currently attached to the container, +if any.

+
objectName importer object
+

Attaches the object as import manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the table of contents contained in +the text, assuming the given format.

+
objectName exporter
+

Returns the export manager object currently attached to the container, +if any.

+
objectName exporter object
+

Attaches the object as export manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding table of contents stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the table of contents from which to generate the text.

+
objectName deserialize = data ?format?
+

This method replaces the contents of the table object with the table +contained in the data. If no format was specified it is +assumed to be the regular serialization of a table of contents.

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case an error will be thrown if the container has no import +manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the table of contents in the data to its +contents instead of replacing it. +The method will throw an error if merging is not possible, i.e. would +produce an invalid table. The existing content is left unchanged in +that case.

+

The result of the method is the empty string.

+
objectName serialize ?format?
+

This method returns the table of contents contained in the object. If no +format is not specified the returned result is the canonical +serialization of its contents.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. +In that case an error will be thrown if the container has no export +manager attached to it.

+
+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export.html Index: embedded/www/tcllib/files/modules/doctools2toc/export.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export.html @@ -0,0 +1,475 @@ + + +doctools::toc::export - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export - Exporting tables of contents

+
+ +

Synopsis

+
+
    +
  • package require doctools::toc::export ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::config
    • +
  • package require doctools::toc::structure
    • +
  • package require snit
    • +
  • package require pluginmgr
    • +
+ +
+
+

Description

+

This package provides a class to manage the plugins for the export of +tables of contents to other formats, i.e. their conversion to, for +example doctoc, HTML, etc.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Importing tables of contents, and

    2. +

  2. Holding tables of contents

    3. +
+

For information about the Concepts of tables of contents, +and their parts, see the same-named section. +For information about the data structure which is the major input to +the manager objects provided by this package see the section +ToC serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_TOC_EXPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_TOC_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/toc/export/plugin"

    5. +

  5. the path "~/.doctools/toc/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/toc/export/plugins"

    8. +

  8. the path "~/.doctools/toc/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with six predefined export plugins, +namely

+
+
doctoc
+

See doctoc export plugin for details.

+
html
+

See html export plugin for details.

+
json
+

See json export plugin for details.

+
nroff
+

See nroff export plugin for details.

+
text
+

See text export plugin for details.

+
wiki
+

See wiki export plugin for details.

+
+

Readers wishing to write their own export plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Export plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a table of contents +stored in serial and converts it to the specified format, +using the export plugin for the format. An error is thrown if no +plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to doctoc.

+

The specification of what a canonical serialization is can be +found in the section ToC serialization format.

+

The plugin has to conform to the interface specified in section +Export plugin API v2 reference.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +table of contents. It invokes that method, feeds the result into +export serial and returns the resulting string as its own +result.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
+
+
+

Export plugin API v2 reference

+

Plugins are what this package uses to manage the support for any +output format beyond the ToC serialization format. Here we +specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::toc::export::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various export methods of export manager + objects to get a string encoding a table of contents in that + format.

    3. +

  3. The plugin can expect that the package + doctools::toc::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. A plugin has to provide one command, with the signature shown + below.

    +
    +
    export serial configuration
    +

    Whenever an export manager of doctools::toc has to generate +output for a table of contents it will invoke this command.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +table of contents for which to generate the output. +The specification of what a canonical serialization is can be +found in the section ToC serialization format.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    file
    +

    This variable, if defined by the user of the table object + is expected to contain the name of the input file for which + the plugin is generating its output for.

    +
    map
    +

    This variable, if defined by the user of the table object is + expected to contain a dictionary mapping from symbolic + document ids used in the table entries to actual paths (or + urls). A plugin has to be able to handle the possibility + that a document id is without entry in this mapping.

    +
    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of the invokations of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html @@ -0,0 +1,324 @@ + + +doctools::toc::export::doctoc - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::doctoc(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::doctoc - doctoc export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::doctoc ?0.1?
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of doctoc markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates doctoc markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Configuration

+

The doctoc export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean newlines
+

If this flag is set the plugin will break the generated doctoc code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of tables of contents. To make this work +this also implies that newlines is set. This effect is +independent of the value for aligned however.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
boolean aligned
+

If this flag is set the generator ensures that the arguments for the +item commands in a division are aligned vertically for a nice +table effect. To make this work this also implies that newlines +is set. This effect is independent of the value for indented +however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and indented, and no alignment is +done.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_html.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_html.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_html.html @@ -0,0 +1,357 @@ + + +doctools::toc::export::html - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::html(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::html - HTML export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::html ?0.1?
    • +
  • package require doctools::text
    • +
  • package require doctools::html
    • +
  • package require doctools::html::cssdefaults
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of HTML markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates HTML markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
boolean newlines
+

If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
string meta
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output in +the <head> section of the document, just after the <title> tag.

+
string header
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output +just after the <h1> title tag in the body of the document, in the +class.header <div>'ision.

+
string footer
+

This variable is meant to hold a fragment of HTML (default: +empty). The fragment it contains will be inserted into the generated +output just before the </body> tag, in the class.footer <div>'ision.

+
dictionary rid
+

The value of this variable (default: empty) maps references to the +identifiers to use as their anchor names. Each reference FOO not +found in the dictionary uses REF-FOO as anchor, +i.e. itself prefixed with the string REF-.

+
string sepline
+

The value of this variable is the string to use for the separator +comments inserted into the output when the outpout is broken across +lines and/or indented. The default string consists of 60 dashes.

+
string class.main
+

This variable contains the class name for the main <div>'ivision of +the generated document. The default is doctools.

+
string class.header
+

This variable contains the class name for the header <div>'ision of +the generated document. The default is toc-header. This +division contains the document title, the user specified header, +if any, and a visible separator line.

+
string class.title
+

This variable contains the class name for the <h1> tag enclosing the +document title. The default is toc-title.

+
string class.navsep
+

This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +toc-navsep.

+
string class.contents
+

This variable contains the class name for the XXXXX holding the +keywords and their references in the generated document. The default +is toc-contents.

+
string class.ref
+

This variable contains the class name for the table elements which are +references to other documents. The default is toc-ref.

+
string class.div
+

This variable contains the class name for the table elements which are +divisions. The default is toc-div.

+
string class.footer
+

This variable contains the class name for the footer <div>'ision of +the generated document. The default is toc-footer. This +division contains a browser-visible separator line and the user +specified footer, if any.

+
+

Note that this plugin ignores the standard configuration +variable format, and its value.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_json.html @@ -0,0 +1,360 @@ + + +doctools::toc::export::json - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::json - JSON export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::json ?0.1?
    • +
  • package require textutil::adjust
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates JSON markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

JSON notation of tables of contents

+

The JSON format used for tables of contents is a direct translation of +the ToC serialization format, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::toc {
+    items {
+        {reference {
+	    desc {DocTools - Tables of Contents}
+	     id introduction.man
+	     label doctools::toc::introduction
+	}}
+	{division {
+	     id processing.man
+	     items {
+	         {reference {
+		     desc {doctoc serialization utilities}
+		     id structure.man
+		     label doctools::toc::structure
+		 }}
+		 {reference {
+		     desc {Parsing text in doctoc format}
+		     id parse.man
+		     label doctools::toc::parse
+		 }}
+	     }
+             label Processing
+        }}
+    }
+    label {Table of Contents} 
+    title TOC
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::toc" : {
+        "items" : [{
+            "reference" : {
+                "desc"  : "DocTools - Tables of Contents",
+                "id"    : "introduction.man",
+                "label" : "doctools::toc::introduction"
+            }
+        },{
+            "division" : {
+                "id"    : "processing.man",
+                "items" : [{
+                    "reference" : {
+                        "desc"  : "doctoc serialization utilities",
+                        "id"    : "structure.man",
+                        "label" : "doctools::toc::structure"
+                    }
+                },{
+                    "reference" : {
+                        "desc"  : "Parsing text in doctoc format",
+                        "id"    : "parse.man",
+                        "label" : "doctools::toc::parse"
+                    }
+                }],
+                "label" : "Processing"
+            }
+        }],
+        "label" : "Table of Contents",
+        "title" : "TOC"
+    }
+}
+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and map and +their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_nroff.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_nroff.html @@ -0,0 +1,294 @@ + + +doctools::toc::export::nroff - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::nroff(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::nroff - nroff export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::nroff ?0.2?
    • +
  • package require doctools::text
    • +
  • package require doctools::nroff::man_macros
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of nroff markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates nroff markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean inline
+

If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output.

+

If this flag is not set, the plugin will place a reference to the +definitions of the man macro set into the output, but not the macro +definitions themselves.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_text.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_text.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_text.html @@ -0,0 +1,280 @@ + + +doctools::toc::export::text - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::text(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::text - plain text export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::text ?0.1?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of plain text markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates plain text markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file, and format, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_wiki.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/export_wiki.html @@ -0,0 +1,287 @@ + + +doctools::toc::export::wiki - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::export::wiki(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::wiki - wiki export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::wiki ?0.1?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of wiki markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates wiki markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Wiki markup

+

The basic syntax of the wiki markup generated by this plugin are +described at http://wiki.tcl.tk/14.

+

The plugin goes beyond the classic markup to generate proper headers +and indenting.

+
+

Configuration

+

The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file and format, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/import.html Index: embedded/www/tcllib/files/modules/doctools2toc/import.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/import.html @@ -0,0 +1,536 @@ + + +doctools::toc::import - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::import(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import - Importing keyword indices

+
+ + +

Description

+

This package provides a class to manage the plugins for the import of +tables of contents from other formats, i.e. their conversion from, for +example doctoc, json, etc.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Exporting tables of contents, and

    2. +

  2. Holding tables of contents

    3. +
+

For information about the Concepts of tables of contents, +and their parts, see the same-named section. +For information about the data structure which is the major output of +the manager objects provided by this package see the section +ToC serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_TOC_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/toc/import/plugin"

    5. +

  5. the path "~/.doctools/toc/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/toc/import/plugins"

    8. +

  8. the path "~/.doctools/toc/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with two predefined import plugins, +namely

+
+
doctoc
+

See doctoc import plugin for details.

+
json
+

See json import plugin for details.

+
+

Readers wishing to write their own import plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Import plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a table of contents using +the import plugin for the format. An error is thrown if no plugin +could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to doctoc.

+

The specification of what a canonical serialization is can be +found in the section ToC serialization format.

+

The plugin has to conform to the interface specified in section +Import plugin API v2 reference.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +table of contents. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

Import plugin API v2 reference

+

Plugins are what this package uses to manage the support for any input +format beyond the ToC serialization format. Here we +specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::toc::import::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various import methods of import manager + objects to get a string encoding a table of contents in that + format.

    3. +

  3. The plugin can expect that the package + doctools::toc::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. The plugin can expect that a command named IncludeFile is + present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such. An example of +such a format would be doctoc.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide one command, with the signature shown + below.

    +
    +
    import text configuration
    +

    Whenever an import manager of doctools::toc has to parse +input for a table of contents it will invoke this command.

    +
    +
    string text
    +

    This argument will contain the text encoding the table of contents per +the format the plugin is for.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of the invokations of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html @@ -0,0 +1,294 @@ + + +doctools::toc::import::doctoc - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::import::doctoc(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import::doctoc - doctoc import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::import::doctoc ?0.1?
    • +
  • package require doctools::toc::parse
    • +
  • package require doctools::toc::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require struct::stack
    • +
  • package require struct::tree
    • +
  • package require treeql
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents import plugin +for the parsing of doctoc markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as doctoc +markup encoding a table of contents, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section ToC serialization format.

+
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/import_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/import_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/import_json.html @@ -0,0 +1,337 @@ + + +doctools::toc::import::json - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::import::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import::json - JSON import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::import::json ?0.1?
    • +
  • package require doctools::toc::structure
    • +
  • package require json
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents import plugin +for the parsing of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as JSON +markup encoding a table of contents, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section ToC serialization format.

+
+
+

JSON notation of tables of contents

+

The JSON format used for tables of contents is a direct translation of +the ToC serialization format, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::toc {
+    items {
+        {reference {
+	    desc {DocTools - Tables of Contents}
+	     id introduction.man
+	     label doctools::toc::introduction
+	}}
+	{division {
+	     id processing.man
+	     items {
+	         {reference {
+		     desc {doctoc serialization utilities}
+		     id structure.man
+		     label doctools::toc::structure
+		 }}
+		 {reference {
+		     desc {Parsing text in doctoc format}
+		     id parse.man
+		     label doctools::toc::parse
+		 }}
+	     }
+             label Processing
+        }}
+    }
+    label {Table of Contents} 
+    title TOC
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::toc" : {
+        "items" : [{
+            "reference" : {
+                "desc"  : "DocTools - Tables of Contents",
+                "id"    : "introduction.man",
+                "label" : "doctools::toc::introduction"
+            }
+        },{
+            "division" : {
+                "id"    : "processing.man",
+                "items" : [{
+                    "reference" : {
+                        "desc"  : "doctoc serialization utilities",
+                        "id"    : "structure.man",
+                        "label" : "doctools::toc::structure"
+                    }
+                },{
+                    "reference" : {
+                        "desc"  : "Parsing text in doctoc format",
+                        "id"    : "parse.man",
+                        "label" : "doctools::toc::parse"
+                    }
+                }],
+                "label" : "Processing"
+            }
+        }],
+        "label" : "Table of Contents",
+        "title" : "TOC"
+    }
+}
+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/introduction.html Index: embedded/www/tcllib/files/modules/doctools2toc/introduction.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/introduction.html @@ -0,0 +1,257 @@ + + +doctools2toc_introduction - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools2toc_introduction(n) 2.0 tcllib "Documentation tools"

+

Name

+

doctools2toc_introduction - DocTools - Tables of Contents

+
+ +

Description

+

doctoc (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables and +contents for documentation.

+

These are

+
    +

  1. A tcl based language for the semantic markup of a table of contents. +Markup is represented by Tcl commands. +Beginners should start with the +doctoc language introduction. +The formal specification is split over two documents, one dealing with +the doctoc language syntax, the other a +doctoc language command reference.

    2. +

  2. A set of packages for the programmatic manipulation of tables of +contents in memory, and their conversion between various formats, +reading and writing. The aforementioned markup language is one of the +formats which can be both read from and written to.

    3. +

  3. The system for the conversion of tables of contents is based on a +plugin mechanism, for this we have two APIs describing the interface +between the packages above and the import/export plugins.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +doctoc language introduction first. Having digested this +the formal doctoc language syntax specification should +become understandable. A writer experienced with doctoc may only +need the doctoc language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them.

    2. +

  2. A processor of documentation written in the doctoc +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose doctoc to the +user. At the bottom level, common to both applications, however we +find the three packages providing the basic facilities to handle +tables of contents, i.e. import from textual formats, programmatic +manipulation in memory, and export to textual formats. These are

    +
    +
    doctoools::toc
    +

    Programmatic manipulation of tables of contents in memory.

    +
    doctoools::toc::import
    +

    Import of tables of contents from various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    doctoools::toc::export
    +

    Export of tables of contents to various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    +

    See also section Package Overview for an overview of the +dependencies between these and other, supporting packages.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the import and export packages and their plugins. +These APIs are described in the documentation for the two relevant +packages, i.e.

    +
      +

    • doctoools::toc::import

      • +

    • doctoools::toc::export

      • +
    +
    4. +
+
+

Related formats

+

The doctoc format does not stand alone, it has two companion formats. +These are called docidx and doctools, and they are +intended for the markup of keyword indices, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the DocTools - Keyword Indices and +the DocTools - General, respectively.

+
+

Package Overview

+
+                                    ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
+                                   ~~                   |               ~~
+                doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
+                        |                               |                       |
+        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
+        |               |                         |     |    |                  |               |                       |               |
+doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
+                        |                         |     |    |                  |
+                doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
+                        doctoc                    |     |    |                  doctoc, json
+                        json                      |     |    |                  |           \\
+                        html                      |     |    |          doctools::toc::parse \\
+                        nroff                     |     |    |                  |             \\
+                        wiki                      |     |    |  +---------------+              json
+                        text                      |     |    |  |               |
+                                                doctools::toc::structure        |
+                                                                                |
+                                                                        +-------+---------------+
+                                                                        |                       |
+          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
+                |                                                                               |
+          doctools::text  doctools::nroff::man_macros                                           =
+                                                                                                |
+                                                                                        doctools::msgcat::toc::<*>
+                                                                                                c, en, de, fr
+                                                                                                (fr == en for now)
+        ~~      Interoperable objects, without actual package dependencies
+        --      Package dependency, higher requires lower package
+        =       Dynamic dependency through plugin system
+        <*>     Multiple packages following the given form of naming.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

doctools2doc_introduction, doctools2idx_introduction

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2toc/msgcat_c.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/msgcat_c.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::toc::c - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::c ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::c is a +support module providing the C language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2toc/msgcat_de.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/msgcat_de.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::toc::de - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::de ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::de is a +support module providing the DE (german) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2toc/msgcat_en.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/msgcat_en.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::toc::en - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::en ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::en is a +support module providing the EN (english) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2toc/msgcat_fr.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/msgcat_fr.html @@ -0,0 +1,171 @@ + + +doctools::msgcat::toc::fr - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::fr ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::fr is a +support module providing the FR (french) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/parse.html Index: embedded/www/tcllib/files/modules/doctools2toc/parse.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/parse.html @@ -0,0 +1,371 @@ + + +doctools::toc::parse - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::toc::parse - Parsing text in doctoc format

+
+ +

Synopsis

+
+
    +
  • package require doctools::toc::parse ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
+ +
+
+

Description

+

This package provides commands to parse text written in the +doctoc markup language and convert it into the canonical +serialization of the table of contents encoded in the text. +See the section ToC serialization format for specification +of their format.

+

This is an internal package of doctools, for use by the higher level +packages handling doctoc documents.

+
+

API

+
+
::doctools::toc::parse text text
+

The command takes the string contained in text and parses it +under the assumption that it contains a document written using the +doctoc markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section Parse errors.

+

When successful the command returns the canonical serialization of the +table of contents which was encoded in the text. +See the section ToC serialization format for specification +of that format.

+
::doctools::toc::parse file path
+

The same as text, except that the text to parse is read from +the file specified by path.

+
::doctools::toc::parse includes
+

This method returns the current list of search paths used when looking +for include files.

+
::doctools::toc::parse include add path
+

This method adds the path to the list of paths searched when +looking for an include file. The call is ignored if the path is +already in the list of paths. The method returns the empty string as +its result.

+
::doctools::toc::parse include remove path
+

This method removes the path from the list of paths searched +when looking for an include file. The call is ignored if the path is +not contained in the list of paths. The method returns the empty +string as its result.

+
::doctools::toc::parse include clear
+

This method clears the list of search paths for include files.

+
::doctools::toc::parse vars
+

This method returns a dictionary containing the current set of +predefined variables known to the vset markup command during +processing.

+
::doctools::toc::parse var set name value
+

This method adds the variable name to the set of predefined +variables known to the vset markup command during processing, +and gives it the specified value. The method returns the empty +string as its result.

+
::doctools::toc::parse var unset name
+

This method removes the variable name from the set of predefined +variables known to the vset markup command during +processing. The method returns the empty string as its result.

+
::doctools::toc::parse var clear ?pattern?
+

This method removes all variables matching the pattern from the +set of predefined variables known to the vset markup command +during processing. The method returns the empty string as its result.

+

The pattern matching is done with string match, and the +default pattern used when none is specified, is *.

+
+
+

Parse errors

+

The format of the parse error messages thrown when encountering +violations of the doctoc markup syntax is human readable and +not intended for processing by machines. As such it is not documented.

+

However, the errorCode attached to the message is +machine-readable and has the following format:

+
    +

  1. The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more.

    2. +

  2. Each error element will be a list containing six strings describing an +error in detail. The strings will be

    +
      +

    1. The path of the file the error occured in. This may be empty.

      2. +

    2. The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero.

      3. +

    3. The line the first character after the error is on. +Lines are counted from one.

      4. +

    4. The column the first character after the error is at. +Columns are counted from zero.

      5. +

    5. The message code of the error. This value can be used as argument to +msgcat::mc to obtain a localized error message, assuming that +the application had a suitable call of doctools::msgcat::init to +initialize the necessary message catalogs (See package +doctools::msgcat).

      6. +

    6. A list of details for the error, like the markup command involved. In +the case of message code doctoc/include/syntax this value is +the set of errors found in the included file, using the format +described here.

      7. +
    +
    3. +
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/structure.html Index: embedded/www/tcllib/files/modules/doctools2toc/structure.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/doctools2toc/structure.html @@ -0,0 +1,324 @@ + + +doctools::toc::structure - Documentation tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

doctools::toc::structure(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::structure - Doctoc serialization utilities

+
+ + +

Description

+

This package provides commands to work with the serializations of +tables of contents as managed by the doctools system v2, and specified +in section ToC serialization format.

+

This is an internal package of doctools, for use by the higher level +packages handling tables of contents and their conversion into and out +of various other formats, like documents written using doctoc +markup.

+
+

API

+
+
::doctools::toc::structure verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +regular serialization of a table of contents and will throw an +error if that is not the case. The result of the command is the empty +string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
::doctools::toc::structure verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a table of contents and will throw +an error if that is not the case. The result of the command is the +empty string.

+

For the specification of canonical serializations see the section +ToC serialization format.

+
::doctools::toc::structure canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a table of contents and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained table of contents and return it as its result. If the +input is already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
::doctools::toc::structure print serial
+

This command assumes that the argument serial contains a valid +regular serialization of a table of contents and returns a string +containing that table in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of regular serializations see the section +ToC serialization format.

+
::doctools::toc::structure merge seriala serialb
+

This command accepts the regular serializations of two tables of +contents and uses them to create their union. The result of the +command is the canonical serialization of this unified table of +contents.

+

Title and label of the resulting table are taken from the table +contained in serialb.

+

The whole table and its divisions are merged recursively in the same +manner:

+
    +

  1. All reference elements which occur in both divisions (identified by +their label) are unified with document id's and descriptions taken +from the second table.

    2. +

  2. All division elements which occur in both divisions (identified by +their label) are unified with the optional document id taken from the +second table, if any, or from the first if none is in the second. The +elements in the division are merged recursively using the same +algorithm as described in this list.

    3. +

  3. Type conflicts between elements, i.e. finding two elements with the +same label but different types result in a merge error.

    4. +

  4. All elements found in the second division but not in the first are +added to the end of the list of elements in the merge result.

    5. +
+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/exif/exif.html Index: embedded/www/tcllib/files/modules/exif/exif.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/exif/exif.html @@ -0,0 +1,194 @@ + +exif - EXIF parsing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

exif(n) 1.1.2 tcllib "EXIF parsing"

+

Name

+

exif - Tcl EXIF extracts and parses EXIF fields from digital images

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require exif ?1.1.2?
    • +
+ +
+
+

Description

+

The EXIF package is a recoding of Chris Breeze's Perl package to do +the same thing. This version accepts a channel as input and returns a +serialized array with all the recognised fields parsed out.

+

There is also a function to obtain a list of all possible field names +that might be present, which is useful in building GUIs that present +such information.

+
+

COMMANDS

+
+
exif::analyze channel ?thumbnail?
+

channel should be an open file handle rewound to the start. It +does not need to be seekable. channel will be set to binary +mode and is left wherever it happens to stop being parsed, usually at +the end of the file or the start of the image data. You must open and +close the stream yourself. If no error is thrown, the return value is +a serialized array with informative English text about what was found +in the EXIF block. Failure during parsing or I/O throw errors.

+

If thumbnail is present and not the empty string it will be +interpreted as the name of a file, and the thumbnail image contained +in the exif data will be written into it.

+
exif::analyzeFile filename ?thumbnail?
+

This is a file-based wrapper around exif::analyze. Instead of +taking a stream it takes a filename and analyzes the contents of +the specified file.

+
exif::fieldnames
+

This returns a list of all possible field names. That is, the array +returned by exif::analyze will not contain keys that are not +listed in the return from exif::fieldnames. Of course, if +information is missing in the image file, exif::analyze may not +return all the fields listed in the return from exif::fieldnames. +This function is expected to be primarily useful for building GUIs to +display results.

+

N.B.: Read the implementation of exif::fieldnames before +modifying the implementation of exif::analyze.

+
+
+

COPYRIGHTS

+

(c) 2002 Darren New +Hold harmless the author, and any lawful use is allowed.

+
+

ACKNOWLEDGEMENTS

+

This code is a direct translation of version 1.3 of exif.pl by Chris +Breeze. See the source for full headers, references, etc.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category exif of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/fileutil.html Index: embedded/www/tcllib/files/modules/fileutil/fileutil.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fileutil/fileutil.html @@ -0,0 +1,470 @@ + + +fileutil - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil(n) 1.14.5 tcllib "file utilities"

+

Name

+

fileutil - Procedures implementing some file utilities

+
+ + +

Description

+

This package provides implementations of standard unix utilities.

+
+
::fileutil::lexnormalize path
+

This command performs purely lexical normalization on the path and returns +the changed path as its result. Symbolic links in the path are not resolved.

+

Examples:

+
+    fileutil::lexnormalize /foo/./bar
+    => /foo/bar
+    fileutil::lexnormalize /foo/../bar
+    => /bar
+
+
+
::fileutil::fullnormalize path
+

This command resolves all symbolic links in the path and returns +the changed path as its result. +In contrast to the builtin file normalize this command +resolves a symbolic link in the last element of the path as well.

+
::fileutil::test path codes ?msgvar? ?label?
+

A command for the testing of several properties of a path. The +properties to test for are specified in codes, either as a list +of keywords describing the properties, or as a string where each +letter is a shorthand for a property to test. The recognized keywords, +shorthands, and associated properties are shown in the list below. The +tests are executed in the order given to the command.

+

The result of the command is a boolean value. It will be true if and +only if the path passes all the specified tests. +In the case of the path not passing one or more test the first +failing test will leave a message in the variable referenced by +msgvar, if such is specified. The message will be prefixed with +label, if it is specified. +Note that the variabled referenced by msgvar is not touched at +all if all the tests pass.

+
+
read
+

file readable

+
write
+

file writable

+
exists
+

file exists

+
exec
+

file executable

+
file
+

file isfile

+
dir
+

file isdirectory

+
+
::fileutil::cat (?options? file)...
+

A tcl implementation of the UNIX cat command. Returns the +contents of the specified file(s). The arguments are files to read, +with interspersed options configuring the process. If there are +problems reading any of the files, an error will occur, and no data +will be returned.

+

The options accepted are -encoding, -translation, +-eofchar, and --. With the exception of the last all +options take a single value as argument, as specified by the tcl +builtin command fconfigure. The -- has to be used to +terminate option processing before a file if that file's name begins +with a dash.

+

Each file can have its own set of options coming before it, and for +anything not specified directly the defaults are inherited from the +options of the previous file. The first file inherits the system +default for unspecified options.

+
::fileutil::writeFile ?options? file data
+

The command replaces the current contents of the specified file +with data, with the process configured by the options. The +command accepts the same options as ::fileutil::cat. The +specification of a non-existent file is legal and causes the command +to create the file (and all required but missing directories).

+
::fileutil::appendToFile ?options? file data
+

This command is like ::fileutil::writeFile, except that the +previous contents of file are not replaced, but appended to. The +command accepts the same options as ::fileutil::cat

+
::fileutil::insertIntoFile ?options? file at data
+

This comment is similar to ::fileutil::appendToFile, except that +the new data is not appended at the end, but inserted at a specified +location within the file. In further contrast this command has to be +given the path to an existing file. It will not create a missing file, +but throw an error instead.

+

The specified location at has to be an integer number in the +range 0 ... [file size file]. 0 will cause +insertion of the new data before the first character of the existing +content, whereas [file size file] causes insertion after +the last character of the existing content, i.e. appending.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::removeFromFile ?options? file at n
+

This command is the complement to ::fileutil::insertIntoFile, removing n characters from the file, starting at location at. +The specified location at has to be an integer number in the +range 0 ... [file size file] - n. 0 +will cause the removal of the new data to start with the first +character of the existing content, +whereas [file size file] - n causes the removal of +the tail of the existing content, i.e. the truncation of the file.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::replaceInFile ?options? file at n data
+

This command is a combination of ::fileutil::removeFromFile and +::fileutil::insertIntoFile. It first removes the part of the +contents specified by the arguments at and n, and then +inserts data at the given location, effectively replacing the +removed by content with data. +All constraints imposed on at and n by +::fileutil::removeFromFile and ::fileutil::insertIntoFile +are obeyed.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::updateInPlace ?options? file cmd
+

This command can be seen as the generic core functionality of +::fileutil::replaceInFile. +It first reads the contents of the specified file, then runs the +command prefix cmd with that data appended to it, and at last +writes the result of that invokation back as the new contents of the +file.

+

If the executed command throws an error the file is not changed.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::fileType filename
+

An implementation of the UNIX file command, which uses +various heuristics to guess the type of a file. Returns a list +specifying as much type information as can be determined about the +file, from most general (eg, "binary" or "text") to most specific (eg, +"gif"). For example, the return value for a GIF file would be "binary +graphic gif". The command will detect the following types of files: +directory, empty, binary, text, script (with interpreter), executable +elf, executable dos, executable ne, executable pe, graphic gif, graphic +jpeg, graphic png, graphic tiff, graphic bitmap, html, xml (with doctype +if available), message pgp, binary pdf, text ps, text eps, binary +gravity_wave_data_frame, compressed bzip, compressed gzip, compressed +zip, compressed tar, audio wave, audio mpeg, and link. It further +detects doctools, doctoc, and docidx documentation files, and +tklib diagrams.

+
::fileutil::find ?basedir ?filtercmd??
+

An implementation of the unix command find. Adapted from the +Tcler's Wiki. Takes at most two arguments, the path to the directory +to start searching from and a command to use to evaluate interest in +each file. The path defaults to ".", i.e. the current +directory. The command defaults to the empty string, which means that +all files are of interest. The command takes care not to +lose itself in infinite loops upon encountering circular link +structures. The result of the command is a list containing the paths +to the interesting files.

+

The filtercmd, if specified, is interpreted as a command prefix +and one argument is added to it, the name of the file or directory +find is currently looking at. Note that this name is not fully +qualified. It has to be joined it with the result of pwd to get +an absolute filename.

+

The result of filtercmd is a boolean value that indicates if the +current file should be included in the list of interesting files.

+

Example:

+
+    # find .tcl files
+    package require fileutil
+    proc is_tcl {name} {return [string match *.tcl $name]}
+    set tcl_files [fileutil::find . is_tcl]
+
+
+
::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
+

This command is based upon the TclX command +recursive_glob, except that it doesn't allow recursion over more +than one directory at a time. It uses ::fileutil::find +internally and is thus able to and does follow symbolic links, +something the TclX command does not do. First argument is +the directory to start the search in, second argument is a list of +patterns. The command returns a list of all files reachable +through basedir whose names match at least one of the +patterns. The options before the pattern-list determine the style of +matching, either regexp or glob. glob-style matching is the default if +no options are given. Usage of the option -- stops option +processing. This allows the use of a leading '-' in the patterns.

+
::fileutil::foreachLine var filename cmd
+

The command reads the file filename and executes the script +cmd for every line in the file. During the execution of the +script the variable var is set to the contents of the current +line. The return value of this command is the result of the last +invocation of the script cmd or the empty string if the file was +empty.

+
::fileutil::grep pattern ?files?
+

Implementation of grep. Adapted from the Tcler's Wiki. The +first argument defines the pattern to search for. This is +followed by a list of files to search through. The list is +optional and stdin will be used if it is missing. The result +of the procedures is a list containing the matches. Each match is a +single element of the list and contains filename, number and contents +of the matching line, separated by a colons.

+
::fileutil::install ?-m mode? source destination
+

The install command is similar in functionality to the install +command found on many unix systems, or the shell script +distributed with many source distributions (unix/install-sh in the Tcl +sources, for example). It copies source, which can be either a +file or directory to destination, which should be a directory, +unless source is also a single file. The ?-m? option lets +the user specify a unix-style mode (either octal or symbolic - see +file attributes.

+
::fileutil::stripN path n
+

Removes the first n elements from the specified path and +returns the modified path. If n is greater than the number of +components in path an empty string is returned. The number of +components in a given path may be determined by performing +llength on the list returned by file split.

+
::fileutil::stripPwd path
+

If, and only if the path is inside of the directory returned by +[pwd] (or the current working directory itself) it is made +relative to that directory. In other words, the current working +directory is stripped from the path. The possibly modified path +is returned as the result of the command. If the current working +directory itself was specified for path the result is the string +".".

+
::fileutil::stripPath prefix path
+

If, and only of the path is inside of the directory +"prefix" (or the prefix directory itself) it is made relative to +that directory. In other words, the prefix directory is stripped from +the path. The possibly modified path is returned as the result +of the command. +If the prefix directory itself was specified for path the result +is the string ".".

+
::fileutil::jail jail path
+

This command ensures that the path is not escaping the directory +jail. It always returns an absolute path derived from path +which is within jail.

+

If path is an absolute path and already within jail it is +returned unmodified.

+

An absolute path outside of jail is stripped of its root element +and then put into the jail by prefixing it with it. The same +happens if path is relative, except that nothing is stripped of +it. Before adding the jail prefix the path is lexically +normalized to prevent the caller from using .. segments in +path to escape the jail.

+
::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
+

Implementation of touch. Alter the atime and mtime of the +specified files. If -c, do not create files if they do not +already exist. If -r, use the atime and mtime from +ref_file. If -t, use the integer clock value +time. It is illegal to specify both -r and +-t. If -a, only change the atime. If -m, +only change the mtime.

+

This command is not available for Tcl versions less than 8.3.

+
::fileutil::tempdir
+

The command returns the path of a directory where the caller can +place temporary files, such as "/tmp" on Unix systems. The +algorithm we use to find the correct directory is as follows:

+
    +

  1. The directory set by an invokation of ::fileutil::tempdir with +an argument. If this is present it is tried exclusively and none of +the following item are tried.

    2. +

  2. The directory named in the TMPDIR environment variable.

    3. +

  3. The directory named in the TEMP environment variable.

    4. +

  4. The directory named in the TMP environment variable.

    5. +

  5. A platform specific location:

    +
    +
    Windows
    +

    "C:\TEMP", "C:\TMP", "\TEMP", +and "\TMP" are tried in that order.

    +
    (classic) Macintosh
    +

    The TRASH_FOLDER environment variable is used. This is most likely +not correct.

    +
    Unix
    +

    The directories "/tmp", "/var/tmp", and "/usr/tmp" are +tried in that order.

    +
    +
    6. +
+

The algorithm utilized is mainly that used in the Python standard +library. The exception is the first item, the ability to have the +search overridden by a user-specified directory.

+
::fileutil::tempdir path
+

In this mode the command sets the path as the first and only +directory to try as a temp. directory. See the previous item for the +use of the set directory. The command returns the empty string.

+
::fileutil::tempdirReset
+

Invoking this command clears the information set by the +last call of [::fileutil::tempdir path]. +See the last item too.

+
::fileutil::tempfile ?prefix?
+

The command generates a temporary file name suitable for writing to, +and the associated file. The file name will be unique, and the file +will be writable and contained in the appropriate system specific temp +directory. The name of the file will be returned as the result of the +command.

+

The code was taken from http://wiki.tcl.tk/772, attributed to +Igor Volobouev and anon.

+
::fileutil::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.

+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/multi.html Index: embedded/www/tcllib/files/modules/fileutil/multi.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fileutil/multi.html @@ -0,0 +1,173 @@ + + +fileutil::multi - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::multi(n) 0.1 tcllib "file utilities"

+

Name

+

fileutil::multi - Multi-file operation, scatter/gather, standard object

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::multi ?0.1?
    • +
  • package require fileutil::multi::op ?0.1?
    • +
  • package require wip ?1.0?
    • +
+ +
+
+

Description

+

This package provides a single command to perform actions on multiple +files selected by glob patterns. It is a thin layer over the package +fileutil::multi::op which provides objects for the +same. This package simply creates a single such object and directs all +file commands to it.

+

At the core is a domain specific language allowing the easy +specification of multi-file copy and/or move and/or deletion +operations. Alternate names would be scatter/gather processor, or +maybe even assembler. +For the detailed specification of this language, and examples, please +see the documention for the package fileutil::multi::op.

+
+

PUBLIC API

+

The main command of the package is:

+
+
::fileutil::multi ?word...?
+

This command interprets the specified words as file commands to +execute. See the section FILE API of the +documentation for the package fileutil::multi::op for +the set of acceptable commands, their syntax, and semantics.

+

The result of the command is the result generated by the last file +command it executed.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/multiop.html Index: embedded/www/tcllib/files/modules/fileutil/multiop.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fileutil/multiop.html @@ -0,0 +1,458 @@ + + +fileutil::multi::op - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::multi::op(n) 0.5.3 tcllib "file utilities"

+

Name

+

fileutil::multi::op - Multi-file operation, scatter/gather

+
+ + +

Description

+

This package provides objects which are able to perform actions on +multiple files selected by glob patterns.

+

At the core is a domain specific language allowing the easy +specification of multi-file copy and/or move and/or deletion +operations. Alternate names would be scatter/gather processor, or +maybe even assembler.

+
+

CLASS API

+

The main command of the package is:

+
+
::fileutil::multi::op ?opName? ?word...?
+

The command creates a new multi-file operation object with an +associated global Tcl command whose name is opName. This +command can be used to invoke the various possible file operations. +It has the following general form:

+
+
opName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If the string %AUTO% is used as the opName then the +package will generate a unique name on its own.

+

If one or more words are specified they are interpreted as an +initial set of file commands to execute. I.e. the method do +of the newly constructed object is implicitly invoked using the words +as its arguments.

+
+
+

OBJECT API

+

The following methods are possible for multi-file operation objects:

+
+
$opName do ?word...?
+

This method interprets the specified words as file commands to +execute. See the section FILE API for the set of +acceptable commands, their syntax, and semantics.

+

The result of the method is the result generated by the last file +command it executed.

+
+
+

FILE API

+

Both object constructor and method do take a list of words +and interpret them as file commands to execute. The names were chosen +to allow the construction of operations as sentences in near-natural +language. Most of the commands influence just the state of the object, +i.e. are simply providing the configuration used by the command +triggering the actual action.

+
+
into directory
+

Specifies the destination directory for operations.

+
in directory
+

Alias for into.

+
to directory
+

Alias for into.

+
from directory
+

Specifies the source directory for operations.

+
not pattern
+

Specifies a glob pattern for paths to be excluded from the operation.

+
for pattern
+

Alias for not.

+
exclude pattern
+

Alias for not.

+
but
+

Has no arguments of its own, but looks ahead in the list of words and +executes all not commands immediately following it. This allows the +construction of "but not" and "but exclude" clauses for a more natural +sounding specification of excluded paths.

+
except
+

A semi-alias for but. Has no arguments of its own, but looks +ahead in the list of words and executes all for commands +immediately following it. This allows the construction of "except for" +clauses for a more natural sounding specification of excluded paths.

+
as name
+

Specifies a new name for the first file handled by the current +operation. I.e. for the renaming of a single file during the +operation.

+
recursive
+

Signals that file expansion should happen in the whole directory +hierarchy and not just the directory itself.

+
recursively
+

An alias for recursive.

+
copy
+

Signals that the operation is the copying of files from source to +destination directory per the specified inclusion and exclusion +patterns.

+
move
+

Signals that the operation is the moving of files from source to +destination directory per the specified inclusion and exclusion +patterns.

+
remove
+

Signals that the operation is the removal of files in the destination +directory per the specified inclusion and exclusion patterns.

+
expand
+

Signals that there is no operation but the calculation of the set of +files from the include and exclude patterns. This operation is not +available if the-set is used.

+
invoke cmdprefix
+

Signals that the user-specified command prefix cmdprefix is the +operation to perform. The command prefix is executed at the global +level and given the source directory, destination directory, and set +of files (as dictionary mapping from source to destination files), in +this order.

+
reset
+

Forces the object into the ground state where all parts of the +configuration have default values.

+
(
+

Saves a copy of the current object state on a stack.

+
)
+

Takes the state at the top of the state stack and restores it, +i.e. makes it the new current object state.

+
cd directory
+

Changes the destination directory to the sub-directory directory +of the current destination.

+
up
+

Changes the destination directory to the parent directory of the +current destination.

+
for-windows
+

Checks that Windows is the current platform. Aborts processing if not.

+
for-win
+

An alias for for-windows.

+
for-unix
+

Checks that Unix is the current platform. Aborts processing if not.

+
the pattern
+

This command specifies the files to operate on per a glob pattern, and +is also the active element, i.e. the command which actually performs +the specified operation. All the other commands only modified the +object state to set the operation up, but di nothing else.

+

To allow for a more natural sounding syntax this command also looks +ahead in the list of words looks and executes several commands +immediately following it before performing its own actions. +These commands are as, but, exclude, except, +from, and into (and aliases). That way these commands act +like qualifiers, and still take effect as if they had been written +before this command.

+

After the operation has been performed the object state the exclude +patterns and the alias name, if specified, are reset to their default +values (i.e. empty), but nothing else.

+
the-set varname
+

Like the, however the set of files to use is not specified +implicitly per a glob pattern, but contained and loaded from the +specified variable. The operation expand is not available +if this command is used.

+
-> varname
+

Saves the set of files from the last expansion into the specified +variable.

+
strict
+

Make file expansion and definition of destination directory (in +and aliases) strict, i.e. report errors for missing directories, and +empty expansion.

+
!strict
+

Complement of strict. A missing destination directory or empty +expansion are not reported as errors.

+
files
+

Limit the search to files. Default is to accept every type of path.

+
links
+

Limit the search to symbolic links. Default is to accept every type of path.

+
directories
+

Limit the search to directories. Default is to accept every type of path.

+
dirs
+

An alias for directories.

+
all
+

Accept all types of paths (default).

+
state?
+

Returns the current state of the object as dictionary. The dictionary keys and their meanings are:

+
+
as
+

Last setting made by as.

+
excluded
+

List of currently known exclusion patterns.

+
from
+

Current source directory, set by from.

+
into
+

Current destination directory, set by into (and aliases).

+
operation
+

Current operation to perform, set by copy, move, remove, expand, or invoke.

+
recursive
+

Current recursion status. Set/unset by recursive and !recursive.

+
strict
+

Current strictness. Set/unset by strict and !strict.

+
type
+

Current path type limiter. Set by either files, directories, links, or all.

+
+
as?
+

Returns the current alias name.

+
excluded?
+

Returns the current set of exclusion patterns.

+
from?
+

Returns the current source directory.

+
into?
+

Returns the current destination directory.

+
operation?
+

Returns the current operation to perform.

+
recursive?
+

Returns the current recursion status.

+
strict?
+

Returns the current strictness.

+
type?
+

Returns the current path type limiter.

+
+
+

EXAMPLES

+

The following examples assume that the variable F contains a +reference to a multi-file operation object.

+
+    $F do copy                       \\
+	the  *.dll                    \\
+	from c:/TDK/PrivateOpenSSL/bin \\
+	to   [installdir_of tls]
+
+
+    $F do move      \\
+	the  *       \\
+	from /sources \\
+	into /scratch  \\
+	but not *.html
+    # Alternatively use 'except for *.html'.
+
+
+    $F do           \\
+	move         \\
+	the  index    \\
+	from /sources  \\
+	into /scratch   \\
+	as   pkgIndex.tcl
+
+
+    $F do         \\
+	remove     \\
+	the *.txt  \\
+	in /scratch
+
+

Note that the fact that most commands just modify the object state +allows us to use more off forms as specifications instead of just +nearly-natural language sentences. +For example the second example in this section can re-arranged into:

+
+    $F do            \\
+	from /sources \\
+	into /scratch  \\
+	but not *.html \\
+	move           \\
+	the  *
+
+

and the result is not only still a valid specification, but even stays +relatively readable.

+

Further note that the information collected by the commands but, +except, and as is automatically reset after the associated +the was executed. However no other state is reset in that +manner, allowing the user to avoid repetitions of unchanging +information. For example the second and third examples of this section +can be merged and rewritten into the equivalent:

+
+$F do                   \\
+    move                 \\
+    the  *                \\
+    from /sources          \\
+    into /scratch           \\
+    but not *.html not index \\
+    the  index               \\
+    as   pkgIndex.tcl
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/traverse.html Index: embedded/www/tcllib/files/modules/fileutil/traverse.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fileutil/traverse.html @@ -0,0 +1,231 @@ + + +fileutil_traverse - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil_traverse(n) 0.4.3 tcllib "file utilities"

+

Name

+

fileutil_traverse - Iterative directory traversal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require fileutil::traverse ?0.4.3?
    • +
  • package require fileutil
    • +
  • package require control
    • +
+ +
+
+

Description

+

This package provides objects for the programmable traversal of +directory hierarchies. +The main command exported by the package is:

+
+
::fileutil::traverse ?objectName? path ?option value...?
+

The command creates a new traversal object with an associated global +Tcl command whose name is objectName. This command may be used +to invoke various operations on the traverser. +If the string %AUTO% is used as the objectName then a +unique name will be generated by the package itself.

+

Regarding the recognized options see section OPTIONS. Note +that all these options can be set only during the creation of the +traversal object. Changing them later is not possible and causes +errors to be thrown if attempted.

+

The object command has the following general form:

+
+
$traverser command ?arg arg ...?
+

Command and its arguments determine the exact behavior of +the object.

+
+
+

The following commands are possible for traversal objects:

+
+
$traverser files
+

This method is the most highlevel one provided by traversal +objects. When invoked it returns a list containing the names of all +files and directories matching the current configuration of the +traverser.

+
$traverser foreach filevar script
+

The highlevel files method (see above) is based on this +mid-level method. When invoked it finds all files and directories +matching per the current configuration and executes the script +for each path. The current path under consideration is stored in the +variable named by filevar. Both variable and script live / are +executed in the context of the caller of the method. In the method +files the script simply saves the found paths into the list +to return.

+
$traverser next filevar
+

This is the lowest possible interface to the traverser, the core all +higher methods are built on. When invoked it returns a boolean value +indicating whether it found a path matching the current configuration +(True), or not (False). If a path was found it is +stored into the variable named by filevar, in the context of the +caller. +The foreach method simply calls this method in a loop until +it returned False. This method is exposed so that we are also +able to incrementally traverse a directory hierarchy in an event-based +manner.

+
+
+

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.

+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/ftp/ftp.html Index: embedded/www/tcllib/files/modules/ftp/ftp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ftp/ftp.html @@ -0,0 +1,444 @@ + + +ftp - ftp client + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ftp(n) 2.4.11 tcllib "ftp client"

+

Name

+

ftp - Client-side tcl implementation of the ftp protocol

+
+ + +

Description

+

The ftp package provides the client side of the ftp protocol as +specified in RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). +The package implements both active (default) and passive ftp sessions.

+

A new ftp session is started with the ::ftp::Open command. To +shutdown an existing ftp session use ::ftp::Close. All other +commands are restricted to usage in an an open ftp session. They will +generate errors if they are used out of context. The ftp package +includes file and directory manipulating commands for remote sites. To +perform the same operations on the local site use commands built into +the core, like cd or file.

+

The output of the package is controlled by two state variables, +::ftp::VERBOSE and ::ftp::DEBUG. Setting +::ftp::VERBOSE to "1" forces the package to show all responses +from a remote server. The default value is "0". Setting +::ftp::DEBUG to "1" enables debugging and forces the package to +show all return codes, states, state changes and "real" ftp +commands. The default value is "0".

+

The command ::ftp::DisplayMsg is used to show the different +messages from the ftp session. The setting of ::ftp::VERBOSE +determines if this command is called or not. The current +implementation of the command uses the log package of tcllib +to write the messages to their final destination. This means that the +behaviour of ::ftp::DisplayMsg can be customized without +changing its implementation. For more radical changes overwriting its +implementation by the application is of course still possible. Note +that the default implementation honors the option -output to +::ftp::Open for a session specific log command.

+

Caution: The default implementation logs error messages like +all other messages. If this behaviour is changed to throwing an error +instead all commands in the API will change their behaviour too. In +such a case they will not return a failure code as described below but +pass the thrown error to their caller.

+
+

API

+
+
::ftp::Open server user passwd ?options?
+

This command is used to start a FTP session by establishing a control +connection to the FTP server. The defaults are used for any option not +specified by the caller.

+

The command takes a host name server, a user name user and +a password password as its parameters and returns a session +handle that is an integer number greater than or equal to "0", if the +connection is successfully established. Otherwise it returns "-1". +The server parameter must be the name or internet address (in +dotted decimal notation) of the ftp server to connect to. The +user and passwd parameters must contain a valid user name +and password to complete the login process.

+

The options overwrite some default values or set special abilities:

+
+
-blocksize size
+

The blocksize is used during data transfer. At most size bytes +are transfered at once. The default value for this option is 4096. +The package will evaluate the -progress callback for the +session after the transfer of each block.

+
-timeout seconds
+

If seconds is non-zero, then ::ftp::Open sets up a timeout +which will occur after the specified number of seconds. The default +value is 600.

+
-port number
+

The port number specifies an alternative remote port on the ftp +server on which the ftp service resides. Most ftp services listen for +connection requests on the default port 21. Sometimes, usually for +security reasons, port numbers other than 21 are used for ftp +connections.

+
-mode mode
+

The transfer mode option determines if a file transfer occurs in +active or passive mode. In passive mode the client +will ask the ftp server to listen on a data port and wait for the +connection rather than to initiate the process by itself when a data +transfer request comes in. Passive mode is normally a requirement when +accessing sites via a firewall. The default mode is active.

+
-progress callback
+

This callback is evaluated whenever a block of data was +transfered. See the option -blocksize for how to specify the +size of the transfered blocks.

+

When evaluating the callback one argument is appended to the +callback script, the current accumulated number of bytes transferred +so far.

+
-command callback
+

Specifying this option places the connection into asynchronous +mode. The callback is evaluated after the completion of any +operation. When an operation is running no further operations must be +started until a callback has been received for the currently executing +operation.

+

When evaluating the callback several arguments are appended to +the callback script, namely the keyword of the operation that has +completed and any additional arguments specific to the operation. If +an error occurred during the execution of the operation the callback is +given the keyword error.

+
-output callback
+

This option has no default. If it is set the default implementation of +::ftp::DisplayMsg will use its value as command prefix to log +all internal messages. The callback will have three arguments appended +to it before evaluation, the id of the session, the message itself, +and the connection state, in this order.

+
+
::ftp::Close handle
+

This command terminates the specified ftp session. If no file transfer +is in progress, the server will close the control connection +immediately. If a file transfer is in progress however, the control +connection will remain open until the transfers completes. When that +happens the server will write the result response for the transfer to +it and close the connection afterward.

+
::ftp::Cd handle directory
+

This command changes the current working directory on the ftp server +to a specified target directory. The command returns 1 if the +current working directory was successfully changed to the specified +directory or 0 if it fails. The target directory can be

+
    +

  • a subdirectory of the current directory,

    • +

  • Two dots, .. (as an indicator for the parent directory of +the current directory)

    • +

  • or a fully qualified path to a new working directory.

    • +
+
::ftp::Pwd handle
+

This command returns the complete path of the current working +directory on the ftp server, or an empty string in case of an error.

+
::ftp::Type handle ?ascii|binary|tenex?
+

This command sets the ftp file transfer type to either ascii, +binary, or tenex. The command always returns the +currently set type. If called without type no change is made.

+

Currently only ascii and binary types are +supported. There is some early (alpha) support for Tenex mode. The +type ascii is normally used to convert text files into a +format suitable for text editors on the platform of the destination +machine. This mainly affects end-of-line markers. The type +binary on the other hand allows the undisturbed transfer of +non-text files, such as compressed files, images and executables.

+
::ftp::List handle ?pattern?
+

This command returns a human-readable list of files. Wildcard +expressions such as "*.tcl" are allowed. If pattern +refers to a specific directory, then the contents of that directory +are returned. If the pattern is not a fully-qualified path +name, the command lists entries relative to the current remote +directory. If no pattern is specified, the contents of the +current remote directory is returned.

+

The listing includes any system-dependent information that the server +chooses to include. For example most UNIX systems produce output from +the command ls -l. The command returns the retrieved +information as a tcl list with one item per entry. Empty lines and +UNIX's "total" lines are ignored and not included in the result as +reported by this command.

+

If the command fails an empty list is returned.

+
::ftp::NList handle ?directory?
+

This command has the same behavior as the ::ftp::List command, +except that it only retrieves an abbreviated listing. This means only +file names are returned in a sorted list.

+
::ftp::FileSize handle file
+

This command returns the size of the specified file on the ftp +server. If the command fails an empty string is returned.

+

ATTENTION! It will not work properly when in ascii mode and +is not supported by all ftp server implementations.

+
::ftp::ModTime handle file
+

This command retrieves the time of the last modification of the +file on the ftp server as a system dependent integer value in +seconds or an empty string if an error occurred. Use the built-in +command clock to convert the retrieves value into other formats.

+
::ftp::Delete handle file
+

This command deletes the specified file on the ftp server. The +command returns 1 if the specified file was successfully deleted or 0 +if it failed.

+
::ftp::Rename handle from to
+

This command renames the file from in the current directory of +the ftp server to the specified new file name to. This new file +name must not be the same as any existing subdirectory or file name. +The command returns 1 if the specified file was successfully renamed +or 0 if it failed.

+
::ftp::Put handle (local | -data data | -channel chan) ?remote?
+

This command transfers a local file local to a remote file +remote on the ftp server. If the file parameters passed to the +command do not fully qualified path names the command will use the +current directory on local and remote host. If the remote file name is +unspecified, the server will use the name of the local file as the +name of the remote file. The command returns 1 to indicate a successful +transfer and 0 in the case of a failure.

+

If -data data is specified instead of a local file, the +system will not transfer a file, but the data passed into it. In +this case the name of the remote file has to be specified.

+

If -channel chan is specified instead of a local file, +the system will not transfer a file, but read the contents of the +channel chan and write this to the remote file. In this case the +name of the remote file has to be specified. After the transfer +chan will be closed.

+
::ftp::Append handle (local | -data data | -channel chan) ?remote?
+

This command behaves like ::ftp::Puts, but appends the +transfered information to the remote file. If the file did not exist +on the server it will be created.

+
::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
+

This command retrieves a remote file remote on the ftp server +and stores its contents into the local file local. If the file +parameters passed to the command are not fully qualified path names +the command will use the current directory on local and remote +host. If the local file name is unspecified, the server will use the +name of the remote file as the name of the local file. The command +returns 1 to indicate a successful transfer and 0 in the case of a +failure. The command will throw an error if the directory the file +local is to be placed in does not exist.

+

If -variable varname is specified, the system will +store the retrieved data into the variable varname instead of a +file.

+

If -channel chan is specified, the system will write +the retrieved data into the channel chan instead of a file. The +system will not close chan after the transfer, this is +the responsibility of the caller to ::ftp::Get.

+
::ftp::Reget handle remote ?local? ?from? ?to?
+

This command behaves like ::ftp::Get, except that if local file +local exists and is smaller than remote file remote, the +local file is presumed to be a partially transferred copy of the +remote file and the transfer is continued from the apparent point of +failure. The command will throw an error if the directory the file +local is to be placed in does not exist. This command is useful +when transferring very large files over networks that tend to drop +connections.

+

Specifying the additional byte offsets from and to will +cause the command to change its behaviour and to download exactly the +specified slice of the remote file. This mode is possible only if a +local destination is explicitly provided. Omission of to leads +to downloading till the end of the file.

+
::ftp::Newer handle remote ?local?
+

This command behaves like ::ftp::Get, except that it retrieves +the remote file only if the modification time of the remote file is +more recent than the file on the local system. If the file does not +exist on the local system, the remote file is considered newer. The +command will throw an error if the directory the file local is +to be placed in does not exist.

+
::ftp::MkDir handle directory
+

This command creates the specified directory on the ftp +server. If the specified path is relative the new directory will be +created as a subdirectory of the current working directory. Else the +created directory will have the specified path name. The command +returns 1 to indicate a successful creation of the directory and 0 in +the case of a failure.

+
::ftp::RmDir handle directory
+

This command removes the specified directory on the ftp server. The +remote directory has to be empty or the command will fail. The command +returns 1 to indicate a successful removal of the directory and 0 in +the case of a failure.

+
::ftp::Quote handle arg1 arg2 ...
+

This command is used to send an arbitrary ftp command to the +server. It cannot be used to obtain a directory listing or for +transferring files. It is included to allow an application to execute +commands on the ftp server which are not provided by this package. +The arguments are sent verbatim, i.e. as is, with no changes.

+

In contrast to the other commands in this package this command will +not parse the response it got from the ftp server but return it +verbatim to the caller.

+
::ftp::DisplayMsg handle msg ?state?
+

This command is used by the package itself to show the different +messages from the ftp sessions. The package itself declares this +command very simple, writing the messages to stdout (if +::ftp::VERBOSE was set, see below) and throwing tcl errors for +error messages. It is the responsibility of the application to +overwrite it as needed. A state variable for different states assigned +to different colors is recommended by the author. The package +log is useful for this.

+
::ftp::VERBOSE
+

A state variable controlling the output of the package. Setting +::ftp::VERBOSE to "1" forces the package to show all responses +from a remote server. The default value is "0".

+
::ftp::DEBUG
+

A state variable controlling the output of ftp. Setting +::ftp::DEBUG to "1" enables debugging and forces the package to +show all return codes, states, state changes and "real" ftp +commands. The default value is "0".

+
+
+

BUGS

+

The correct execution of many commands depends upon the proper +behavior by the remote server, network and router configuration.

+

An update command placed in the procedure ::ftp::DisplayMsg may +run into persistent errors or infinite loops. The solution to this +problem is to use update idletasks instead of update.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ftp/ftp_geturl.html Index: embedded/www/tcllib/files/modules/ftp/ftp_geturl.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ftp/ftp_geturl.html @@ -0,0 +1,174 @@ + + +ftp::geturl - ftp client + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ftp::geturl(n) 0.2.1 tcllib "ftp client"

+

Name

+

ftp::geturl - Uri handler for ftp urls

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require ftp::geturl ?0.2.1?
    • +
+ +
+
+

Description

+

This package provides a command which wraps around the client side of +the ftp protocol provided by package ftp to allow the +retrieval of urls using the ftp schema.

+
+

API

+
+
::ftp::geturl url
+

This command can be used by the generic command ::uri::geturl +(See package uri) to retrieve the contents of ftp +urls. Internally it uses the commands of the package ftp to +fulfill the request.

+

The contents of a ftp url are defined as follows:

+
+
file
+

The contents of the specified file itself.

+
directory
+

A listing of the contents of the directory in key value notation where +the file name is the key and its attributes the associated value.

+
link
+

The attributes of the link, including the path it refers to.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ftpd/ftpd.html Index: embedded/www/tcllib/files/modules/ftpd/ftpd.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ftpd/ftpd.html @@ -0,0 +1,342 @@ + + +ftpd - Tcl FTP Server Package + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ftpd(n) 1.2.6 tcllib "Tcl FTP Server Package"

+

Name

+

ftpd - Tcl FTP server implementation

+
+ + +

Description

+

The ftpd package provides a simple Tcl-only server library +for the FTP protocol as specified in +RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). +It works by listening on the standard FTP socket. Most server errors +are returned as error messages with the appropriate code attached to +them. Since the server code for the ftp daemon is executed in the +event loop, it is possible that a +bgerror will be thrown on the server if there are problems with +the code in the module.

+
+

COMMANDS

+
+
::ftpd::server ?myaddr?
+

Open a listening socket to listen to and accept ftp connections. +myaddr is an optional argument. myaddr is the domain-style name +or numerical IP address of the client-side network interface to use +for the connection.

+
::ftpd::config ?option value? ?option value ...?
+

The value is always the name of the command to call as the +callback. The option specifies which callback should be configured. +See section CALLBACKS for descriptions of the arguments and +return values for each of the callbacks.

+
+
-authIpCmd proc
+

Callback to authenticate new connections based on the ip-address of +the peer.

+
-authUsrCmd proc
+

Callback to authenticate new connections based on the user logging in +(and the users password).

+
-authFileCmd proc
+

Callback to accept or deny a users access to read and write to a +specific path or file.

+
-logCmd proc
+

Callback for log information generated by the FTP engine.

+
-fsCmd proc
+

Callback to connect the engine to the filesystem it operates on.

+
-closeCmd proc
+

Callback to be called when a connection is closed. This allows the +embedding application to perform its own cleanup operations.

+
-xferDoneCmd proc
+

Callback for transfer completion notification. In other words, it is +called whenever a transfer of data to or from the client has +completed.

+
+
+
+

CALLBACKS

+
+
authIpCmd callback
+

The authIpCmd receives the ip-address of the peer attempting to +connect to the ftp server as its argument. It returns a 1 to allow +users from the specified IP to attempt to login and a 0 to reject the +login attempt from the specified IP.

+
authUsrCmd callback
+

The authUsrCmd receives the username and password as its two +arguments. It returns a 1 to accept the attempted login to the ftpd +and a 0 to reject the attempted login.

+
authFileCmd callback
+

The authFileCmd receives the user (that is currently logged in), the +path or filename that is about to be read or written, and +read or write as its three arguments. It returns a +1 to allow the path or filename to be read or written, and a 0 to +reject the attempted read or write with a permissions error code.

+
logCmd callback
+

The logCmd receives a severity and a message as its two arguments. +The severities used within the ftpd package are note, +debug, and error. The logCmd doesn't return +anything.

+
fsCmd callback
+

The fsCmd receives a subcommand, a filename or path, and optional +additional arguments (depending on the subcommand).

+

The subcommands supported by the fsCmd are:

+
+
fsCmd append path
+

The append subcommand receives the filename to append to as its +argument. It returns a writable tcl channel as its return value.

+
fsCmd delete path channel
+

The delete subcommand receives the filename to delete, and a channel +to write to as its two arguments. The file specified is deleted and +the appropriate ftp message is written to the channel that is passed +as the second argument. The delete subcommand returns nothing.

+
fsCmd dlist path style channel
+

The dlist subcommand receives the path that it should list the files +that are in, the style in which the files should be listed which is +either nlst or list, and a channel to write to as +its three arguments. The files in the specified path are printed to +the specified channel one per line. If the style is nlst +only the name of the file is printed to the channel. If the style is +list then the file permissions, number of links to the file, +the name of the user that owns the file, the name of the group that +owns the file, the size (in bytes) of the file, the modify time of the +file, and the filename are printed out to the channel in a formatted +space separated format. The dlist subcommand returns +nothing.

+
fsCmd exists path
+

The exists subcommand receives the name of a file to check the +existence of as its only argument. The exists subcommand returns a 1 +if the path specified exists and the path is not a directory.

+
fsCmd mkdir path channel
+

The mkdir subcommand receives the path of a directory to create and a +channel to write to as its two arguments. The mkdir subcommand +creates the specified directory if necessary and possible. The mkdir +subcommand then prints the appropriate success or failure message to +the channel. The mkdir subcommand returns nothing.

+
fsCmd mtime path channel
+

The mtime subcommand receives the path of a file to check the modify +time on and a channel as its two arguments. If the file exists the +mtime is printed to the channel in the proper FTP format, otherwise an +appropriate error message and code are printed to the channel. The +mtime subcommand returns nothing.

+
fsCmd permissions path
+

The permissions subcommand receives the path of a file to retrieve the +permissions of. The permissions subcommand returns the octal file +permissions of the specified file. The file is expected to exist.

+
fsCmd rename path newpath channel
+

The rename subcommand receives the path of the current file, the new +file path, and a channel to write to as its three arguments. The +rename subcommand renames the current file to the new file path if the +path to the new file exists, and then prints out the appropriate +message to the channel. If the new file path doesn't exist the +appropriate error message is printed to the channel. The rename +subcommand returns nothing.

+
fsCmd retr path
+

The retr subcommand receives the path of a file to read as its only +argument. The retr subcommand returns a readable channel that the +specified file can be read from.

+
fsCmd rmdir path channel
+

The rmdir subcommand receives the path of a directory to remove and a +channel to write to as its two arguments. The rmdir subcommand +removes the specified directory (if possible) and prints the +appropriate message to the channel (which may be an error if the +specified directory does not exist or is not empty). The rmdir +subcommand returns nothing.

+
fsCmd size path channel
+

The size subcommand receives the path of a file to get the size (in +bytes) of and a channel to write to as its two arguments. The size +subcommand prints the appropriate code and the size of the file if the +specified path is a file, otherwise an appropriate error code and +message are printed to the channel. The size subcommand returns +nothing.

+
fsCmd store path
+

The store subcommand receives the path of a file to write as its only +argument. The store subcommand returns a writable channel.

+
+
closeCmd
+

The closeCmd receives no arguments when it is invoked, and any +return value it may generate is discarded.

+
xferDoneCmd sock sock2 file bytes filename err
+

The xferDoneCmd receives six arguments when invoked. These are, +in this order, the channel handle of the control socket for the +connection, the channel handle of the data socket used for the +transfer (already closed), the handle of the channel containing the +transfered file, the number of bytes transfered, the path of the file +which was transfered, and a (possibly empty) error message. +Any return value it may generate is discarded.

+
+
+

VARIABLES

+
+
::ftpd::cwd
+

The current working directory for a session when someone first +connects to the FTPD or when the REIN ftp command is received.

+
::ftpd::contact
+

The e-mail address of the person that is the contact for the ftp +server. This address is printed out as part of the response to the +FTP HELP command.

+
::ftpd::port
+

The port that the ftp server should listen on. +If port is specified as zero, the operating system will allocate an +unused port for use as a server socket; afterwards, the variable will +contain the port number that was allocated.

+
::ftpd::welcome
+

The message that is printed out when the user first connects to the +ftp server.

+
::ftpd::CurrentSocket
+

Accessible to all callbacks and all filesystem commands (which are a +special form of callback) and contains the handle of the socket +channel which was active when the callback was invoked.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftpd of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/cfront.html Index: embedded/www/tcllib/files/modules/fumagic/cfront.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fumagic/cfront.html @@ -0,0 +1,186 @@ + + +fileutil::magic::cfront - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::magic::cfront(n) 1.0 tcllib "file utilities"

+

Name

+

fileutil::magic::cfront - Generator core for compiler of magic(5) files

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::magic::cfront ?1.0?
    • +
  • package require fileutil::magic::cgen ?1.0?
    • +
  • package require fileutil::magic::rt ?1.0?
    • +
  • package require struct::list
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides the frontend of a compiler of magic(5) files +into recognizers based on the fileutil::magic::rt recognizer +runtime package. For the generator backed used by this compiler see +the package fileutil::magic::cgen.

+
+

COMMANDS

+
+
::fileutil::magic::cfront::compile path...
+

This command takes the paths of one or more files and directories and +compiles all the files, and the files in all the directories into a +single recognizer for all the file types specified in these files.

+

All the files have to be in the format specified by magic(5).

+

The result of the command is a Tcl script containing the generated +recognizer.

+
::fileutil::magic::cfront::procdef procname path...
+

This command behaves like ::fileutil::magic::cfront::compile +with regard to the specified path arguments, then wraps the resulting +recognizer script into a procedure named procname, puts code +setting up the namespace of procname in front, and returns the +resulting script.

+
::fileutil::magic::cfront::install path...
+

This command uses ::fileutil::magic::cfront::procdef to compile +each of the paths into a recognizer procedure and installs the result +in the current interpreter.

+

The name of each new procedure is derived from the name of the +file/directory used in its creation, with file/directory "FOO" +causing the creation of procedure ::fileutil::magic::/FOO::run.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/cgen.html Index: embedded/www/tcllib/files/modules/fumagic/cgen.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fumagic/cgen.html @@ -0,0 +1,182 @@ + + +fileutil::magic::cgen - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::magic::cgen(n) 1.0 tcllib "file utilities"

+

Name

+

fileutil::magic::cgen - Generator core for compiler of magic(5) files

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::magic::cgen ?1.0?
    • +
  • package require fileutil::magic::rt ?1.0?
    • +
  • package require struct::tree
    • +
  • package require struct::list
    • +
+ +
+
+

Description

+

This package provides the generator backend for a compiler of magic(5) +files into recognizers based on the fileutil::magic::rt +recognizer runtime package. For the compiler frontend using this +generator see the package fileutil::magic::cfront.

+
+

COMMANDS

+
+
::fileutil::magic::cgen::2tree script
+

This command converts the recognizer specified by the script +into a tree and returns the object command of that tree as its +result. It uses the package struct::tree for the tree.

+

The script is in the format specified by magic(5).

+
::fileutil::magic::cgen::treedump tree
+

This command takes a tree as generated by +::fileutil::magic::cgen::2tree and returns a string encoding the +tree for human consumption, to aid in debugging.

+
::fileutil::magic::cgen::treegen tree node
+

This command takes a tree as generated by +::fileutil::magic::cgen::2tree and returns a Tcl script, the +recognizer for the file types represented by the sub-tree rooted at +the node. +The generated script makes extensive use of the commands provided by +the recognizer runtime package fileutil::magic::rt to +perform its duties.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/filetypes.html Index: embedded/www/tcllib/files/modules/fumagic/filetypes.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fumagic/filetypes.html @@ -0,0 +1,174 @@ + + +fileutil::magic::filetype - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::magic::filetype(n) 1.0.2 tcllib "file utilities"

+

Name

+

fileutil::magic::filetype - Procedures implementing file-type recognition

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::magic::filetype ?1.0.2?
    • +
+ +
+
+

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 276 Kilobyte of +generated Tcl code.

+
+
::fileutil::magic::filetype filename
+

This command is similar to the command fileutil::fileType.

+

The output of the command for the specified file is a string +describing the type of the file.

+

This list will be empty if the type of the file is not recognized.

+
+
+

REFERENCES

+
    +

  1. File(1) sources +This site contains the current sources for the file command, including +the magic definitions used by it. The latter were used by us to +generate this recognizer.

    2. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/mimetypes.html Index: embedded/www/tcllib/files/modules/fumagic/mimetypes.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fumagic/mimetypes.html @@ -0,0 +1,173 @@ + + +fileutil::magic::mimetype - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::magic::mimetype(n) 1.0.2 tcllib "file utilities"

+

Name

+

fileutil::magic::mimetype - Procedures implementing mime-type recognition

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::magic::mimetype ?1.0.2?
    • +
+ +
+
+

Description

+

This package provides a command for the recognition of file types in +pure Tcl. The output is standardized to mime-types.

+

The core part of the recognizer was generated from a "magic(5)" file +containing the checks to perform to recognize files, and associated +mime-types.

+
+
::fileutil::magic::mimetype filename
+

This command is similar to the command fileutil::fileType.

+

The output of the command for the specified file is not a list of +attributes describing the type of the file, but a list of standard +mime-types the file may have.

+

This list will be empty if the type of the file is not recognized.

+
+
+

REFERENCES

+
    +

  1. File(1) sources +This site contains the current sources for the file command, including +the magic definitions used by it. The latter were used by us to +generate this recognizer.

    2. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/rtcore.html Index: embedded/www/tcllib/files/modules/fumagic/rtcore.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/fumagic/rtcore.html @@ -0,0 +1,322 @@ + + +fileutil::magic::rt - file utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

fileutil::magic::rt(n) 1.0 tcllib "file utilities"

+

Name

+

fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl

+
+ + +

Description

+

This package provides the runtime core for file type recognition +engines written in pure Tcl and is thus used by all other packages in +this module, i.e. the two frontend packages +fileutil::magic::mimetypes and +fileutil::magic::filetypes, and the two engine compiler +packages fileutil::magic::cgen and +fileutil::magic::cfront.

+
+

COMMANDS

+
+
::fileutil::magic::rt::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 atlevel 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 level atlevel, for later use by +::fileutil::magic::rt::R.

+
::fileutil::magic::rt::Nx atlevel 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 level atlevel, 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 atlevel 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 level atlevel, 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.

+
+
+

NUMERIC TYPES

+
+
byte
+

8-bit integer

+
short
+

16-bit integer, stored in native endianess

+
beshort
+

see above, stored in big endian

+
leshort
+

see above, stored in small/little endian

+
long
+

32-bit integer, stored in native endianess

+
belong
+

see above, stored in big endian

+
lelong
+

see above, stored in small/little endian

+
+

All of the types above exit in an unsigned form as well. The type +names are the same, with the character "u" added as prefix.

+
+
date
+

32-bit integer timestamp, stored in native endianess

+
bedate
+

see above, stored in big endian

+
ledate
+

see above, stored in small/little endian

+
ldate
+

32-bit integer timestamp, stored in native endianess

+
beldate
+

see above, stored in big endian

+
leldate
+

see above, stored in small/little endian

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/generator/generator.html Index: embedded/www/tcllib/files/modules/generator/generator.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/generator/generator.html @@ -0,0 +1,510 @@ + +generator - Tcl Generator Commands + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

generator(n) 0.1 tcllib "Tcl Generator Commands"

+

Name

+

generator - Procedures for creating and using generators.

+
+ + +

Description

+

The generator package provides commands to define and iterate over +generator expressions. A generator is a command that returns a sequence +of values. However, unlike an ordinary command that returns a list, a +generator yields each value and then suspends, allowing subsequent +values to be fetched on-demand. As such, generators can be used to efficiently +iterate over a set of values, without having to generate all answers in-memory. +Generators can be used to iterate over elements of a data structure, or rows +in the result set of a database query, or to decouple producer/consumer software +designs such as parsers and tokenizers, or to implement sophisticated custom +control strategies such as backtracking search. Generators reduce the need to +implement custom control structures, as many such structures can be recast as +generators, leading to both a simpler implementation and a more standardised +interface. The generator mechanism is built on top of the Tcl 8.6 coroutine +mechanism.

+

The package exports a single ensemble command, generator. All +functionality is provided as subcommands of this command. The core subcommands +of the package are define, yield, and foreach. The +define command works like Tcl's proc command, but creates a +generator procedure; that is, a procedure that returns a generator when called. +The generator itself is a command that can be called multiple times: each time +it returns the next value in the generated series. When the +series has been exhausted, the generator command returns an empty list and then +destroys itself. Rather than manually call a generator, however, the package +also provides a flexible foreach command that loops through the values of +one or more generators. This loop construct mimicks the functionality of the +built-in Tcl foreach command, including handling multiple return values +and looping over multiple generators at once. Writing a generator is also a +simple task, much like writing a normal procedure: simply use the define +command to define the generator, and then call yield instead of return. +For example, we can define a generator for looping through the integers +in a particular range:

+
+    generator define range {n m} {
+        for {set i $n} {$i <= $m} {incr i} { generator yield $i }
+    }
+    generator foreach x [range 1 10] {
+        puts "x = $x"
+    }
+
+

The above example will print the numbers from 1 to 10 in sequence, as you would +expect. The difference from a normal loop over a list is that the numbers are +only generated as they are needed. If we insert a break into the loop then any +remaining numbers in the sequence would never be generated. To illustrate, we +can define a generator that produces the sequence of natural numbers: an +infinite series. A normal procedure would never return trying to produce this +series as a list. By using a generator we only have to generate those values +which are actually used:

+
+    generator define nats {} {
+        while 1 { generator yield [incr nat] }
+    }
+    generator foreach n [nats] {
+        if {$n > 100} { break }
+    }
+
+
+

COMMANDS

+
+
generator define name params body
+

Creates a new generator procedure. The arguments to the command are identical to +those for proc: a name, a list of parameters, and a body. The +parameter list format is identical to a procedure. In particular, default values +and the ?args? syntax can be used as usual. Each time the resulting +generator procedure is called it creates a new generator command (coroutine) +that will yield a list of values on each call. Each result from a generator is +guaranteed to be a non-empty list of values. When a generator is exhausted it +returns an empty list and then destroys itself to free up resources. It is an +error to attempt to call an exhausted generator as the command no longer exists.

+
generator yield arg ?args..?
+

Used in the definition of a generator, this command returns the next set of +values to the consumer. Once the yield command has been called the +generator will suspend to allow the consumer to process that value. When the +next value is requested, the generator will resume as if the yield command had +just returned, and can continue processing to yield the next result. The +yield command must be called with at least one argument, but can be called with +multiple arguments, in which case this is equivalent to calling yield +once for each argument.

+
generator foreach varList generator varList generator ?...? body
+

Loops through one or more generators, assigning the next values to variables and +then executing the loop body. Works much like the built-in foreach +command, but working with generators rather than lists. Multiple generators can +be iterated over in parallel, and multiple results can be retrieved from a +single generator at once. Like the built-in foreach, the loop will +continue until all of the generators have been exhausted: variables for +generators that are exhausted early will be set to the empty string.

+

The foreach command will automatically clean-up all of the generators +at the end of the loop, regardless of whether the loop terminated early or not. +This behaviour is provided as a convenience to avoid having to explicitly +clean up a generator in the usual cases. Generators can however be destroyed +before the end of the loop, in which case the loop will continue as normal until +all the other generators have been destroyed or exhausted.

+

The foreach command does not take a snapshot of the generator. Any +changes in the state of the generator made inside the loop or by other code will +affect the state of the loop. In particular, if the code in the loop invokes the +generator to manually retrieve the next element, this element will then be +excluded from the loop, and the next iteration will continue from the element +after that one. Care should be taken to avoid concurrent updates to generators +unless this behaviour is required (e.g., in argument processing).

+
generator next generator ?varName..?
+

Manually retrieves the next values from a generator. One value is retrieved for +each variable supplied and assigned to the corresponding variable. If the +generator becomes exhausted at any time then any remaining variables are set to +the empty string.

+
generator exists generator
+

Returns 1 if the generator (still) exists, or 0 otherwise.

+
generator names
+

Returns a list of all currently existing generator commands.

+
generator destroy ?generator..?
+

Destroys one or more generators, freeing any associated resources.

+
generator finally cmd ?arg..?
+

Used in the definition of a generator procedure, this command arranges for a +resource to be cleaned up whenever the generator is destroyed, either explicitly +or implicitly when the generator is exhausted. This command can be used like a +finally block in the try command, except that it is tied to the +life-cycle of the generator rather than to a particular scope. For example, if +we create a generator to iterate over the lines in a text file, we can use +finally to ensure that the file is closed whenever the generator is +destroyed:

+
+    generator define lines file {
+        set in [open $file]
+        # Ensure file is always closed
+        generator finally close $in
+        while {[gets $in line] >= 0} {
+            generator yield $line
+        }
+    }
+    generator foreach line [lines /etc/passwd] {
+        puts "[incr count]: $line"
+        if {$count > 10} { break }
+    }
+    # File will be closed even on early exit
+
+

If you create a generator that consumes another generator (such as the standard +map and filter generators defined later), then you should use +a finally command to ensure that this generator is destroyed when its +parent is. For example, the map generator is defined as follows:

+
+    generator define map {f xs} {
+        generator finally generator destroy $xs
+        generator foreach x $xs { generator yield [{*}$f $x] }
+    }
+
+
+
generator from format value
+

Creates a generator from a data structure. Currently, supported formats are +list, dict, or string. The list format yields each +element in turn. For dictionaries, each key and value are yielded separately. +Finally, strings are yielded a character at a time.

+
generator to format generator
+

Converts a generator into a data structure. This is the reverse operation of the +from command, and supports the same data structures. The two operations +obey the following identity laws (where = is interpreted +appropriately):

+
+    [generator to $fmt [generator from $fmt $value]] = $value
+    [generator from $fmt [generator to $fmt $gen]]   = $gen
+
+
+
+
+

PRELUDE

+

The following commands are provided as a standard library of generator +combinators and functions that perform convenience operations on generators. The +functions in this section are loosely modelled on the equivalent functions from +the Haskell Prelude. Warning: most of the functions in this prelude +destroy any generator arguments they are passed as a side-effect. If you want to +have persistent generators, see the streams library.

+
+
generator map function generator
+

Apply a function to every element of a generator, returning a new generator of +the results. This is the classic map function from functional programming, +applied to generators. For example, we can generate all the square numbers using +the following code (where nats is defined as earlier):

+
+    proc square x { expr {$x * $x} }
+    generator foreach n [generator map square [nats]] {
+        puts "n = $n"
+        if {$n > 1000} { break }
+    }
+
+
+
generator filter predicate generator
+

Another classic functional programming gem. This command returns a generator +that yields only those items from the argument generator that satisfy the +predicate (boolean function). For example, if we had a generator employees +that returned a stream of dictionaries representing people, we could filter all +those whose salaries are above 100,000 dollars (or whichever currency you prefer) +using a simple filter:

+
+    proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
+    set fat-cats [generator filter {salary> 100000} $employees]
+
+
+
generator reduce function zero generator
+

This is the classic left-fold operation. This command takes a function, an +initial value, and a generator of values. For each element in the generator it +applies the function to the current accumulator value (the zero argument +initially) and that element, and then uses the result as the new accumulator +value. This process is repeated through the entire generator (eagerly) and the +final accumulator value is then returned. If we consider the function to be a +binary operator, and the zero argument to be the left identity element of that +operation, then we can consider the reduce command as folding +the operator between each successive pair of values in the generator in a +left-associative fashion. For example, the sum of a sequence of numbers can be +calculated by folding a + operator between them, with 0 as the identity:

+
+    # sum xs          = reduce + 0 xs
+    # sum [range 1 5] = reduce + 0 [range 1 5]
+    #                 = reduce + [+ 0 1] [range 2 5]
+    #                 = reduce + [+ 1 2] [range 3 5]
+    #                 = ...
+    #                 = reduce + [+ 10 5] <empty>
+    #                 = ((((0+1)+2)+3)+4)+5
+    #                 = 15
+    proc + {a b} { expr {$a + $b} }
+    proc sum gen { generator reduce + 0 $gen }
+    puts [sum [range 1 10]]
+
+

The reduce operation is an extremely useful one, and a great variety of +different operations can be defined using it. For example, we can define a +factorial function as the product of a range using generators. This definition +is both very clear and also quite efficient (in both memory and running time):

+
+    proc * {x y} { expr {$x * $y} }
+    proc prod gen { generator reduce * 0 $gen }
+    proc fac n { prod [range 1 $n] }
+
+

However, while the reduce operation is efficient for finite generators, +care should be taken not to apply it to an infinite generator, as this will +result in an infinite loop:

+
+    sum [nats]; # Never returns
+
+
+
generator foldl function zero generator
+

This is an alias for the reduce command.

+
generator foldr function zero generator
+

This is the right-associative version of reduce. This operation is +generally inefficient, as the entire generator needs to be evaluated into memory +(as a list) before the reduction can commence. In an eagerly evaluated language +like Tcl, this operation has limited use, and should be avoided if possible.

+
generator all predicate generator
+

Returns true if all elements of the generator satisfy the given predicate.

+
generator and generator
+

Returns true if all elements of the generator are true (i.e., takes the logical +conjunction of the elements).

+
generator any generator
+

Returns true if any of the elements of the generator are true (i.e., logical +disjunction).

+
generator concat generator ?generator..?
+

Returns a generator which is the concatenation of each of the argument +generators.

+
generator concatMap function generator
+

Given a function which maps a value to a series of values, and a generator of +values of that type, returns a generator of all of the results in one flat +series. Equivalent to concat applied to the result of map.

+
generator drop n generator
+

Removes the given number of elements from the front of the generator and returns +the resulting generator with those elements removed.

+
generator dropWhile predicate generator
+

Removes all elements from the front of the generator that satisfy the predicate.

+
generator contains element generator
+

Returns true if the generator contains the given element. Note that this will +destroy the generator!

+
generator foldl1 function generator
+

A version of foldl that takes the zero argument from the first +element of the generator. Therefore this function is only valid on non-empty +generators.

+
generator foldli function zero generator
+

A version of foldl that supplies the integer index of each element as +the first argument to the function. The first element in the generator at this +point is given index 0.

+
generator foldri function zero generator
+

Right-associative version of foldli.

+
generator head generator
+

Returns the first element of the generator.

+
generator tail generator
+

Removes the first element of the generator, returning the rest.

+
generator init generator
+

Returns a new generator consisting of all elements except the last of the +argument generator.

+
generator takeList n generator
+

Returns the next n elements of the generator as a list. If not enough +elements are left in the generator, then just the remaining elements are +returned.

+
generator take n generator
+

Returns the next n elements of the generator as a new generator. The old +generator is destroyed.

+
generator iterate function init
+

Returns an infinite generator formed by repeatedly applying the function to the +initial argument. For example, the Fibonacci numbers can be defined as follows:

+
+    proc fst pair { lindex $pair 0 }
+    proc snd pair { lindex $pair 1 }
+    proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
+    proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }
+
+
+
generator last generator
+

Returns the last element of the generator (if it exists).

+
generator length generator
+

Returns the length of the generator, destroying it in the process.

+
generator or predicate generator
+

Returns 1 if any of the elements of the generator satisfy the predicate.

+
generator product generator
+

Returns the product of the numbers in a generator.

+
generator repeat n value..
+

Returns a generator that consists of n copies of the given elements. The +special value Inf can be used to generate an infinite sequence.

+
generator sum generator
+

Returns the sum of the values in the generator.

+
generator takeWhile predicate generator
+

Returns a generator of the first elements in the argument generator that satisfy +the predicate.

+
generator splitWhen predicate generator
+

Splits the generator into lists of elements using the predicate to identify +delimiters. The resulting lists are returned as a generator. Elements matching +the delimiter predicate are discarded. For example, to split up a generator +using the string "|" as a delimiter:

+
+    set xs [generator from list {a | b | c}]
+    generator split {string equal "|"} $xs ;# returns a then b then c
+
+
+
generator scanl function zero generator
+

Similar to foldl, but returns a generator of all of the intermediate +values for the accumulator argument. The final element of this generator is +equivalent to foldl called on the same arguments.

+
+
+

BUGS, IDEAS, FEEDBACK

+

Please report any errors in this document, or in the package it describes, to +Neil Madden.

+
+ +
ADDED embedded/www/tcllib/files/modules/gpx/gpx.html Index: embedded/www/tcllib/files/modules/gpx/gpx.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/gpx/gpx.html @@ -0,0 +1,271 @@ + + +gpx - GPS eXchange Format (GPX) + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)"

+

Name

+

gpx - Extracts waypoints, tracks and routes from GPX files

+
+ + +

Description

+

This module parses and extracts waypoints, tracks, routes and +metadata from a GPX (GPS eXchange) file. Both GPX version 1.0 +and 1.1 are supported.

+
+

COMMANDS

+
+
::gpx::Create gpxFilename ?rawXML?
+

The ::gpx::Create is the first command called to process GPX +data. It takes the GPX data from either the rawXML +parameter if present or from the contents of gpxFilename, +and parses it using tdom. It returns a token value that is used +by all the other commands.

+
::gpx::Cleanup token
+

This procedure cleans up resources associated with token. +It is strongly recommended that you call this +function after you are done with a given GPX file. +Not doing so will result in memory not being freed, and +if your app calls ::gpx::Create enough times, the +memory leak could cause a performance hit...or worse.

+
::gpx::GetGPXMetadata token
+

This procedure returns a dictionary of the metadata +associated with the GPX data identified by token. +The format of the metadata dictionary is described +below, but keys version and creator +will always be present.

+
::gpx::GetWaypointCount token
+

This procedure returns the number of waypoints defined in the GPX +data identified by token.

+
::gpx::GetAllWaypoints token
+

This procedure returns the a list of waypoints defined in the GPX +data identified by token. The format of each waypoint item +is described below.

+
::gpx::GetTrackCount token
+

This procedure returns the number of tracks defined in the GPX +data identified by token.

+
::gpx::GetTrackMetadata token whichTrack
+

This procedure returns a dictionary of the metadata +associated track number whichTrack (1 based) in +the GPX data identified by token. +The format of the metadata dictionary is described below.

+
::gpx::GetTrackPoints token whichTrack
+

The procedure returns a list of track points comprising track +number whichTrack (1 based) in the GPX data identified by +token. The format of the metadata dictionary is described below.

+
::gpx::GetRouteCount token
+

This procedure returns the number of routes defined in the GPX +data identified by token.

+
::gpx::GetRouteMetadata token whichRoute
+

This procedure returns a dictionary of the metadata +associated route number whichRoute (1 based) in +the GPX data identified by token. +The format of the metadata dictionary is described below.

+
::gpx::GetRoutePoints token whichRoute
+

The procedure returns a list of route points comprising route +number whichRoute (1 based) in the GPX data identified by +token. The format of the metadata dictionary is described below.

+
+
+

DATA STRUCTURES

+
+
metadata dictionary
+

The metadata associated with either the GPX document, a +track, a route, a waypoint, a track point or route +point is returned in a dictionary. The keys of that +dictionary will be whatever optional GPX elements are +present. The value for each key depends on the GPX schema +for that element. For example, the value for a version +key will be a string, while for a link key will be +a sub-dictionary with keys href and optionally +text and type.

+
point item
+

Each item in a track or route list of points consists of +a list of three elements: latitude, longitude and +metadata dictionary. Latitude and longitude +are decimal numbers. The metadata dictionary format is +described above. For points in a track, typically there will +always be ele (elevation) and time metadata keys.

+
+
+

EXAMPLE

+
+% set token [::gpx::Create myGpxFile.gpx]
+% set version [dict get [::gpx::GetGPXMetadata $token] version]
+% set trackCnt [::gpx::GetTrackCount $token]
+% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
+% lassign $firstPoint lat lon ptMetadata
+% puts "first point in the first track is at $lat, $lon"
+% if {[dict exists $ptMetadata ele]} { 
+     puts "at elevation [dict get $ptMetadata ele] meters"
+  }
+% ::gpx::Cleanup $token
+
+
+

REFERENCES

+
    +

  1. GPX: the GPS Exchange Format + (http://www.topografix.com/gpx.asp)

    2. +

  2. GPX 1.1 Schema Documentation (http://www.topografix.com/GPX/1/1/)

    3. +

  3. GPX 1.0 Developer's Manual (http://www.topografix.com/gpx_manual.asp)

    4. +
+
+

AUTHOR

+

Keith Vetter

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category gpx of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_aycock/aycock.html Index: embedded/www/tcllib/files/modules/grammar_aycock/aycock.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_aycock/aycock.html @@ -0,0 +1,246 @@ + + +grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl"

+

Name

+

grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl

+
+ + +

Description

+

The grammar::aycock package +implements a parser generator for the class of parsers described +in John Aycock and R. Nigel Horspool. Practical Earley Parsing. +The Computer Journal, 45(6):620-630, 2002. +http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254

+
+

PROCEDURES

+

The grammar::aycock package exports the single procedure:

+
+
::aycock::parser grammar ?-verbose?
+

Generates a parser for the given grammar, and returns its +name. If the optional -verbose flag is given, dumps verbose +information relating to the generated parser to the standard output. +The returned parser is an object that accepts commands as shown in +OBJECT COMMAND below.

+
+
+

OBJECT COMMAND

+
+
parserName parse symList valList ?clientData?
+

Invokes a parser returned from ::aycock::parser. symList is +a list of grammar symbols representing the terminals in an input +string, and valList is a list of their semantic values. The +result is the semantic value of the entire string when parsed.

+
parserName destroy
+

Destroys a parser constructed by ::aycock::parser.

+
parserName terminals
+

Returns a list of terminal symbols that may be presented in the +symList argument to the parse object command.

+
parserName nonterminals
+

Returns a list of nonterminal symbols that were defined in the +parser's grammar.

+
parserName save
+

Returns a Tcl script that will reconstruct the parser without +needing all the mechanism of the parser generator at run time. +The reconstructed parser depends on a set of commands in the +package grammar::aycock::runtime, +which is also automatically loaded +when the grammar::aycock package is loaded.

+
+
+

DESCRIPTION

+

The grammar::aycock::parser command accepts a grammar expressed as +a Tcl list. The list must be structured as the concatenation of a set +of rules. Each rule comprises a variable number of +elements in the list:

+
    +

  • The name of the nonterminal symbol that the rule reduces.

    • +

  • The literal string, ::=

    • +

  • Zero or more names of terminal or nonterminal symbols that +comprise the right-hand-side of the rule.

    • +

  • Finally, a Tcl script to execute when the rule is reduced. +Within the given script, a variable called _ contains a list of +the semantic values of the symbols on the right-hand side. The value +returned by the script is expected to be the semantic value of the +left-hand side. If the clientData parameter was passed to the +parse method, it is available in a variable called +clientData. It is permissible for the script to be the empty +string. In this case, the semantic value of the rule will be the same +as the semantic value of the first symbol on the right-hand side. If +the right-hand side is also empty, the semantic value will be the +empty string.

    • +
+

Parsing is done with an Earley parser, which is not terribly efficient +in speed or memory consumption, but which deals effectively with +ambiguous grammars. For this reason, the grammar::aycock package is +perhaps best adapted to natural-language processing or the parsing of +extraordinarily complex languages in which ambiguity can be tolerated.

+
+

EXAMPLE

+

The following code demonstrates a trivial desk calculator, admitting +only +, * and parentheses as its operators. It also +shows the format in which the lexical analyzer is expected to present +terminal symbols to the parser.

+
+set p [aycock::parser {
+    start ::= E {}
+    E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}}
+    E ::= T {}
+    T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}}
+    T ::= F {}
+    F ::= NUMBER {}
+    F ::= ( E ) {lindex $_ 1}
+}]
+puts [$p parse {(  NUMBER +  NUMBER )  *  ( NUMBER +  NUMBER ) }  {{} 2      {} 3      {} {} {} 7     {} 1      {}}]
+$p destroy
+
+

The example, when run, prints 40.

+
+

KEYWORDS

+

Aycock, Earley, Horspool, parser, compiler

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html Index: embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html @@ -0,0 +1,208 @@ + + +grammar::fa::dacceptor - Finite automaton operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::dacceptor - Create and use deterministic acceptors

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit
    • +
  • package require struct::set
    • +
  • package require grammar::fa::dacceptor ?0.1.1?
    • +
+ +
+
+

Description

+

This package provides a class for acceptors constructed from +deterministic finite automatons (DFA). Acceptors are objects +which can be given a string of symbols and tell if the DFA they are +constructed from would accept that string. +For the actual creation of the DFAs the acceptors are based on we have +the packages grammar::fa and grammar::fa::op.

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa::dacceptor daName fa ?-any any?
+

Creates a new deterministic acceptor with an associated global Tcl command +whose name is daName. This command may be used to invoke various +operations on the acceptor. It has the following general form:

+
+
daName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section ACCEPTOR METHODS for more explanations.

+

The acceptor will be based on the deterministic finite automaton +stored in the object fa. It will keep a copy of the relevant +data of the FA in its own storage, in a form easy to use for its +purposes. This also means that changes made to the fa after the +construction of the acceptor will not influence the acceptor.

+

If any has been specified, then the acceptor will convert all +symbols in the input which are unknown to the base FA to that symbol +before proceeding with the processing.

+
+
+
+

ACCEPTOR METHODS

+

All acceptors provide the following methods for their manipulation:

+
+
daName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
daName accept? symbols
+

Takes the list of symbols and checks if the FA the acceptor is +based on would accept it. The result is a boolean value. True +is returned if the symbols are accepted, and False +otherwise. Note that bogus symbols in the input are either translated +to the any symbol (if specified), or cause the acceptance test +to simply fail. No errors will be thrown. The method will process only +just that prefix of the input which is enough to fully determine +(non-)acceptance.

+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/dexec.html Index: embedded/www/tcllib/files/modules/grammar_fa/dexec.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_fa/dexec.html @@ -0,0 +1,265 @@ + + +grammar::fa::dexec - Finite automaton operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::dexec - Execute deterministic finite automatons

+
+ + +

Description

+

This package provides a class for executors constructed from +deterministic finite automatons (DFA). Executors are objects +which are given a string of symbols in a piecemal fashion, perform +state transitions and report back when they enter a final state, or +find an error in the input. +For the actual creation of the DFAs the executors are based on we have +the packages grammar::fa and grammar::fa::op.

+

The objects follow a push model. Symbols are pushed into the executor, +and when something important happens, i.e. error occurs, a state transition, +or a final state is entered this will be reported via the callback +specified via the option -command. Note that conversion of +this into a pull model where the environment retrieves messages from +the object and the object uses a callback to ask for more symbols is +a trivial thing.

+

Side note: +The acceptor objects provided by grammar::fa::dacceptor +could have been implemented on top of the executors provided here, but +were not, to get a bit more performance (we avoid a number of method +calls and the time required for their dispatch).

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?
+

Creates a new deterministic executor with an associated global Tcl +command whose name is daName. This command may be used to invoke +various operations on the executor. It has the following general form:

+
+
daName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section EXECUTOR METHODS for more +explanations.

+

The executor will be based on the deterministic finite automaton +stored in the object fa. It will keep a copy of the relevant +data of the FA in its own storage, in a form easy to use for its +purposes. This also means that changes made to the fa after the +construction of the executor will not influence the executor.

+

If any has been specified, then the executor will convert all +symbols in the input which are unknown to the base FA to that symbol +before proceeding with the processing.

+
+
+
+

EXECUTOR METHODS

+

All executors provide the following methods for their manipulation:

+
+
daName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
daName put symbol
+

Takes the current state of the executor and the symbol and +performs the appropriate state transition. Reports any errors +encountered via the command callback, as well as entering a final +state of the underlying FA.

+

When an error is reported all further invokations of put will +do nothing, until the error condition has been cleared via an +invokation of method reset.

+
daName reset
+

Unconditionally sets the executor into the start state of the +underlying FA. This also clears any error condition put may +have encountered.

+
daName state
+

Returns the current state of the underlying FA. This allow for +introspection without the need to pass data from the callback command.

+
+
+

EXECUTOR CALLBACK

+

The callback command cmdprefix given to an executor via the +option -command will be executed by the object at the global +level, using the syntax described below. Note that cmdprefix is +not simply the name of a command, but a full command prefix. In other +words it may contain additional fixed argument words beyond the +command word.

+
+
cmdprefix error code message
+

The executor has encountered an error, and message contains a +human-readable text explaining the nature of the problem. +The code on the other hand is a fixed machine-readable text. +The following error codes can be generated by executor objects.

+
+
BADSYM
+

An unknown symbol was found in the input. This can happen if and only +if no -any symbol was specified.

+
BADTRANS
+

The underlying FA has no transition for the current combination of +input symbol and state. In other words, the executor was not able to +compute a new state for this combination.

+
+
cmdprefix final stateid
+

The executor has entered the final state stateid.

+
cmdprefix reset
+

The executor was reset.

+
cmdprefix state stateid
+

The FA changed state due to a transition. stateid is the new state.

+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/fa.html Index: embedded/www/tcllib/files/modules/grammar_fa/fa.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_fa/fa.html @@ -0,0 +1,628 @@ + + +grammar::fa - Finite automaton operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa - Create and manipulate finite automatons

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit 1.3
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require grammar::fa::op ?0.2?
    • +
  • package require grammar::fa ?0.4?
    • +
+ +
+
+

Description

+

This package provides a container class for +finite automatons (Short: FA). +It allows the incremental definition of the automaton, its +manipulation and querying of the definition. +While the package provides complex operations on the automaton +(via package grammar::fa::op), it does not have the +ability to execute a definition for a stream of symbols. +Use the packages +grammar::fa::dacceptor and +grammar::fa::dexec for that. +Another package related to this is grammar::fa::compiler. It +turns a FA into an executor class which has the definition of the FA +hardwired into it. The output of this package is configurable to suit +a large number of different implementation languages and paradigms.

+

For more information about what a finite automaton is see section +FINITE AUTOMATONS.

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa faName ?=|:=|<--|as|deserialize src|fromRegex re ?over??
+

Creates a new finite automaton with an associated global Tcl command +whose name is faName. This command may be used to invoke various +operations on the automaton. It has the following general form:

+
+
faName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section FA METHODS for more explanations. The +new automaton will be empty if no src is specified. Otherwise +it will contain a copy of the definition contained in the src. +The src has to be a FA object reference for all operators except +deserialize and fromRegex. The deserialize +operator requires src to be the serialization of a FA instead, +and fromRegex takes a regular expression in the form a of a +syntax tree. See ::grammar::fa::op::fromRegex for more detail on +that.

+
+
+
+

FA METHODS

+

All automatons provide the following methods for their manipulation:

+
+
faName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
faName clear
+

Clears out the definition of the automaton contained in faName, +but does not destroy the object.

+
faName = srcFA
+

Assigns the contents of the automaton contained +in srcFA to faName, overwriting any +existing definition. +This is the assignment operator for automatons. It copies the +automaton contained in the FA object srcFA over the automaton +definition in faName. The old contents of faName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    faName deserialize [srcFA serialize]
+
+
+
faName --> dstFA
+

This is the reverse assignment operator for automatons. It copies the +automation contained in the object faName over the automaton +definition in the object dstFA. +The old contents of dstFA are deleted by this operation.

+

This operation is in effect equivalent to

+
+    dstFA deserialize [faName serialize]
+
+
+
faName serialize
+

This method serializes the automaton stored in faName. In other +words it returns a tcl value completely describing that +automaton. +This allows, for example, the transfer of automatons over arbitrary +channels, persistence, etc. +This method is also the basis for both the copy constructor and the +assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the grammar::fa interface. This is what +will enable us to copy automatons between different implementations of +the same interface.

+

The result is a list of three elements with the following structure:

+
    +

  1. The constant string grammar::fa.

    2. +

  2. A list containing the names of all known input symbols. The order of +elements in this list is not relevant.

    3. +

  3. The last item in the list is a dictionary, however the order of the +keys is important as well. The keys are the states of the serialized +FA, and their order is the order in which to create the states when +deserializing. This is relevant to preserve the order relationship +between states.

    +

    The value of each dictionary entry is a list of three elements +describing the state in more detail.

    +
      +

    1. A boolean flag. If its value is true then the state is a +start state, otherwise it is not.

      2. +

    2. A boolean flag. If its value is true then the state is a +final state, otherwise it is not.

      3. +

    3. The last element is a dictionary describing the transitions for the +state. The keys are symbols (or the empty string), and the values are +sets of successor states.

      4. +
    +
    4. +
+

Assuming the following FA (which describes the life of a truck driver +in a very simple way :)

+
+    Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
+    (...) is the start state.
+
+

a possible serialization is

+
+    grammar::fa \\
+    {yellow red green red/yellow} \\
+    {Drive     {0 0 {yellow     Brake}} \\
+     Brake     {0 0 {red        Stop}} \\
+     Stop      {1 0 {red/yellow Attention}} \\
+     Attention {0 0 {green      Drive}}}
+
+

A possible one, because I did not care about creation order here

+
faName deserialize serialization
+

This is the complement to serialize. It replaces the +automaton definition in faName with the automaton described by +the serialization value. The old contents of faName are +deleted by this operation.

+
faName states
+

Returns the set of all states known to faName.

+
faName state add s1 ?s2 ...?
+

Adds the states s1, s2, et cetera to the FA definition in +faName. The operation will fail any of the new states is already +declared.

+
faName state delete s1 ?s2 ...?
+

Deletes the state s1, s2, et cetera, and all associated +information from the FA definition in faName. The latter means +that the information about in- or outbound transitions is deleted as +well. If the deleted state was a start or final state then this +information is invalidated as well. The operation will fail if the +state s is not known to the FA.

+
faName state exists s
+

A predicate. It tests whether the state s is known to the FA in +faName. +The result is a boolean value. It will be set to true if the +state s is known, and false otherwise.

+
faName state rename s snew
+

Renames the state s to snew. Fails if s is not a +known state. Also fails if snew is already known as a state.

+
faName startstates
+

Returns the set of states which are marked as start states, +also known as initial states. +See FINITE AUTOMATONS for explanations what this means.

+
faName start add s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as start (aka initial).

+
faName start remove s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as not start (aka not accepting).

+
faName start? s
+

A predicate. It tests if the state s in the FA faName is +start or not. +The result is a boolean value. It will be set to true if the +state s is start, and false otherwise.

+
faName start?set stateset
+

A predicate. It tests if the set of states stateset contains at +least one start state. They operation will fail if the set contains an +element which is not a known state. +The result is a boolean value. It will be set to true if a +start state is present in stateset, and false otherwise.

+
faName finalstates
+

Returns the set of states which are marked as final states, +also known as accepting states. +See FINITE AUTOMATONS for explanations what this means.

+
faName final add s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as final (aka accepting).

+
faName final remove s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as not final (aka not accepting).

+
faName final? s
+

A predicate. It tests if the state s in the FA faName is +final or not. +The result is a boolean value. It will be set to true if the +state s is final, and false otherwise.

+
faName final?set stateset
+

A predicate. It tests if the set of states stateset contains at +least one final state. They operation will fail if the set contains an +element which is not a known state. +The result is a boolean value. It will be set to true if a +final state is present in stateset, and false otherwise.

+
faName symbols
+

Returns the set of all symbols known to the FA faName.

+
faName symbols@ s ?d?
+

Returns the set of all symbols for which the state s has transitions. +If the empty symbol is present then s has epsilon transitions. If two +states are specified the result is the set of symbols which have transitions +from s to t. This set may be empty if there are no transitions +between the two specified states.

+
faName symbols@set stateset
+

Returns the set of all symbols for which at least one state in the set +of states stateset has transitions. +In other words, the union of [faName symbols@ s] +for all states s in stateset. +If the empty symbol is present then at least one state contained in +stateset has epsilon transitions.

+
faName symbol add sym1 ?sym2 ...?
+

Adds the symbols sym1, sym2, et cetera to the FA +definition in faName. The operation will fail any of the symbols +is already declared. The empty string is not allowed as a value for the symbols.

+
faName symbol delete sym1 ?sym2 ...?
+

Deletes the symbols sym1, sym2 et cetera, and all +associated information from the FA definition in faName. The +latter means that all transitions using the symbols are deleted as +well. The operation will fail if any of the symbols is not known to +the FA.

+
faName symbol rename sym newsym
+

Renames the symbol sym to newsym. Fails if sym is +not a known symbol. Also fails if newsym is already known as a +symbol.

+
faName symbol exists sym
+

A predicate. It tests whether the symbol sym is known to the FA +in faName. +The result is a boolean value. It will be set to true if the +symbol sym is known, and false otherwise.

+
faName next s sym ?--> next?
+

Define or query transition information.

+

If next is specified, then the method will add a transition from +the state s to the successor state next labeled with +the symbol sym to the FA contained in faName. The +operation will fail if s, or next are not known states, or +if sym is not a known symbol. An exception to the latter is that +sym is allowed to be the empty string. In that case the new +transition is an epsilon transition which will not consume +input when traversed. The operation will also fail if the combination +of (s, sym, and next) is already present in the FA.

+

If next was not specified, then the method will return +the set of states which can be reached from s through +a single transition labeled with symbol sym.

+
faName !next s sym ?--> next?
+

Remove one or more transitions from the Fa in faName.

+

If next was specified then the single transition from the state +s to the state next labeled with the symbol sym is +removed from the FA. Otherwise all transitions originating in +state s and labeled with the symbol sym will be removed.

+

The operation will fail if s and/or next are not known as +states. It will also fail if a non-empty sym is not known as +symbol. The empty string is acceptable, and allows the removal of +epsilon transitions.

+
faName nextset stateset sym
+

Returns the set of states which can be reached by a single transition +originating in a state in the set stateset and labeled with the +symbol sym.

+

In other words, this is the union of +[faName next s symbol] +for all states s in stateset.

+
faName is deterministic
+

A predicate. It tests whether the FA in faName is a +deterministic FA or not. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName is complete
+

A predicate. It tests whether the FA in faName is a complete FA +or not. A FA is complete if it has at least one transition per state +and symbol. This also means that a FA without symbols, or states is +also complete. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+

Note: When a FA has epsilon-transitions transitions over a symbol for +a state S can be indirect, i.e. not attached directly to S, but to a +state in the epsilon-closure of S. The symbols for such indirect +transitions count when computing completeness.

+
faName is useful
+

A predicate. It tests whether the FA in faName is an useful FA +or not. A FA is useful if all states are reachable +and useful. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName is epsilon-free
+

A predicate. It tests whether the FA in faName is an +epsilon-free FA or not. A FA is epsilon-free if it has no epsilon +transitions. This definition means that all deterministic FAs are +epsilon-free as well, and epsilon-freeness is a necessary +pre-condition for deterministic'ness. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName reachable_states
+

Returns the set of states which are reachable from a start state by +one or more transitions.

+
faName unreachable_states
+

Returns the set of states which are not reachable from any start state +by any number of transitions. This is

+
+	 [faName states] - [faName reachable_states]
+
+
+
faName reachable s
+

A predicate. It tests whether the state s in the FA faName +can be reached from a start state by one or more transitions. +The result is a boolean value. It will be set to true if the +state can be reached, and false otherwise.

+
faName useful_states
+

Returns the set of states which are able to reach a final state by +one or more transitions.

+
faName unuseful_states
+

Returns the set of states which are not able to reach a final state by +any number of transitions. This is

+
+	 [faName states] - [faName useful_states]
+
+
+
faName useful s
+

A predicate. It tests whether the state s in the FA faName +is able to reach a final state by one or more transitions. +The result is a boolean value. It will be set to true if the +state is useful, and false otherwise.

+
faName epsilon_closure s
+

Returns the set of states which are reachable from the state s +in the FA faName by one or more epsilon transitions, i.e +transitions over the empty symbol, transitions which do not consume +input. This is called the epsilon closure of s.

+
faName reverse
+
+
faName complete
+
+
faName remove_eps
+
+
faName trim ?what?
+
+
faName determinize ?mapvar?
+
+
faName minimize ?mapvar?
+
+
faName complement
+
+
faName kleene
+
+
faName optional
+
+
faName union fa ?mapvar?
+
+
faName intersect fa ?mapvar?
+
+
faName difference fa ?mapvar?
+
+
faName concatenate fa ?mapvar?
+
+
faName fromRegex regex ?over?
+

These methods provide more complex operations on the FA. Please see +the same-named commands in the package grammar::fa::op for +descriptions of what they do.

+
+
+ +

FINITE AUTOMATONS

+

For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where

+
    +

  • S is a set of states,

    • +

  • Sy a set of input symbols,

    • +

  • St is a subset of S, the set of start states, also known as +initial states.

    • +

  • Fi is a subset of S, the set of final states, also known as +accepting.

    • +

  • T is a function from S x (Sy + epsilon) to {S}, the transition function. +Here epsilon denotes the empty input symbol and is distinct +from all symbols in Sy; and {S} is the set of subsets of S. In other +words, T maps a combination of State and Input (which can be empty) to +a set of successor states.

    • +
+

In computer theory a FA is most often shown as a graph where the nodes +represent the states, and the edges between the nodes encode the +transition function: For all n in S' = T (s, sy) we have one edge +between the nodes representing s and n resp., labeled with sy. The +start and accepting states are encoded through distinct visual +markers, i.e. they are attributes of the nodes.

+

FA's are used to process streams of symbols over Sy.

+

A specific FA is said to accept a finite stream sy_1 sy_2 +... sy_n if there is a path in the graph of the FA beginning at a +state in St and ending at a state in Fi whose edges have the labels +sy_1, sy_2, etc. to sy_n. +The set of all strings accepted by the FA is the language of +the FA. One important equivalence is that the set of languages which +can be accepted by an FA is the set of regular languages.

+

Another important concept is that of deterministic FAs. A FA is said +to be deterministic if for each string of input symbols there +is exactly one path in the graph of the FA beginning at the start +state and whose edges are labeled with the symbols in the string. +While it might seem that non-deterministic FAs to have more power of +recognition, this is not so. For each non-deterministic FA we can +construct a deterministic FA which accepts the same language (--> +Thompson's subset construction).

+

While one of the premier applications of FAs is in parsing, +especially in the lexer stage (where symbols == characters), +this is not the only possibility by far.

+

Quite a lot of processes can be modeled as a FA, albeit with a +possibly large set of states. For these the notion of accepting states +is often less or not relevant at all. What is needed instead is the +ability to act to state changes in the FA, i.e. to generate some +output in response to the input. +This transforms a FA into a finite transducer, which has an +additional set OSy of output symbols and also an additional +output function O which maps from "S x (Sy + epsilon)" to +"(Osy + epsilon)", i.e a combination of state and input, possibly +empty to an output symbol, or nothing.

+

For the graph representation this means that edges are additional +labeled with the output symbol to write when this edge is traversed +while matching input. Note that for an application "writing an output +symbol" can also be "executing some code".

+

Transducers are not handled by this package. They will get their own +package in the future.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/faop.html Index: embedded/www/tcllib/files/modules/grammar_fa/faop.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_fa/faop.html @@ -0,0 +1,464 @@ + + +grammar::fa::op - Finite automaton operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::op - Operations on finite automatons

+
+ + +

Description

+

This package provides a number of complex operations on finite +automatons (Short: FA), +as provided by the package grammar::fa. +The package does not provide the ability to create and/or manipulate +such FAs, nor the ability to execute a FA for a stream of symbols. +Use the packages grammar::fa +and grammar::fa::interpreter for that. +Another package related to this is grammar::fa::compiler +which turns a FA into an executor class which has the definition of +the FA hardwired into it.

+

For more information about what a finite automaton is see section +FINITE AUTOMATONS in package grammar::fa.

+
+

API

+

The package exports the API described here. All commands modify their +first argument. I.e. whatever FA they compute is stored back into +it. Some of the operations will construct an automaton whose states +are all new, but related to the states in the source +automaton(s). These operations take variable names as optional +arguments where they will store mappings which describe the +relationship(s). +The operations can be loosely partitioned into structural and language +operations. The latter are defined in terms of the language the +automaton(s) accept, whereas the former are defined in terms of the +structural properties of the involved automaton(s). Some operations +are both. +Structure operations

+
+
::grammar::fa::op::constructor cmd
+

This command has to be called by the user of the package before any other +operations is performed, to establish a command which can be used to +construct a FA container object. If this is not done several operations +will fail as they are unable to construct internal and transient containers +to hold state and/or partial results.

+

Any container class using this package for complex operations should set +its own class command as the constructor. See package grammar::fa +for an example.

+
::grammar::fa::op::reverse fa
+

Reverses the fa. This is done by reversing the direction of all +transitions and swapping the sets of start and final +states. The language of fa changes unpredictably.

+
::grammar::fa::op::complete fa ?sink?
+

Completes the fa complete, but nothing is done if the +fa is already complete. This implies that only the first +in a series of multiple consecutive complete operations on fa +will perform anything. The remainder will be null operations.

+

The language of fa is unchanged by this operation.

+

This is done by adding a single new state, the sink, and +transitions from all other states to that sink for all symbols they +have no transitions for. The sink itself is made complete by adding +loop transitions for all symbols.

+

Note: When a FA has epsilon-transitions transitions over a symbol for +a state S can be indirect, i.e. not attached directly to S, but to a +state in the epsilon-closure of S. The symbols for such indirect +transitions count when computing completeness of a state. In other +words, these indirectly reached symbols are not missing.

+

The argument sink provides the name for the new state and most +not be present in the fa if specified. If the name is not +specified the command will name the state "sinkn", where n +is set so that there are no collisions with existing states.

+

Note that the sink state is not useful by definition. In +other words, while the FA becomes complete, it is also +not useful in the strict sense as it has a state from which +no final state can be reached.

+
::grammar::fa::op::remove_eps fa
+

Removes all epsilon-transitions from the fa in such a manner the +the language of fa is unchanged. However nothing is done if the +fa is already epsilon-free. +This implies that only the first in a series of multiple consecutive +complete operations on fa will perform anything. The remainder +will be null operations.

+

Note: This operation may cause states to become unreachable or +not useful. These states are not removed by this operation. +Use ::grammar::fa::op::trim for that instead.

+
::grammar::fa::op::trim fa ?what?
+

Removes unwanted baggage from fa. +The legal values for what are listed below. The command defaults +to !reachable|!useful if no specific argument was given.

+
+
!reachable
+

Removes all states which are not reachable from a start state.

+
!useful
+

Removes all states which are unable to reach a final state.

+
!reachable&!useful
+
+
!(reachable|useful)
+

Removes all states which are not reachable from a start state and are +unable to reach a final state.

+
!reachable|!useful
+
+
!(reachable&useful)
+

Removes all states which are not reachable from a start state or are +unable to reach a final state.

+
+
::grammar::fa::op::determinize fa ?mapvar?
+

Makes the fa deterministic without changing the language +accepted by the fa. However nothing is done if the fa is +already deterministic. This implies that only the first in a +series of multiple consecutive complete operations on fa will +perform anything. The remainder will be null operations.

+

The command will store a dictionary describing the relationship +between the new states of the resulting dfa and the states of the +input nfa in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting dfa, values +are sets of states from the input nfa.

+

Note: An empty dictionary signals that the command was able to +make the fa deterministic without performing a full subset +construction, just by removing states and shuffling transitions around +(As part of making the FA epsilon-free).

+

Note: The algorithm fails to make the FA deterministic in the +technical sense if the FA has no start state(s), because determinism +requires the FA to have exactly one start states. +In that situation we make a best effort; and the missing start state +will be the only condition preventing the generated result from being +deterministic. +It should also be noted that in this case the possibilities for +trimming states from the FA are also severely reduced as we cannot +declare states unreachable.

+
::grammar::fa::op::minimize fa ?mapvar?
+

Creates a FA which accepts the same language as fa, but has a +minimal number of states. Uses Brzozowski's method to accomplish this.

+

The command will store a dictionary describing the relationship +between the new states of the resulting minimal fa and the states of +the input fa in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting minimal fa, +values are sets of states from the input fa.

+

Note: An empty dictionary signals that the command was able to +minimize the fa without having to compute new states. This +should happen if and only if the input FA was already minimal.

+

Note: If the algorithm has no start or final states to work +with then the result might be technically minimal, but have a very +unexpected structure. +It should also be noted that in this case the possibilities for +trimming states from the FA are also severely reduced as we cannot +declare states unreachable.

+
+

Language operations +All operations in this section require that all input FAs have at +least one start and at least one final state. Otherwise the language of +the FAs will not be defined, making the operation senseless (as it +operates on the languages of the FAs in a defined manner).

+
+
::grammar::fa::op::complement fa
+

Complements fa. This is possible if and only if fa is +complete and deterministic. The resulting FA accepts the +complementary language of fa. In other words, all inputs not +accepted by the input are accepted by the result, and vice versa.

+

The result will have all states and transitions of the input, and +different final states.

+
::grammar::fa::op::kleene fa
+

Applies Kleene's closure to fa. +The resulting FA accepts all strings S for which we can find a +natural number n (0 inclusive) and strings A1 ... An +in the language of fa such that S is the concatenation of +A1 ... An. +In other words, the language of the result is the infinite union over +finite length concatenations over the language of fa.

+

The result will have all states and transitions of the input, and new +start and final states.

+
::grammar::fa::op::optional fa
+

Makes the fa optional. In other words it computes the FA which +accepts the language of fa and the empty the word (epsilon) as +well.

+

The result will have all states and transitions of the input, and new +start and final states.

+
::grammar::fa::op::union fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the union of the languages of the two FAs.

+

The result will have all states and transitions of the two input FAs, +and new start and final states. All states of fb which exist in +fa as well will be renamed, and the mapvar will contain a +mapping from the old states of fb to the new ones, if present.

+

It should be noted that the result will be non-deterministic, even if +the inputs are deterministic.

+
::grammar::fa::op::intersect fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the intersection of the languages of the two FAs. In other +words, the result will accept a word if and only if the word is +accepted by both fa and fb. The result will be useful, but +not necessarily deterministic or minimal.

+

The command will store a dictionary describing the relationship +between the new states of the resulting fa and the pairs of states of +the input FAs in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting fa, values +are pairs of states from the input FAs. Pairs are represented by +lists. The first element in each pair will be a state in fa, the +second element will be drawn from fb.

+
::grammar::fa::op::difference fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the difference of the languages of the two FAs. In other +words, the result will accept a word if and only if the word is +accepted by fa, but not by fb. This can also be expressed +as the intersection of fa with the complement of fb. The +result will be useful, but not necessarily deterministic or minimal.

+

The command will store a dictionary describing the relationship +between the new states of the resulting fa and the pairs of states of +the input FAs in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting fa, values +are pairs of states from the input FAs. Pairs are represented by +lists. The first element in each pair will be a state in fa, the +second element will be drawn from fb.

+
::grammar::fa::op::concatenate fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the cross-product of the languages of the two FAs. I.e. a word +W will be accepted by the result if there are two words A and B +accepted by fa, and fb resp. and W is the concatenation of +A and B.

+

The result FA will be non-deterministic.

+
::grammar::fa::op::fromRegex fa regex ?over?
+

Generates a non-deterministic FA which accepts the same language as +the regular expression regex. If the over is specified it +is treated as the set of symbols the regular expression and the +automaton are defined over. The command will compute the set from the +"S" constructors in regex when over was not +specified. This set is important if and only if the complement +operator "!" is used in regex as the complementary language of +an FA is quite different for different sets of symbols.

+

The regular expression is represented by a nested list, which forms +a syntax tree. The following structures are legal:

+
+
{S x}
+

Atomic regular expression. Everything else is constructed from +these. Accepts the Symbol "x".

+
{. A1 A2 ...}
+

Concatenation operator. Accepts the concatenation of the regular +expressions A1, A2, etc.

+

Note that this operator accepts zero or more arguments. With zero +arguments the represented language is epsilon, the empty word.

+
{| A1 A2 ...}
+

Choice operator, also called "Alternative". Accepts all input accepted +by at least one of the regular expressions A1, A2, etc. In +other words, the union of A1, A2.

+

Note that this operator accepts zero or more arguments. With zero +arguments the represented language is the empty language, +the language without words.

+
{& A1 A2 ...}
+

Intersection operator, logical and. Accepts all input accepted which +is accepted by all of the regular expressions A1, A2, +etc. In other words, the intersection of A1, A2.

+
{? A}
+

Optionality operator. Accepts the empty word and anything from the +regular expression A.

+
{* A}
+

Kleene closure. Accepts the empty word and any finite concatenation of +words accepted by the regular expression A.

+
{+ A}
+

Positive Kleene closure. Accepts any finite concatenation of words +accepted by the regular expression A, but not the empty word.

+
{! A}
+

Complement operator. Accepts any word not accepted by the regular +expression A. Note that the complement depends on the set of +symbol the result should run over. See the discussion of the argument +over before.

+
+
::grammar::fa::op::toRegexp fa
+

This command generates and returns a regular expression which accepts +the same language as the finite automaton fa. The regular +expression is in the format as described above, for +::grammar::fa::op::fromRegex.

+
::grammar::fa::op::toRegexp2 fa
+

This command has the same functionality as ::grammar::fa::op::toRegexp, +but uses a different algorithm to simplify the generated regular expressions.

+
::grammar::fa::op::toTclRegexp regexp symdict
+

This command generates and returns a regular expression in Tcl syntax for the +regular expression regexp, if that is possible. regexp is in the +same format as expected by ::grammar::fa::op::fromRegex.

+

The command will fail and throw an error if regexp contains +complementation and intersection operations.

+

The argument symdict is a dictionary mapping symbol names to +pairs of syntactic type and Tcl-regexp. If a symbol +occurring in the regexp is not listed in this dictionary then +single-character symbols are considered to designate themselves +whereas multiple-character symbols are considered to be a character +class name.

+
::grammar::fa::op::simplifyRegexp regexp
+

This command simplifies a regular expression by applying the following +algorithm first to the main expression and then recursively to all +sub-expressions:

+
    +

  1. Convert the expression into a finite automaton.

    2. +

  2. Minimize the automaton.

    3. +

  3. Convert the automaton back to a regular expression.

    4. +

  4. Choose the shorter of original expression and expression from +the previous step.

    5. +
+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/gasm.html Index: embedded/www/tcllib/files/modules/grammar_me/gasm.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/gasm.html @@ -0,0 +1,445 @@ + + +grammar::me::cpu::gasm - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu::gasm - ME assembler

+
+ + +

Description

+

This package provides a simple in-memory assembler. Its origin is that +of a support package for use by packages converting PEG and other +grammars into a corresponding matcher based on the ME virtual machine, +like page::compiler::peg::mecpu. Despite that it is actually +mostly agnostic regarding the instructions, users can choose any +instruction set they like.

+

The program under construction is held in a graph structure (See +package struct::graph) during assembly and subsequent +manipulation, with instructions represented by nodes, and the flow of +execution between instructions explicitly encoded in the arcs between +them.

+

In this model jumps are not encoded explicitly, they are implicit in +the arcs. The generation of explicit jumps is left to any code +converting the graph structure into a more conventional +representation. The same goes for branches. They are implicitly +encoded by all instructions which have two outgoing arcs, whereas all +other instructions have only one outgoing arc. Their conditonality is +handled by tagging their outgoing arcs with information about the +conditions under which they are taken.

+

While the graph the assembler operates on is supplied from the +outside, i.e. external, it does manage some internal state, namely:

+
    +

  1. The handle of the graph node most assembler operations will +work on, the anchor.

    2. +

  2. A mapping from arbitrary strings to instructions. I.e. it is +possible to label an instruction during assembly, and later +recall that instruction by its label.

    3. +

  3. The condition code to use when creating arcs between +instructions, which is one of always, ok, and +fail.

    4. +

  4. The current operation mode, one of halt, +okfail, and !okfail.

    5. +

  5. The name of a node in a tree. This, and the operation mode +above are the parts most heavily influenced by the needs of a grammar +compiler, as they assume some basic program structures (selected +through the operation mode), and intertwine the graph with a tree, +like the AST for the grammar to be compiled.

    6. +
+
+

DEFINITIONS

+

As the graph the assembler is operating on, and the tree it is +intertwined with, are supplied to the assembler from the outside it is +necessary to specify the API expected from them, and to describe the +structures expected and/or generated by the assembler in either.

+
    +

  1. Any graph object command used by the assembler has to provide +the API as specified in the documentation for the package +struct::graph.

    2. +

  2. Any tree object command used by the assembler has to provide +the API as specified in the documentation for the package +struct::tree.

    3. +

  3. Any instruction (node) generated by the assembler in a graph +will have at least two, and at most three attributes:

    +
    +
    instruction
    +

    The value of this attribute is the name of +the instruction. The only names currently defined by the assembler are +the three pseudo-instructions

    +
    +
    NOP
    +

    This instruction does nothing. Useful for fixed +framework nodes, unchanging jump destinations, and the like. No +arguments.

    +
    C
    +

    A .NOP to allow the insertion of arbitrary comments +into the instruction stream, i.e. a comment node. One argument, the +text of the comment.

    +
    BRA
    +

    A .NOP serving as explicitly coded conditional +branch. No arguments.

    +
    +

    However we reserve the space of all instructions whose names begin +with a "." (dot) for future use by the assembler.

    +
    arguments
    +

    The value of this attribute is a list of +strings, the arguments of the instruction. The contents are dependent +on the actual instruction and the assembler doesn't know or care about +them. This means for example that it has no builtin knowledge about +what instruction need which arguments and thus doesn't perform any +type of checking.

    +
    expr
    +

    This attribute is optional. When it is present its +value is the name of a node in the tree intertwined with the graph.

    +
    +
    4. +

  4. Any arc between two instructions will have one attribute:

    +
    +
    condition
    +

    The value of this attribute determines under which +condition execution will take this arc. It is one of always, +ok, and fail. The first condition is used for all arcs +which are the single outgoing arc of an instruction. The other two are +used for the two outgoing arcs of an instruction which implicitly +encode a branch.

    +
    +
    5. +

  5. A tree node given to the assembler for cross-referencing will +be written to and given the following attributes, some fixed, some +dependent on the operation mode. All values will be references to +nodes in the instruction graph. Some of the instruction will expect +some or specific sets of these attributes.

    +
    +
    gas::entry
    +

    Always written.

    +
    gas::exit
    +

    Written for all modes but okfail.

    +
    gas::exit::ok
    +

    Written for mode okfail.

    +
    gas::exit::fail
    +

    Written for mode okfail.

    +
    +
    6. +
+
+

API

+
+
::grammar::me::cpu::gasm::begin g n ?mode? ?note?
+

This command starts the assembly of an instruction sequence, and +(re)initializes the state of the assembler. After completion of the +instruction sequence use ::grammar::me::cpu::gasm::done to +finalize the assembler.

+

It will operate on the graph g in the specified mode +(Default is okfail). As part of the initialization it will +always create a standard .NOP instruction and label it "entry". The +creation of the remaining standard instructions is +mode-dependent:

+
+
halt
+

An "icf_halt" instruction labeled "exit/return".

+
!okfail
+

An "icf_ntreturn" instruction labeled "exit/return".

+
okfail
+

Two .NOP instructions labeled "exit/ok" and +"exit/fail" respectively.

+
+

The note, if specified (default is not), is given to the "entry" .NOP instruction.

+

The node reference n is simply stored for use by +::grammar::me::cpu::gasm::done. It has to refer to a node in the +tree t argument of that command.

+

After the initialization is done the "entry" instruction will be the +anchor, and the condition code will be set to always.

+

The command returns the empy string as its result.

+
::grammar::me::cpu::gasm::done --> t
+

This command finalizes the creation of an instruction sequence and +then clears the state of the assembler. +NOTE that this does not delete any of the created +instructions. They can be made available to future begin/done cycles. +Further assembly will be possible only after reinitialization of the +system via ::grammar::me::cpu::gasm::begin.

+

Before the state is cleared selected references to selected +instructions will be written to attributes of the node n in the +tree t. +Which instructions are saved is mode-dependent. Both mode +and the destination node n were specified during invokation of +::grammar::me::cpu::gasm::begin.

+

Independent of the mode a reference to the instruction labeled "entry" +will be saved to the attribute gas::entry of n. The +reference to the node n will further be saved into the attribute +"expr" of the "entry" instruction. Beyond that

+
+
halt
+

A reference to the instruction labeled +"exit/return" will be saved to the attribute gas::exit of +n.

+
okfail
+

See halt.

+
!okfail
+

Reference to the two instructions labeled +"exit/ok" and "exit/fail" will be saved to the attributes +gas::exit::ok and gas::exit::fail of n +respectively.

+
+

The command returns the empy string as its result.

+
::grammar::me::cpu::gasm::state
+

This command returns the current state of the assembler. Its format is +not documented and considered to be internal to the package.

+
::grammar::me::cpu::gasm::state! s
+

This command takes a serialized assembler state s as returned by +::grammar::me::cpu::gasm::state and makes it the current state +of the assembler.

+

Note that this may overwrite label definitions, however all +non-conflicting label definitions in the state before are not touched +and merged with s.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::lift t dst = src
+

This command operates on the tree t. It copies the contents of +the attributes gas::entry, gas::exit::ok and +gas::exit::fail from the node src to the node dst. +It returns the empty string as its result.

+
::grammar::me::cpu::gasm::Inline t node label
+

This command links an instruction sequence created by an earlier +begin/done pair into the current instruction sequence.

+

To this end it

+
    +

  1. reads the instruction references from the attributes +gas::entry, gas::exit::ok, and gas::exit::fail +from the node n of the tree t and makes them available to +assembler und the labels label/entry, label/exit::ok, and +label/exit::fail respectively.

    2. +

  2. Creates an arc from the anchor to the node labeled +label/entry, and tags it with the current condition code.

    3. +

  3. Makes the node labeled label/exit/ok the new anchor.

    4. +
+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Cmd cmd ?arg...?
+

This is the basic command to add instructions to the graph. +It creates a new instruction of type cmd with the given +arguments arg... +If the anchor was defined it will also create an arc from the +anchor to the new instruction using the current condition code. +After the call the new instruction will be the anchor and the +current condition code will be set to always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Bra
+

This is a convenience command to create a .BRA pseudo-instruction. It +uses ::grammar::me::cpu::gasm::Cmd to actually create the +instruction and inherits its behaviour.

+
::grammar::me::cpu::gasm::Nop text
+

This is a convenience command to create a .NOP pseudo-instruction. It +uses ::grammar::me::cpu::gasm::Cmd to actually create the +instruction and inherits its behaviour. +The text will be saved as the first and only argument of the new +instruction.

+
::grammar::me::cpu::gasm::Note text
+

This is a convenience command to create a .C pseudo-instruction, +i.e. a comment. It uses ::grammar::me::cpu::gasm::Cmd to +actually create the instruction and inherits its behaviour. +The text will be saved as the first and only argument of the new +instruction.

+
::grammar::me::cpu::gasm::Jmp label
+

This command creates an arc from the anchor to the instruction +labeled with label, and tags with the the current condition +code.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Exit
+

This command creates an arc from the anchor to one of the exit +instructions, based on the operation mode (see +::grammar::me::cpu::gasm::begin), and tags it with current +condition code.

+

For mode okfail it links to the instruction labeled either +"exit/ok" or "exit/fail", depending on the current condition code, and +tagging it with the current condition code +For the other two modes it links to the instruction labeled +"exit/return", tagging it condition code always, independent +the current condition code.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Who label
+

This command returns a reference to the instruction labeled with +label.

+
::grammar::me::cpu::gasm::/Label name
+

This command labels the anchor with name. +Note that an instruction can have more than one label.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Clear
+

This command clears the anchor, leaving it undefined, and +further resets the current condition code to always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Ok
+

This command sets the current condition code to ok.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Fail
+

This command sets the current condition code to fail.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/At name
+

This command sets the anchor to the instruction labeled with +name, and further resets the current condition code to +always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/CloseLoop
+

This command marks the anchor as the last instruction in a loop +body, by creating the attribute LOOP.

+

The command returns the empty string as its result.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_ast.html Index: embedded/www/tcllib/files/modules/grammar_me/me_ast.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_ast.html @@ -0,0 +1,218 @@ + + +grammar::me_ast - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_ast - Various representations of ASTs

+
+ +

Description

+

This document specifies various representations for the +abstract syntax trees (short AST) generated by +instances of ME virtual machines, independent of variant. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

ASTs and all the representations we specify distinguish between two +types of nodes, namely:

+
+
Terminal
+

Terminal nodes refer to the terminal symbols found in the token +stream. They are always leaf nodes. I.e. terminal nodes never have +children.

+
Nonterminal
+

Nonterminal nodes represent a nonterminal symbol of the grammar used +during parsing. They can occur as leaf and inner nodes of the +tree.

+
+

Both types of nodes carry basic range information telling a user which +parts of the input are covered by the node by providing the location +of the first and last tokens found within the range. Locations are +provided as non-negative integer offsets from the beginning of the +token stream, with the first token found in the stream located at +offset 0 (zero).

+

The root of an AS tree can be either a terminal or nonterminal node.

+
+

AST VALUES

+

This representation of ASTs is a Tcl list. The main list represents +the root node of the tree, with the representations of the children +nested within.

+

Each node is represented by a single Tcl list containing three or more +elements. The first element is either the empty string or the name of +a nonterminal symbol (which is never the empty string). The second and +third elements are then the locations of the first and last tokens. +Any additional elements after the third are then the representations +of the children, with the leftmost child first, i.e. as the fourth +element of the list representing the node.

+
+

AST OBJECTS

+

In this representation an AST is represented by a Tcl object command +whose API is compatible to the tree objects provided by the package +struct::tree. I.e it has to support at least all of the +methods described by that package, and may support more.

+

Because of this the remainder of the specifications is written using +the terms of struct::tree.

+

Each node of the AST directly maps to a node in the tree object. All +data beyond the child nodes, i.e. node type and input locations, are +stored in attributes of the node in the tree object. They are:

+
+
type
+

The type of the AST node. The recognized values are terminal +and nonterminal.

+
range
+

The locations of the first and last token of the terminal data in the +input covered by the node. This is a list containing two locations.

+
detail
+

This attribute is present only for nonterminal nodes. It contains the +name of the nonterminal symbol stored in the node.

+
+
+

EXTENDED AST OBJECTS

+

Extended AST objects are like AST objects, with additional +information.

+
+
detail
+

This attribute is now present at all nodes. Its contents are unchanged +for nonterminal nodes. For terminal nodes it contains a list +describing all tokens from the input which are covered by the node.

+

Each element of the list contains the token name, the associated +lexeme attribute, line number, and column index, in this order.

+
range_lc
+

This new attribute is defined for all nodes, and contains the +locations from attribute range translated into line number and +column index. Lines are counted from 1, columns are counted from 0.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_cpu.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpu.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_cpu.html @@ -0,0 +1,357 @@ + + +grammar::me::cpu - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu - Virtual machine implementation II for parsing token streams

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation provides an object-based API and the machines are +not truly tied to Tcl. A C implementation of the same API is quite +possible.

+

Internally the package actually uses the value-based machine +manipulation commands as provided by the package +grammar::me::cpu::core to perform its duties.

+
+

API

+

CLASS API

+

The package directly provides only a single command for the +construction of ME virtual machines.

+
+
::grammar::me::cpu meName matchcode
+

The command creates a new ME machine object with an associated global +Tcl command whose name is meName. This command may be used to +invoke various operations on the machine. +It has the following general form:

+
+
meName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The argument matchcode contains the match instructions the +machine has to execute while parsing the input stream. Please read +section MATCH CODE REPRESENTATION of the +documentation for the package grammar::me::cpu::core for +the specification of the structure of this value.

+

The tokmap argument taken by the implementation provided by the +package grammar::me::tcl is here hidden inside of the match +instructions and therefore not needed.

+
+
+

OBJECT API

+

All ME virtual machine objects created by the class command specified +in section CLASS API support the methods listed below.

+

The machines provided by this package provide methods for operation in +both push- and pull-styles. Push-style means that tokens are pushed +into the machine state when they arrive, triggering further execution +until they are consumed. In other words, this allows the machine to be +suspended and resumed at will and an arbitrary number of times, the +quasi-parallel operation of several machines, and the operation as +part of the event loop.

+
+
meName lc location
+

This method converts the location of a token given as offset in the +input stream into the associated line number and column index. The +result of the command is a 2-element list containing the two values, +in the order mentioned in the previous sentence. +This allows higher levels to convert the location information found in +the error status and the generated AST into more human readable data.

+

Note that the command is not able to convert locations which +have not been reached by the machine yet. In other words, if the +machine has read 7 tokens the command is able to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+
meName tok ?from ?to??
+

This method returns a Tcl list containing the part of the input stream +between the locations from and to (both inclusive). If +to is not specified it will default to the value of from. +If from is not specified either the whole input stream is returned.

+

Each element of the returned list is a list of four elements, the +token, its associated lexeme, line number, and column index, in this +order. +This command places the same restrictions on its location arguments as +the method lc.

+
meName pc state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter.

+
meName iseof state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag.

+
meName at state
+

This method takes the state value of a ME virtual machine and returns +the current location in the input stream.

+
meName cc state
+

This method takes the state value of a ME virtual machine and returns +the current token.

+
meName sv
+

This command returns the current semantic value SV stored in +the machine. This is an abstract syntax tree as specified in the +document grammar::me_ast, section AST VALUES.

+
meName ok
+

This method returns the current match status OK.

+
meName error
+

This method returns the current error status ER.

+
meName lstk state
+

This method takes the state value of a ME virtual machine and returns +the location stack.

+
meName astk state
+

This method takes the state value of a ME virtual machine and returns +the AST stack.

+
meName mstk state
+

This method takes the state value of a ME virtual machine and returns +the AST marker stack.

+
meName estk state
+

This method takes the state value of a ME virtual machine and returns +the error stack.

+
meName rstk state
+

This method takes the state value of a ME virtual machine and returns +the subroutine return stack.

+
meName nc state
+

This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary.

+
meName ast
+

This method returns the current top entry of the AST stack AS. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
meName halted
+

This method returns a boolean value telling the caller whether the +engine has halted execution or not. Halt means that no further +matching is possible, and the information retrieved via the other +method is final. Attempts to run the engine will be ignored, +until a reset is made.

+
meName code
+

This method returns the code information used to construct the +object. In other words, the match program executed by the machine.

+
meName eof
+

This method adds an end of file marker to the end of the input stream. +This signals the machine that the current contents of the input queue +are the final parts of the input and nothing will come after. Attempts +to put more characters into the queue will fail.

+
meName put tok lex line col
+

This method adds the token tok to the end of the input stream, +with associated lexeme data lex and line/column +information.

+
meName putstring string lvar cvar
+

This method adds each individual character in the string as a +token to the end of the input stream, from first to last. The lexemes +will be empty and the line/col information is computed based on the +characters encountered and the data in the variables lvar and +cvar.

+
meName run ?n?
+

This methods causes the engine to execute match instructions until +either

+
    +

  • n instructions have been executed, or

    • +

  • a halt instruction was executed, or

    • +

  • the input queue is empty and the code is asking for more tokens to +process.

    • +
+

If no limit n was set only the last two conditions are checked +for.

+
meName pull nextcmd
+

This method implements pull-style operation of the machine. It causes +it to execute match instructions until either a halt instruction is +reached, or the command prefix +nextcmd ceases to deliver more tokens.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the machine whenever the a new character +from the stream is required. The instruction for handling this is +ict_advance. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The end of the input stream for this method does not imply that method +eof is called for the machine as a whole. By avoiding this +and still asking for an explicit call of the method it is possible to +mix push- and pull-style operation during the lifetime of the machine.

+
meName reset
+

This method resets the machine to its initial state, discarding any +state it may have.

+
meName destroy
+

This method deletes the object and releases all resurces it claimed.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html @@ -0,0 +1,422 @@ + + +grammar::me::cpu::core - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu::core - ME virtual machine state manipulation

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation represents each ME virtual machine as a Tcl value +and provides commands to manipulate and query such values to show the +effects of executing instructions, adding tokens, retrieving state, +etc.

+

The values fully follow the paradigm of Tcl that every value is a +string and while also allowing C implementations for a proper +Tcl_ObjType to keep all the important data in native data structures. +Because of the latter it is recommended to access the state values +only through the commands of this package to ensure that +internal representation is not shimmered away.

+

The actual structure used by all state values is described in section +CPU STATE.

+
+

API

+

The package directly provides only a single command, and all the +functionality is made available through its methods.

+
+
::grammar::me::cpu::core disasm asm
+

This method returns a list containing a disassembly of the match +instructions in asm. The format of asm is specified in the +section MATCH PROGRAM REPRESENTATION.

+

Each element of the result contains instruction label, instruction +name, and the instruction arguments, in this order. The label can be +the empty string. Jump destinations are shown as labels, strings and +tokens unencoded. Token names are prefixed with their numeric id, if, +and only if a tokmap is defined. The two components are separated by a +colon.

+
::grammar::me::cpu::core asm asm
+

This method returns code in the format as specified in section +MATCH PROGRAM REPRESENTATION generated from ME assembly +code asm, which is in the format as returned by the method +disasm.

+
::grammar::me::cpu::core new asm
+

This method creates state value for a ME virtual machine in its +initial state and returns it as its result.

+

The argument matchcode contains a Tcl representation of the +match instructions the machine has to execute while parsing the input +stream. Its format is specified in the section +MATCH PROGRAM REPRESENTATION.

+

The tokmap argument taken by the implementation provided by the +package grammar::me::tcl is here hidden inside of the match +instructions and therefore not needed.

+
::grammar::me::cpu::core lc state location
+

This method takes the state value of a ME virtual machine and uses it +to convert a location in the input stream (as offset) into a line +number and column index. The result of the method is a 2-element list +containing the two pieces in the order mentioned in the previous +sentence.

+

Note that the method cannot convert locations which the machine +has not yet read from the input stream. In other words, if the machine +has read 7 characters so far it is possible to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+

This utility allows higher levels to convert the location offsets +found in the error status and the AST into more human readable data.

+
::grammar::me::cpu::core tok state ?from ?to??
+

This method takes the state value of a ME virtual machine and returns +a Tcl list containing the part of the input stream between the +locations from and to (both inclusive). If to is not +specified it will default to the value of from. If from is +not specified either the whole input stream is returned.

+

This method places the same restrictions on its location arguments as +the method lc.

+
::grammar::me::cpu::core pc state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter.

+
::grammar::me::cpu::core iseof state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag.

+
::grammar::me::cpu::core at state
+

This method takes the state value of a ME virtual machine and returns +the current location in the input stream.

+
::grammar::me::cpu::core cc state
+

This method takes the state value of a ME virtual machine and returns +the current token.

+
::grammar::me::cpu::core sv state
+

This method takes the state value of a ME virtual machine and returns +the current semantic value stored in it. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
::grammar::me::cpu::core ok state
+

This method takes the state value of a ME virtual machine and returns +the match status stored in it.

+
::grammar::me::cpu::core error state
+

This method takes the state value of a ME virtual machine and returns +the current error status stored in it.

+
::grammar::me::cpu::core lstk state
+

This method takes the state value of a ME virtual machine and returns +the location stack.

+
::grammar::me::cpu::core astk state
+

This method takes the state value of a ME virtual machine and returns +the AST stack.

+
::grammar::me::cpu::core mstk state
+

This method takes the state value of a ME virtual machine and returns +the AST marker stack.

+
::grammar::me::cpu::core estk state
+

This method takes the state value of a ME virtual machine and returns +the error stack.

+
::grammar::me::cpu::core rstk state
+

This method takes the state value of a ME virtual machine and returns +the subroutine return stack.

+
::grammar::me::cpu::core nc state
+

This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary.

+
::grammar::me::cpu::core ast state
+

This method takes the state value of a ME virtual machine and returns +the abstract syntax tree currently at the top of the AST stack stored +in it. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
::grammar::me::cpu::core halted state
+

This method takes the state value of a ME virtual machine and returns +the current halt status stored in it, i.e. if the machine has stopped +or not.

+
::grammar::me::cpu::core code state
+

This method takes the state value of a ME virtual machine and returns +the code stored in it, i.e. the instructions executed by the machine.

+
::grammar::me::cpu::core eof statevar
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar and modifies it so that the eof +flag inside is set. This signals to the machine that whatever token +are in the input queue are the last to be processed. There will be no +more.

+
::grammar::me::cpu::core put statevar tok lex line col
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar and modifies it so that the token +tok is added to the end of the input queue, with associated +lexeme data lex and line/column information.

+

The operation will fail with an error if the eof flag of the machine +has been set through the method eof.

+
::grammar::me::cpu::core run statevar ?n?
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar, executes a number of +instructions and stores the state resulting from their modifications +back into the variable.

+

The execution loop will run until either

+
    +

  • n instructions have been executed, or

    • +

  • a halt instruction was executed, or

    • +

  • the input queue is empty and the code is asking for more tokens to +process.

    • +
+

If no limit n was set only the last two conditions are checked +for.

+
+

MATCH PROGRAM REPRESENTATION

+

A match program is represented by nested Tcl list. The first element, +asm, is a list of integer numbers, the instructions to execute, +and their arguments. The second element, pool, is a list of +strings, referenced by the instructions, for error messages, token +names, etc. The third element, tokmap, provides ordering +information for the tokens, mapping their names to their numerical +rank. This element can be empty, forcing lexicographic comparison when +matching ranges.

+

All ME instructions are encoded as integer numbers, with the mapping +given below. A number of the instructions, those which handle error +messages, have been given an additional argument to supply that +message explicitly instead of having it constructed from token names, +etc. This allows the machine state to store only the message ids +instead of the full strings.

+

Jump destination arguments are absolute indices into the asm +element, refering to the instruction to jump to. Any string arguments +are absolute indices into the pool element. Tokens, characters, +messages, and token (actually character) classes to match are coded as +references into the pool as well.

+
    +

  1. "ict_advance message"

    2. +

  2. "ict_match_token tok message"

    3. +

  3. "ict_match_tokrange tokbegin tokend message"

    4. +

  4. "ict_match_tokclass code message"

    5. +

  5. "inc_restore branchlabel nt"

    6. +

  6. "inc_save nt"

    7. +

  7. "icf_ntcall branchlabel"

    8. +

  8. "icf_ntreturn"

    9. +

  9. "iok_ok"

    10. +

  10. "iok_fail"

    11. +

  11. "iok_negate"

    12. +

  12. "icf_jalways branchlabel"

    13. +

  13. "icf_jok branchlabel"

    14. +

  14. "icf_jfail branchlabel"

    15. +

  15. "icf_halt"

    16. +

  16. "icl_push"

    17. +

  17. "icl_rewind"

    18. +

  18. "icl_pop"

    19. +

  19. "ier_push"

    20. +

  20. "ier_clear"

    21. +

  21. "ier_nonterminal message"

    22. +

  22. "ier_merge"

    23. +

  23. "isv_clear"

    24. +

  24. "isv_terminal"

    25. +

  25. "isv_nonterminal_leaf nt"

    26. +

  26. "isv_nonterminal_range nt"

    27. +

  27. "isv_nonterminal_reduce nt"

    28. +

  28. "ias_push"

    29. +

  29. "ias_mark"

    30. +

  30. "ias_mrewind"

    31. +

  31. "ias_mpop"

    32. +
+
+
+

CPU STATE

+

A state value is a list containing the following elements, in the order listed below:

+
    +

  1. code: Match instructions, see MATCH PROGRAM REPRESENTATION.

    2. +

  2. pc: Program counter, int.

    3. +

  3. halt: Halt flag, boolean.

    4. +

  4. eof: Eof flag, boolean

    5. +

  5. tc: Terminal cache, and input queue. Structure see below.

    6. +

  6. cl: Current location, int.

    7. +

  7. ct: Current token, string.

    8. +

  8. ok: Match status, boolean.

    9. +

  9. sv: Semantic value, list.

    10. +

  10. er: Error status, list.

    11. +

  11. ls: Location stack, list.

    12. +

  12. as: AST stack, list.

    13. +

  13. ms: AST marker stack, list.

    14. +

  14. es: Error stack, list.

    15. +

  15. rs: Return stack, list.

    16. +

  16. nc: Nonterminal cache, dictionary.

    17. +
+

tc, the input queue of tokens waiting for processing and the +terminal cache containing the tokens already processing are one +unified data structure simply holding all tokens and their +information, with the current location separating that which has been +processed from that which is waiting. +Each element of the queue/cache is a list containing the token, its +lexeme information, line number, and column index, in this order.

+

All stacks have their top element aat the end, i.e. pushing an item is +equivalent to appending to the list representing the stack, and +popping it removes the last element.

+

er, the error status is either empty or a list of two elements, +a location in the input, and a list of messages, encoded as references +into the pool element of the code.

+

nc, the nonterminal cache is keyed by nonterminal name and +location, each value a four-element list containing current location, +match status, semantic value, and error status, in this order.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_intro.html Index: embedded/www/tcllib/files/modules/grammar_me/me_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_intro.html @@ -0,0 +1,179 @@ + + +grammar::me_intro - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_intro - Introduction to virtual machines for parsing token streams

+
+ +

Description

+

This document is an introduction to and overview of the basic +facilities for the parsing and/or matching of token +streams. One possibility often used for the token domain are +characters.

+

The packages themselves all provide variants of one +virtual machine, called a match engine (short +ME), which has all the facilities needed for the matching and +parsing of a stream, and which are either controlled directly, or are +customized with a match program. The virtual machine is basically a +pushdown automaton, with additional elements for backtracking and/or +handling of semantic data and construction of abstract syntax trees +(AST).

+

Because of the high degree of similarity in the actual implementations +of the aforementioned virtual machine and the data structures they +receive and generate these common parts are specified in a separate +document which will be referenced by the documentation for packages +actually implementing it.

+

The relevant documents are:

+
+
grammar::me_vm
+

Virtual machine specification.

+
grammar::me_ast
+

Specification of various representations used for abstract syntax +trees.

+
grammar::me::util
+

Utility commands.

+
grammar::me::tcl
+

Singleton ME virtual machine implementation tied to Tcl for control +flow and stacks. Hardwired for pull operation. Uninteruptible during +processing.

+
grammar::me::cpu
+

Object-based ME virtual machine implementation with explicit control +flow, and stacks, using bytecodes. Suspend/Resumable. Push/pull +operation.

+
grammar::me::cpu::core
+

Core functionality for state manipulation and stepping used in the +bytecode based implementation of ME virtual machines.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_tcl.html Index: embedded/www/tcllib/files/modules/grammar_me/me_tcl.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_tcl.html @@ -0,0 +1,402 @@ + + +grammar::me::tcl - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::tcl - Virtual machine implementation I for parsing token streams

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation is tied very strongly to Tcl. All the stacks in +the machine state are handled through the Tcl stack, all control flow +is handled by Tcl commands, and the remaining machine instructions are +directly mapped to Tcl commands. Especially the matching of +nonterminal symbols is handled by Tcl procedures as well, essentially +extending the machine implementation with custom instructions.

+

Further on the implementation handles only a single machine which is +uninteruptible during execution and hardwired for pull operation. I.e. +it explicitly requests each new token through a callback, pulling them +into its state.

+

A related package is grammar::peg::interp which provides a +generic interpreter / parser for parsing expression grammars (PEGs), +implemented on top of this implementation of the ME virtual machine.

+
+

API

+

The commands documented in this section do not implement any of the +instructions of the ME virtual machine. They provide the facilities +for the initialization of the machine and the retrieval of important +information.

+
+
::grammar::me::tcl cmd ...
+

This is an ensemble command providing access to the commands listed in +this section. See the methods themselves for detailed specifications.

+
::grammar::me::tcl init nextcmd ?tokmap?
+

This command (re)initializes the machine. It returns the empty +string. This command has to be invoked before any other command of +this package.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the machine whenever the a new character +from the stream is required. The instruction for handling this is +ict_advance. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The optional dictionary tokmap maps from tokens to integer +numbers. If present the numbers impose an order on the tokens, which +is subsequently used by ict_match_tokrange to determine if a +token is in the specified range or not. If no token map is specified +the lexicographic order of th token names will be used instead. This +choice is especially asensible when using characters as tokens.

+
::grammar::me::tcl lc location
+

This command converts the location of a token given as offset in the +input stream into the associated line number and column index. The +result of the command is a 2-element list containing the two values, +in the order mentioned in the previous sentence. +This allows higher levels to convert the location information found in +the error status and the generated AST into more human readable data.

+

Note that the command is not able to convert locations which +have not been reached by the machine yet. In other words, if the +machine has read 7 tokens the command is able to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+

After a call of init the state used for the conversion is +cleared, making further conversions impossible until the machine has +read tokens again.

+
::grammar::me::tcl tok from ?to?
+

This command returns a Tcl list containing the part of the input +stream between the locations from and to (both +inclusive). If to is not specified it will default to the value +of from.

+

Each element of the returned list is a list of four elements, the +token, its associated lexeme, line number, and column index, in this +order. +In other words, each element has the same structure as the result of +the nextcmd callback given to ::grammar::me::tcl::init

+

This command places the same restrictions on its location arguments as +::grammar::me::tcl::lc.

+
::grammar::me::tcl tokens
+

This command returns the number of tokens currently known to the ME +virtual machine.

+
::grammar::me::tcl sv
+

This command returns the current semantic value SV stored in +the machine. This is an abstract syntax tree as specified in the +document grammar::me_ast, section AST VALUES.

+
::grammar::me::tcl ast
+

This method returns the abstract syntax tree currently at the top of +the AST stack of the ME virtual machine. This is an abstract syntax +tree as specified in the document grammar::me_ast, section +AST VALUES.

+
::grammar::me::tcl astall
+

This method returns the whole stack of abstract syntax trees currently +known to the ME virtual machine. Each element of the returned list is +an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES. +The top of the stack resides at the end of the list.

+
::grammar::me::tcl ctok
+

This method returns the current token considered by the ME virtual +machine.

+
::grammar::me::tcl nc
+

This method returns the contents of the nonterminal cache as a +dictionary mapping from "symbol,location" to match +information.

+
::grammar::me::tcl next
+

This method returns the next token callback as specified during +initialization of the ME virtual machine.

+
::grammar::me::tcl ord
+

This method returns a dictionary containing the tokmap specified +during initialization of the ME virtual machine. +::grammar::me::tcl::ok +This variable contains the current match status OK. It is +provided as variable instead of a command because that makes access to +this information faster, and the speed of access is considered very +important here as this information is used constantly to determine the +control flow.

+
+
+

MACHINE STATE

+

Please go and read the document grammar::me_vm first for a +specification of the basic ME virtual machine and its state.

+

This implementation manages the state described in that document, +except for the stacks minus the AST stack. In other words, location +stack, error stack, return stack, and ast marker stack are implicitly +managed through standard Tcl scoping, i.e. Tcl variables in +procedures, outside of this implementation.

+
+

MACHINE INSTRUCTIONS

+

Please go and read the document grammar::me_vm first for a +specification of the basic ME virtual machine and its instruction set.

+

This implementation maps all instructions to Tcl commands in the +namespace "::grammar::me::tcl", except for the stack related commands, +nonterminal symbols and control flow. +Here we simply list the commands and explain the differences to the +specified instructions, if there are any. For their semantics see the +aforementioned specification. The machine commands are not +reachable through the ensemble command ::grammar::me::tcl.

+
+
::grammar::me::tcl::ict_advance message
+

No changes.

+
::grammar::me::tcl::ict_match_token tok message
+

No changes.

+
::grammar::me::tcl::ict_match_tokrange tokbegin tokend message
+

If, and only if a token map was specified during initialization then +the arguments are the numeric representations of the smallest and +largest tokens in the range. Otherwise they are the relevant tokens +themselves and lexicographic comparison is used.

+
::grammar::me::tcl::ict_match_tokclass code message
+

No changes.

+
::grammar::me::tcl::inc_restore nt
+

Instead of taking a branchlabel the command returns a boolean value. +The result will be true if and only if cached information was +found. The caller has to perform the appropriate branching.

+
::grammar::me::tcl::inc_save nt startlocation
+

The command takes the start location as additional argument, as it is +managed on the Tcl stack, and not in the machine state.

+
icf_ntcall branchlabel
+
+
icf_ntreturn
+

These two instructions are not mapped to commands. They are control +flow instructions and handled in Tcl.

+
::grammar::me::tcl::iok_ok
+

No changes.

+
::grammar::me::tcl::iok_fail
+

No changes.

+
::grammar::me::tcl::iok_negate
+

No changes.

+
icf_jalways branchlabel
+
+
icf_jok branchlabel
+
+
icf_jfail branchlabel
+
+
icf_halt
+

These four instructions are not mapped to commands. They are control +flow instructions and handled in Tcl.

+
::grammar::me::tcl::icl_get
+

This command returns the current location CL in the input. +It replaces icl_push.

+
::grammar::me::tcl::icl_rewind oldlocation
+

The command takes the location as argument as it comes from the +Tcl stack, not the machine state.

+
icl_pop
+

Not mapped, the stacks are not managed by the package.

+
::grammar::me::tcl::ier_get
+

This command returns the current error state ER. +It replaces ier_push.

+
::grammar::me::tcl::ier_clear
+

No changes.

+
::grammar::me::tcl::ier_nonterminal message location
+

The command takes the location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::ier_merge olderror
+

The command takes the second error state to merge as argument as it +comes from the Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_clear
+

No changes.

+
::grammar::me::tcl::isv_terminal
+

No changes.

+
::grammar::me::tcl::isv_nonterminal_leaf nt startlocation
+

The command takes the start location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_nonterminal_range nt startlocation
+

The command takes the start location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?
+

The command takes start location and marker as argument as it comes +from the Tcl stack, not the machine state.

+
::grammar::me::tcl::ias_push
+

No changes.

+
::grammar::me::tcl::ias_mark
+

This command returns a marker for the current state of the AST stack +AS. The marker stack is not managed by the machine.

+
::grammar::me::tcl::ias_pop2mark marker
+

The command takes the marker as argument as it comes from the +Tcl stack, not the machine state. It replaces ias_mpop.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_util.html Index: embedded/www/tcllib/files/modules/grammar_me/me_util.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_util.html @@ -0,0 +1,199 @@ + + +grammar::me::util - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me::util(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::util - AST utilities

+
+ + +

Description

+

This package provides a number of utility command for the conversion +between the various representations of abstract syntax trees as +specified in the document grammar::me_ast.

+
+
::grammar::me::util::ast2tree ast tree ?root?
+

This command converts an ast from value to object +representation. All nodes in the ast will be converted into +nodes of this tree, with the root of the AST a child of the node +root. If this node is not explicitly specified the root of the +tree is used. Existing content of tree is not touched, i.e. neither +removed nor changed, with the exception of the specified root node, +which will gain a new child.

+
::grammar::me::util::ast2etree ast mcmd tree ?root?
+

This command is like ::grammar::me::util::ast2tree, except that +the result is in the extended object representation of the input AST. +The source of the extended information is the command prefix +mcmd. +It has to understand two methods, lc, and tok, with +the semantics specified below.

+
+
mcmd lc location
+

Takes the location of a token given as offset in the input stream and +return a 2-element list containing the associated line number and +column index, in this order.

+
mcmd tok from ?to?
+

Takes one or two locations from and to as offset in the +input stream and returns a Tcl list containing the specified part of +the input stream. Both location are inclusive. If to is not +specified it will default to the value of from.

+

Each element of the returned list is a list containing the token, its +associated lexeme, the line number, and column index, in this order.

+
+

Both the ensemble command ::grammar::me::tcl provided by the +package grammar::me::tcl and the objects command created by +the package ::grammar::me::cpu fit the above specification.

+
::grammar::me::util::tree2ast tree ?root?
+

This command converts an ast in (extended) object representation +into a value and returns it. +If a root node is specified the AST is generated from that node +downward. Otherwise the root of the tree object is used as the +starting point.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_vm.html Index: embedded/www/tcllib/files/modules/grammar_me/me_vm.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_me/me_vm.html @@ -0,0 +1,549 @@ + + +grammar::me_vm - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_vm - Virtual machine for parsing token streams

+
+ +

Description

+

Please go and read the document grammar::me_intro first for +an overview of the various documents and their relations.

+

This document specifies a virtual machine for the controlled matching +and parsing of token streams, creating an +abstract syntax tree (short AST) reflecting the +structure of the input. Special machine features are the caching and +reuse of partial results, caching of the encountered input, and the +ability to backtrack in both input and AST creation.

+

These features make the specified virtual machine especially useful to +packrat parsers based on parsing expression grammars. It is however +not restricted to this type of parser. Normal LL and LR parsers can be +implemented with it as well.

+

The following sections will discuss first the abstract state kept by +ME virtual machines, and then their instruction set.

+
+

MACHINE STATE

+

A ME virtual machine manages the following state:

+
+
Current token CT
+

The token from the input under consideration by the machine.

+

This information is used and modified by the instructions defined in +the section +TERMINAL MATCHING.

+
Current location CL
+

The location of the current token in the input stream, as +offset relative to the beginning of the stream. The first token is +considered to be at offset 0.

+

This information is implicitly used and modified by the instructions +defined in the sections +TERMINAL MATCHING and +NONTERMINAL MATCHING, +and can be directly queried and modified by the instructions defined +in section +INPUT LOCATION HANDLING.

+
Location stack LS
+

In addition to the above a stack of locations, for backtracking. +Locations can put on the stack, removed from it, and removed with +setting the current location.

+

This information is implicitly used and modified by the instructions +defined in the sections +TERMINAL MATCHING and +NONTERMINAL MATCHING, +and can be directly queried and modified by the instructions defined +in section +INPUT LOCATION HANDLING.

+
Match status OK
+

A boolean value, the result of the last attempt at matching input. +It is set to true if that attempt was successful, and +false otherwise.

+

This information is influenced by the instructions defined in the +sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +UNCONDITIONAL MATCHING. +It is queried by the instructions defined in the section +CONTROL FLOW.

+
Semantic value SV
+

The semantic value associated with (generated by) the last attempt at +matching input. Contains either the empty string or a node for the +abstract syntax tree constructed from the input.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
AST stack AS
+

A stack of partial abstract syntax trees constructed by the machine +during matching.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
AST Marker stack MS
+

In addition to the above a stack of stacks, for backtracking. This is +actually a stack of markers into the AST stack, thus implicitly +snapshooting the state of the AST stack at some point in time. Markers +can be put on the stack, dropped from it, and used to roll back the +AST stack to an earlier state.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
Error status ER
+

Error information associated with the last attempt at matching +input. Contains either the empty string or a list of 2 elements, a +location in the input and a list of error messages associated with +it, in this order.

+

Note that error information can be set even if the last attempt +at matching input was successful. For example the *-operator (matching +a sub-expression zero or more times) in a parsing expression grammar +is always successful, even if it encounters a problem further in the +input and has to backtrack. Such problems must not be forgotten when +continuing to match.

+

This information is queried and influenced by the instructions defined +in the sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +ERROR HANDLING.

+
Error stack ES
+

In addition to the above a stack of error information, to allow the +merging of current and older error information when performing +backtracking in choices after an unsucessful match.

+

This information is queried and influenced by the instructions defined +in the sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +ERROR HANDLING.

+
Return stack RS
+

A stack of program counter values, i.e. locations in the code +controlling the virtual machine, for the management of subroutine +calls, i.e. the matching of nonterminal symbols.

+

This information is queried and influenced by the instructions defined +in the section +NONTERMINAL MATCHING.

+
Nonterminal cache NC
+

A cache of machine states (A 4-tuple containing a location in the +input, match status OK, semantic value SV, and error +status ER) keyed by name of nonterminal symbol and location in +the input stream.

+

The key location is where machine started the attempt to match the +named nonterminal symbol, and the location in the value is where +machine ended up after the attempt completed, independent of the +success of the attempt.

+

This status is queried and influenced by the instructions defined in +the section +NONTERMINAL MATCHING.

+
+
+

MACHINE INSTRUCTIONS

+

With the machine state specified it is now possible to explain the +instruction set of ME virtual machines. They are grouped roughly by +the machine state they influence and/or query.

+

TERMINAL MATCHING

+

First the instructions to match tokens from the input stream, and +by extension all terminal symbols.

+

These instructions are the only ones which may retrieve a new token +from the input stream. This is a may and not a will +because the instructions will a retrieve new token if, and only if the +current location CL is at the head of the stream. +If the machine has backtracked (see icl_rewind) the instructions +will retrieve the token to compare against from the internal cache.

+
+
ict_advance message
+

This instruction tries to advance to the next token in the input +stream, i.e. the one after the current location CL. The +instruction will fail if, and only if the end of the input stream is +reached, i.e. if there is no next token.

+

The sucess/failure of the instruction is remembered in the match +status OK. In the case of failure the error status ER is +set to the current location and the message message. +In the case of success the error status ER is cleared, the new +token is made the current token CT, and the new location is +made the current location CL.

+

The argument message is a reference to the string to put into +the error status ER, if such is needed.

+
ict_match_token tok message
+

This instruction tests the current token CT for equality +with the argument tok and records the result in the match +status OK. The instruction fails if the current token is +not equal to tok.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the +current location CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+
ict_match_tokrange tokbegin tokend message
+

This instruction tests the current token CT for being in +the range of tokens from tokbegin to tokend +(inclusive) and records the result in the match status OK. The +instruction fails if the current token is not inside the range.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the current location +CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+
ict_match_tokclass code message
+

This instruction tests the current token CT for being a member +of the token class code and records the result in the match +status OK. The instruction fails if the current token is not a +member of the specified class.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the +current location CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+

Currently the following classes are legal:

+
+
alnum
+

A token is accepted if it is a unicode alphabetical character, or a digit.

+
alpha
+

A token is accepted if it is a unicode alphabetical character.

+
digit
+

A token is accepted if it is a unicode digit character.

+
xdigit
+

A token is accepted if it is a hexadecimal digit character.

+
punct
+

A token is accepted if it is a unicode punctuation character.

+
space
+

A token is accepted if it is a unicode space character.

+
+
+
+

NONTERMINAL MATCHING

+

The instructions in this section handle the matching of nonterminal +symbols. They query the nonterminal cache NC for saved +information, and put such information into the cache.

+

The usage of the cache is a performance aid for backtracking parsers, +allowing them to avoid an expensive rematch of complex nonterminal +symbols if they have been encountered before.

+
+
inc_restore branchlabel nt
+

This instruction checks if the nonterminal cache NC contains +information about the nonterminal symbol nt, at the current +location CL. If that is the case the instruction will update +the machine state (current location CL, match status OK, +semantic value SV, and error status ER) with the found +information and continue execution at the instruction refered to by +the branchlabel. The new current location CL will be the +last token matched by the nonterminal symbol, i.e. belonging to it.

+

If no information was found the instruction will continue execution at +the next instruction.

+

Together with icf_ntcall it is possible to generate code for +memoized and non-memoized matching of nonterminal symbols, either as +subroutine calls, or inlined in the caller.

+
inc_save nt
+

This instruction saves the current state of the machine (current +location CL, match status OK, semantic value SV, +and error status ER), to the nonterminal cache NC. It +will also pop an entry from the location stack LS and save it +as the start location of the match.

+

It is expected to be called at the end of matching a nonterminal +symbol, with nt the name of the nonterminal symbol the code was +working on. This allows the instruction inc_restore to check for +and retrieve the data, should we have to match this nonterminal symbol +at the same location again, during backtracking.

+
icf_ntcall branchlabel
+

This instruction invokes the code for matching the nonterminal symbol +nt as a subroutine. To this end it stores the current program +counter PC on the return stack RS, the current location +CL on the location stack LS, and then continues +execution at the address branchlabel.

+

The next matching icf_ntreturn will cause the execution to +continue at the instruction coming after the call.

+
icf_ntreturn
+

This instruction will pop an entry from the return stack RS, +assign it to the program counter PC, and then continue +execution at the new address.

+
+
+

UNCONDITIONAL MATCHING

+

The instructions in this section are the remaining match +operators. They change the match status OK directly and +unconditionally.

+
+
iok_ok
+

This instruction sets the match status OK to true, +indicating a successful match.

+
iok_fail
+

This instruction sets the match status OK to false, +indicating a failed match.

+
iok_negate
+

This instruction negates the match status OK, turning a failure +into a success and vice versa.

+
+
+

CONTROL FLOW

+

The instructions in this section implement both conditional and +unconditional control flow. The conditional jumps query the match +status OK.

+
+
icf_jalways branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel and then continues execution from +there. This is an unconditional jump.

+
icf_jok branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel. This happens if, and only if the match +status OK indicates a success. Otherwise it simply continues +execution at the next instruction. This is a conditional jump.

+
icf_jfail branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel. This happens if, and only if the match +status OK indicates a failure. Otherwise it simply continues +execution at the next instruction. This is a conditional jump.

+
icf_halt
+

This instruction halts the machine and blocks any further execution.

+
+
+

INPUT LOCATION HANDLING

+

The instructions in this section are for backtracking, they manipulate +the current location CL of the machine state. +They allow a user of the machine to query and save locations in the +input, and to rewind the current location CL to saved +locations, making them one of the components enabling the +implementation of backtracking parsers.

+
+
icl_push
+

This instruction pushes a copy of the current location CL on +the location stack LS.

+
icl_rewind
+

This instruction pops an entry from the location stack LS and +then moves the current location CL back to this point in the +input.

+
icl_pop
+

This instruction pops an entry from the location stack LS and +discards it.

+
+
+

ERROR HANDLING

+

The instructions in this section provide read and write access to the +error status ER of the machine.

+
+
ier_push
+

This instruction pushes a copy of the current error status ER +on the error stack ES.

+
ier_clear
+

This instruction clears the error status ER.

+
ier_nonterminal message
+

This instruction checks if the error status ER contains an +error whose location is just past the location found in the top entry +of the location stack LS. +Nothing happens if no such error is found. +Otherwise the found error is replaced by an error at the location +found on the stack, having the message message.

+
ier_merge
+

This instruction pops an entry from the error stack ES, merges +it with the current error status ER and stores the result of +the merge as the new error status ER.

+

The merge is performed as described below:

+

If one of the two error states is empty the other is chosen. If +neither error state is empty, and refering to different locations, +then the error state with the location further in the input is +chosen. If both error states refer to the same location their messages +are merged (with removing duplicates).

+
+
+

SEMANTIC VALUES

+

The instructions in this section manipulate the semantic value +SV.

+
+
isv_clear
+

This instruction clears the semantic value SV.

+
isv_terminal
+

This instruction creates a terminal AST node for the current token +CT, makes it the semantic value SV, and also pushes the +node on the AST stack AS.

+
isv_nonterminal_leaf nt
+

This instruction creates a nonterminal AST node without any children +for the nonterminal nt, and makes it the semantic value +SV.

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
isv_nonterminal_range nt
+

This instruction creates a nonterminal AST node for the nonterminal +nt, with a single terminal node as its child, and makes this AST +the semantic value SV. The terminal node refers to the input +string from the location found on top of the location stack LS +to the current location CL (both inclusive).

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
isv_nonterminal_reduce nt
+

This instruction creates a nonterminal AST node for the nonterminal +nt and makes it the semantic value SV.

+

All entries on the AST stack AS above the marker found in the +top entry of the AST Marker stack MS become children of the new +node, with the entry at the stack top becoming the rightmost child. If +the AST Marker stack MS is empty the whole stack is used. The +AST marker stack MS is left unchanged.

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
+
+

AST STACK HANDLING

+

The instructions in this section manipulate the AST stack AS, +and the AST Marker stack MS.

+
+
ias_push
+

This instruction pushes the semantic value SV on the AST stack +AS.

+
ias_mark
+

This instruction pushes a marker for the current state of the AST +stack AS on the AST Marker stack MS.

+
ias_mrewind
+

This instruction pops an entry from the AST Marker stack MS and +then proceeds to pop entries from the AST stack AS until the +state represented by the popped marker has been reached again. +Nothing is done if the AST stack AS is already smaller than +indicated by the popped marker.

+
ias_mpop
+

This instruction pops an entry from the AST Marker stack MS and +discards it.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_peg/peg.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_peg/peg.html @@ -0,0 +1,592 @@ + + +grammar::peg - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::peg(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::peg - Create and manipulate parsing expression grammars

+
+ + +

Description

+

This package provides a container class for +parsing expression grammars (Short: PEG). +It allows the incremental definition of the grammar, its manipulation +and querying of the definition. +The package neither provides complex operations on the grammar, nor has +it the ability to execute a grammar definition for a stream of symbols. +Two packages related to this one are grammar::mengine and +grammar::peg::interpreter. The first of them defines a +general virtual machine for the matching of a character stream, and +the second implements an interpreter for parsing expression grammars +on top of that virtual machine.

+

TERMS & CONCEPTS

+

PEGs are similar to context-free grammars, but not equivalent; in some +cases PEGs are strictly more powerful than context-free grammars (there +exist PEGs for some non-context-free languages). +The formal mathematical definition of parsing expressions and parsing +expression grammars can be found in section +PARSING EXPRESSION GRAMMARS.

+

In short, we have terminal symbols, which are the most basic +building blocks for sentences, and nonterminal symbols +with associated parsing expressions, defining the grammatical +structure of the sentences. The two sets of symbols are distinctive, +and do not overlap. When speaking about symbols the word "symbol" is +often left out. The union of the sets of terminal and nonterminal +symbols is called the set of symbols.

+

Here the set of terminal symbols is not explicitly managed, +but implicitly defined as the set of all characters. Note that this +means that we inherit from Tcl the ability to handle all of Unicode.

+

A pair of nonterminal and parsing expression is also +called a grammatical rule, or rule for short. In the +context of a rule the nonterminal is often called the left-hand-side +(LHS), and the parsing expression the right-hand-side (RHS).

+

The start expression of a grammar is a parsing expression +from which all the sentences contained in the language specified by +the grammar are derived. +To make the understanding of this term easier let us assume for a +moment that the RHS of each rule, and the start expression, is either +a sequence of symbols, or a series of alternate parsing expressions. +In the latter case the rule can be seen as a set of rules, each +providing one alternative for the nonterminal. +A parsing expression A' is now a derivation of a parsing expression A +if we pick one of the nonterminals N in the expression, and one of the +alternative rules R for N, and then replace the nonterminal in A with +the RHS of the chosen rule. Here we can see why the terminal symbols +are called such. They cannot be expanded any further, thus terminate +the process of deriving new expressions. +An example

+
+    Rules
+      (1)  A <- a B c
+      (2a) B <- d B
+      (2b) B <- e
+    Some derivations, using starting expression A.
+      A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c
+
+

A derived expression containing only terminal symbols is a +sentence. The set of all sentences which can be derived from +the start expression is the language of the grammar.

+

Some definitions for nonterminals and expressions:

+
    +

  1. A nonterminal A is called reachable if it is possible to derive +a parsing expression from the start expression which contains A.

    2. +

  2. A nonterminal A is called useful if it is possible to derive a +sentence from it.

    3. +

  3. A nonterminal A is called recursive if it is possible to derive +a parsing expression from it which contains A, again.

    4. +

  4. The FIRST set of a nonterminal A contains all the symbols which +can occur of as the leftmost symbol in a parsing expression derived from +A. If the FIRST set contains A itself then that nonterminal is called +left-recursive.

    5. +

  5. The LAST set of a nonterminal A contains all the symbols which +can occur of as the rightmost symbol in a parsing expression derived from +A. If the LAST set contains A itself then that nonterminal is called +right-recursive.

    6. +

  6. The FOLLOW set of a nonterminal A contains all the symbols which +can occur after A in a parsing expression derived from the start +expression.

    7. +

  7. A nonterminal (or parsing expression) is called nullable if the +empty sentence can be derived from it.

    8. +
+

And based on the above definitions for grammars:

+
    +

  1. A grammar G is recursive if and only if it contains a nonterminal +A which is recursive. The terms left- and right-recursive, +and useful are analogously defined.

    2. +

  2. A grammar is minimal if it contains only reachable and +useful nonterminals.

    3. +

  3. A grammar is wellformed if it is not left-recursive. Such +grammars are also complete, which means that they always succeed +or fail on all input sentences. For an incomplete grammar on the +other hand input sentences exist for which an attempt to match them +against the grammar will not terminate.

    4. +

  4. As we wish to allow ourselves to build a grammar incrementally in a +container object we will encounter stages where the RHS of one or more +rules reference symbols which are not yet known to the container. Such +a grammar we call invalid. +We cannot use the term incomplete as this term is already +taken, see the last item.

    5. +
+
+

CONTAINER CLASS API

+

The package exports the API described here.

+
+
::grammar::peg pegName ?=|:=|<--|as|deserialize src?
+

The command creates a new container object for a parsing expression +grammar and returns the fully qualified name of the object command as +its result. The API the returned command is following is described in +the section CONTAINER OBJECT API. It may be used to invoke +various operations on the container and the grammar within.

+

The new container, i.e. grammar will be empty if no src is +specified. Otherwise it will contain a copy of the grammar contained +in the src. +The src has to be a container object reference for all operators +except deserialize. +The deserialize operator requires src to be the +serialization of a parsing expression grammar instead.

+

An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is valid, but not +useful.

+
+
+

CONTAINER OBJECT API

+

All grammar container objects provide the following methods for the +manipulation of their contents:

+
+
pegName destroy
+

Destroys the grammar, including its storage space and associated +command.

+
pegName clear
+

Clears out the definition of the grammar contained in pegName, +but does not destroy the object.

+
pegName = srcPEG
+

Assigns the contents of the grammar contained in srcPEG to +pegName, overwriting any existing definition. +This is the assignment operator for grammars. It copies the grammar +contained in the grammar object srcPEG over the grammar +definition in pegName. The old contents of pegName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    pegName deserialize [srcPEG serialize]
+
+
+
pegName --> dstPEG
+

This is the reverse assignment operator for grammars. It copies the +automation contained in the object pegName over the grammar +definition in the object dstPEG. +The old contents of dstPEG are deleted by this operation.

+

This operation is in effect equivalent to

+
+    dstPEG deserialize [pegName serialize]
+
+
+
pegName serialize
+

This method serializes the grammar stored in pegName. In other +words it returns a tcl value completely describing that +grammar. +This allows, for example, the transfer of grammars over arbitrary +channels, persistence, etc. +This method is also the basis for both the copy constructor and the +assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the grammar::peg interface. This is what +will enable us to copy grammars between different implementations of +the same interface.

+

The result is a list of four elements with the following structure:

+
    +

  1. The constant string grammar::peg.

    2. +

  2. A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values are the parsing expressions describing +their sentennial structure.

    3. +

  3. A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values hints to a matcher regarding the semantic +values produced by the symbol.

    4. +

  4. The last item is a parsing expression, the start expression +of the grammar.

    5. +
+

Assuming the following PEG for simple mathematical expressions

+
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
+    Sign       <- '+' / '-'
+    Number     <- Sign? Digit+
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)
+    MulOp      <- '*' / '/'
+    Factor     <- Term (AddOp Term)*
+    AddOp      <- '+'/'-'
+    Term       <- Number
+
+

a possible serialization is

+
+    grammar::peg \\
+    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
+     Factor     {x Term {* {x AddOp Term}}} \\
+     Term       Number \\
+     MulOp      {/ * /} \\
+     AddOp      {/ + -} \\
+     Number     {x {? Sign} {+ Digit}} \\
+     Sign       {/ + -} \\
+     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
+    } \\
+    {Expression value     Factor     value \\
+     Term       value     MulOp      value \\
+     AddOp      value     Number     value \\
+     Sign       value     Digit      value \\
+    }
+    Expression
+
+

A possible one, because the order of the nonterminals in the +dictionary is not relevant.

+
pegName deserialize serialization
+

This is the complement to serialize. It replaces the grammar +definition in pegName with the grammar described by the +serialization value. The old contents of pegName are +deleted by this operation.

+
pegName is valid
+

A predicate. It tests whether the PEG in pegName is valid. +See section TERMS & CONCEPTS for the definition of this +grammar property. +The result is a boolean value. It will be set to true if +the PEG has the tested property, and false otherwise.

+
pegName start ?pe?
+

This method defines the start expression of the grammar. It +replaces the previously defined start expression with the parsing +expression pe. +The method fails and throws an error if pe does not contain a +valid parsing expression as specified in the section +PARSING EXPRESSIONS. In that case the existing start +expression is not changed. +The method returns the empty string as its result.

+

If the method is called without an argument it will return the currently +defined start expression.

+
pegName nonterminals
+

Returns the set of all nonterminal symbols known to the grammar.

+
pegName nonterminal add nt pe
+

This method adds the nonterminal nt and its associated parsing +expression pe to the set of nonterminal symbols and rules of the +PEG contained in the object pegName. +The method fails and throws an error if either the string nt is +already known as a symbol of the grammar, or if pe does not +contain a valid parsing expression as specified in the section +PARSING EXPRESSIONS. In that case the current set of +nonterminal symbols and rules is not changed. +The method returns the empty string as its result.

+
pegName nonterminal delete nt1 ?nt2 ...?
+

This method removes the named symbols nt1, nt2 from the +set of nonterminal symbols of the PEG contained in the object +pegName. +The method fails and throws an error if any of the strings is not +known as a nonterminal symbol. In that case the current set of +nonterminal symbols is not changed. +The method returns the empty string as its result.

+

The stored grammar becomes invalid if the deleted nonterminals are +referenced by the RHS of still-known rules.

+
pegName nonterminal exists nt
+

A predicate. It tests whether the nonterminal symbol nt is known +to the PEG in pegName. +The result is a boolean value. It will be set to true if the +symbol nt is known, and false otherwise.

+
pegName nonterminal rename nt ntnew
+

This method renames the nonterminal symbol nt to ntnew. +The method fails and throws an error if either nt is not known +as a nonterminal, or if ntnew is a known symbol. +The method returns the empty string as its result.

+
pegName nonterminal mode nt ?mode?
+

This mode returns or sets the semantic mode associated with the +nonterminal symbol nt. If no mode is specified the +current mode of the nonterminal is returned. Otherwise the current +mode is set to mode. +The method fails and throws an error if nt is not known as a +nonterminal. +The grammar interpreter implemented by the package +grammar::peg::interpreter recognizes the +following modes:

+
+
value
+

The semantic value of the nonterminal is the abstract syntax tree +created from the AST's of the RHS and a node for the nonterminal +itself.

+
match
+

The semantic value of the nonterminal is an the abstract syntax tree +consisting of single a node for the string matched by the RHS. The ASTs +generated by the RHS are discarded.

+
leaf
+

The semantic value of the nonterminal is an the abstract syntax tree +consisting of single a node for the nonterminal itself. The ASTs +generated by the RHS are discarded.

+
discard
+

The nonterminal has no semantic value. The ASTs generated by the RHS +are discarded (as well).

+
+
pegName nonterminal rule nt
+

This method returns the parsing expression associated with the +nonterminal nt. +The method fails and throws an error if nt is not known as a +nonterminal.

+
pegName unknown nonterminals
+

This method returns a list containing the names of all nonterminal +symbols which are referenced on the RHS of a grammatical rule, but +have no rule definining their structure. In other words, a list of +the nonterminal symbols which make the grammar invalid. The grammar +is valid if this list is empty.

+
+
+

PARSING EXPRESSIONS

+

Various methods of PEG container objects expect a parsing expression +as their argument, or will return such. This section specifies the +format such parsing expressions are in.

+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string alnum is an atomic parsing expression. It matches +any alphanumeric character.

    3. +

  3. The string alpha is an atomic parsing expression. It matches +any alphabetical character.

    4. +

  4. The string dot is an atomic parsing expression. It matches +any character.

    5. +

  5. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    6. +

  6. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    7. +

  7. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    8. +

  8. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    9. +

  9. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    10. +

  10. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    11. +

  11. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    12. +

  12. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    13. +

  13. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    14. +
+

Examples of parsing expressions where already shown, in the +description of the method serialize.

+
+
+

PARSING EXPRESSION GRAMMARS

+

For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where

+
    +

  • VN is a set of nonterminal symbols,

    • +

  • VT is a set of terminal symbols,

    • +

  • R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and e a parsing expression.

    • +

  • eS is a parsing expression, the start expression.

    • +
+

Further constraints are

+
    +

  • The intersection of VN and VT is empty.

    • +

  • For all A in VT exists exactly one pair (A,e) in R. In other words, R +is a function from nonterminal symbols to parsing expressions.

    • +
+

Parsing expression are inductively defined via

+
    +

  • The empty string (epsilon) is a parsing expression.

    • +

  • A terminal symbol a is a parsing expression.

    • +

  • A nonterminal symbol A is a parsing expression.

    • +

  • e1e2 is a parsing expression for parsing expressions +e1 and 2. This is called sequence.

    • +

  • e1/e2 is a parsing expression for parsing expressions +e1 and 2. This is called ordered choice.

    • +

  • e* is a parsing expression for parsing expression +e. This is called zero-or-more repetitions, also known +as kleene closure.

    • +

  • e+ is a parsing expression for parsing expression +e. This is called one-or-more repetitions, also known +as positive kleene closure.

    • +

  • !e is a parsing expression for parsing expression +e1. This is called a not lookahead predicate.

    • +

  • &e is a parsing expression for parsing expression +e1. This is called an and lookahead predicate.

    • +
+

PEGs are used to define a grammatical structure for streams of symbols +over VT. They are a modern phrasing of older formalisms invented by +Alexander Birham. These formalisms were called TS (TMG recognition +scheme), and gTS (generalized TS). Later they were renamed to TPDL +(Top-Down Parsing Languages) and gTPDL (generalized TPDL).

+

They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars.

+
+

REFERENCES

+
    +

  1. The Packrat Parsing and Parsing Expression Grammars Page, +by Bryan Ford, Massachusetts Institute of Technology. This is the main +entry page to PEGs, and their realization through Packrat Parsers.

    2. +

  2. Parsing Techniques - A Practical Guide , an online book +offering a clear, accessible, and thorough discussion of many +different parsing techniques with their interrelations and +applicabilities, including error recovery techniques.

    3. +

  3. Compilers and Compiler Generators, an online book using +CoCo/R, a generator for recursive descent parsers.

    4. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_peg of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html @@ -0,0 +1,212 @@ + + +grammar::peg::interp - Grammar operations and usage + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::peg::interp - Interpreter for parsing expression grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require grammar::mengine ?0.1?
    • +
  • package require grammar::peg::interp ?0.1.1?
    • +
+ +
+
+

Description

+

This package provides commands for the controlled matching of a +character stream via a parsing expression grammar and the creation +of an abstract syntax tree for the stream and partials.

+

It is built on top of the virtual machine provided by the package +grammar::me::tcl and directly interprets the parsing +expression grammar given to it. +In other words, the grammar is not pre-compiled but used as is.

+

The grammar to be interpreted is taken from a container object +following the interface specified by the package +grammar::peg::container. Only the relevant parts +are copied into the state of this package.

+

It should be noted that the package provides exactly one instance +of the interpreter, and interpreting a second grammar requires +the user to either abort or complete a running interpretation, or +to put them into different Tcl interpreters.

+

Also of note is that the implementation assumes a pull-type +handling of the input. In other words, the interpreter pulls +characters from the input stream as it needs them. For usage +in a push environment, i.e. where the environment pushes new +characters as they come we have to put the engine into its +own thread.

+
+

THE INTERPRETER API

+

The package exports the following API

+
+
::grammar::peg::interp::setup peg
+

This command (re)initializes the interpreter. It returns the +empty string. This command has to be invoked first, before any +matching run.

+

Its argument peg is the handle of an object containing the +parsing expression grammar to interpret. This grammar has to be +valid, or an error will be thrown.

+
::grammar::peg::interp::parse nextcmd errorvar astvar
+

This command interprets the loaded grammar and tries to match it +against the stream of characters represented by the command prefix +nextcmd.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the interpreter whenever the a new +character from the stream is required. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The result of the command is a boolean value indicating whether the +matching process was successful (true), or not +(false). In the case of a match failure error information will +be stored into the variable referenced by errorvar. The variable +referenced by astvar will always contain the generated abstract +syntax tree, however in the case of an error it will be only partial +and possibly malformed.

+

The abstract syntax tree is represented by a nested list, as +described in section AST VALUES of +document grammar::me_ast.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_peg of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/hook/hook.html Index: embedded/www/tcllib/files/modules/hook/hook.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/hook/hook.html @@ -0,0 +1,415 @@ + + +hook - Hooks + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

hook(n) 0.1 tcllib "Hooks"

+

Name

+

hook - Hooks

+
+ + +

Description

+

This package provides the hook ensemble command, which +implements the Subject/Observer pattern. It allows subjects, +which may be modules, objects, widgets, and so +forth, to synchronously call hooks which may be bound to an +arbitrary number of subscribers, called observers. A subject +may call any number of distinct hooks, and any number of observers can +bind callbacks to a particular hook called by a particular +subject. Hook bindings can be queried and deleted.

+

This man page is intended to be a reference only.

+
+

Concepts

+

Introduction

+

Tcl modules usually send notifications to other modules in two ways: +via Tk events, and via callback options like the text widget's +-yscrollcommand option. Tk events are available only in Tk, +and callback options require tight coupling between the modules +sending and receiving the notification.

+

Loose coupling between sender and receiver is often desirable, +however. In Model/View/Controller terms, a View can send a command +(stemming from user input) to the Controller, which updates the +Model. The Model can then call a hook to which all relevant +Views subscribe. The Model is decoupled from the Views, and indeed +need not know whether any Views actually exist. +At present, Tcl/Tk has no standard mechanism for implementing loose +coupling of this kind. This package defines a new command, hook, +which implements just such a mechanism.

+
+

Bindings

+

The hook command manages a collection of hook bindings. A hook +binding has four elements:

+
    +

  1. A subject: the name of the entity that will be calling the +hook.

    2. +

  2. The hook itself. A hook usually reflects some occurrence in the +life of the subject that other entities might care to know +about. A hook has a name, and may also have arguments. Hook +names are arbitrary strings. Each subject must document the +names and arguments of the hooks it can call.

    3. +

  3. The name of the observer that wishes to receive the hook +from the subject.

    4. +

  4. A command prefix to which the hook arguments will be appended +when the binding is executed.

    5. +
+
+

Subjects and observers

+

For convenience, this document collectively refers to subjects and +observers as objects, while placing no requirements on how +these objects are actually implemented. An object can be a +TclOO or Snit or XOTcl object, a Tcl +command, a namespace, a module, a pseudo-object managed by some other +object (as tags are managed by the Tk text widget) or simply a +well-known name.

+

Subject and observer names are arbitrary strings; however, as +hook might be used at the package level, it's necessary to have +conventions that avoid name collisions between packages written by +different people.

+

Therefore, any subject or observer name used in core or package level +code should look like a Tcl command name, and should be defined in a +namespace owned by the package. Consider, for example, an ensemble +command ::foo that creates a set of pseudo-objects and uses +hook to send notifications. The pseudo-objects have names +that are not commands and exist in their own namespace, rather like +file handles do. To avoid name collisions with subjects defined by +other packages, users of hook, these ::foo handles +should have names like ::foo::1, ::foo::2, and so on.

+

Because object names are arbitrary strings, application code can use +whatever additional conventions are dictated by the needs of the +application.

+
+
+

Reference

+

Hook provides the following commands:

+
+
hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
+

This subcommand is used to create, update, delete, and query hook +bindings.

+

Called with no arguments it returns a list of the subjects with +hooks to which observers are currently bound.

+

Called with one argument, a subject, it returns a list of +the subject's hooks to which observers are currently bound.

+

Called with two arguments, a subject and a hook, it +returns a list of the observers which are currently bound to this +subject and hook.

+

Called with three arguments, a subject, a hook, and +an observer, it returns the binding proper, the command prefix +to be called when the hook is called, or the empty string if there is +no such binding.

+

Called with four arguments, it creates, updates, or deletes a +binding. If cmdPrefix is the empty string, it deletes any +existing binding for the subject, hook, and +observer; nothing is returned. Otherwise, cmdPrefix must +be a command prefix taking as many additional arguments as are +documented for the subject and hook. The binding is added +or updated, and the observer is returned.

+

If the observer is the empty string, "", it will create a +new binding using an automatically generated observer name of the form +::hook::ob<number>. The automatically generated name +will be returned, and can be used to query, update, and delete the +binding as usual. If automated observer names are always used, the +observer name effectively becomes a unique binding ID.

+

It is possible to call hook bind to create or delete a +binding to a subject and hook while in an observer binding +for that same subject and hook. The following rules +determine what happens when

+
+    hook bind $s $h $o $binding
+
+

is called during the execution of

+
+    hook call $s $h
+
+
    +

  1. No binding is ever called after it is deleted.

    2. +

  2. When a binding is called, the most recently given command prefix is +always used.

    3. +

  3. The set of observers whose bindings are to be called is determined +when this method begins to execute, and does not change thereafter, +except that deleted bindings are not called.

    4. +
+

In particular:

+
    +

  1. If $os binding to $s and $h is deleted, and +$os binding has not yet been called during this execution of

    +
    +    hook call $s $h
+
    +

    it will not be called. (Note that it might already have been called; +and in all likelihood, it is probably deleting itself.)

    2. +

  2. If $o changes the command prefix that's bound to $s and +$h, and if $os binding has not yet been called during +this execution of

    +
    +    hook call $s $h
+
    +

    the new binding will be called when the time comes. (But again, it is +probably $os binding that is is making the change.)

    3. +

  3. If a new observer is bound to $s and $h, its binding will +not be called until the next invocation of

    +
    +    hook call $s $h
+
    +
    4. +
+
hook call subject hook ?args...?
+

This command is called when the named subject wishes to call the +named hook. All relevant bindings are called with the specified +arguments in the global namespace. Note that the bindings are called +synchronously, before the command returns; this allows the args +to include references to entities that will be cleaned up as soon as +the hook has been called.

+

The order in which the bindings are called is not guaranteed. If +sequence among observers must be preserved, define one observer and +have its bindings call the other callbacks directly in the proper +sequence.

+

Because the hook mechanism is intended to support loose +coupling, it is presumed that the subject has no knowledge of +the observers, nor any expectation regarding return values. This has a +number of implications:

+
    +

  1. hook call returns the empty string.

    2. +

  2. Normal return values from observer bindings are ignored.

    3. +

  3. Errors and other exceptional returns propagate normally by +default. This will rarely be what is wanted, because the subjects +usually have no knowledge of the observers and will therefore have no +particular competence at handling their errors. That makes it an +application issue, and so applications will usually want to define an +-errorcommand.

    4. +
+

If the -errorcommand configuration option has a non-empty +value, its value will be invoked for all errors and other exceptional +returns in observer bindings. See hook configure, below, for +more information on configuration options.

+
hook forget object
+

This command deletes any existing bindings in which the named +object appears as either the subject or the +observer. +Bindings deleted by this method will never be called again. In +particular,

+
    +

  1. If an observer is forgotten during a call to hook call, any +uncalled binding it might have had to the relevant subject and hook +will not be called subsequently.

    2. +

  2. If a subject $s is forgotten during a call to

    +
    hook call $s $h
    +

    then hook call will return as soon as the current binding +returns. No further bindings will be called.

    3. +
+
hook cget option
+

This command returns the value of one of the hook command's +configuration options.

+
hook configure option value ...
+

This command sets the value of one or more of the hook command's +configuration options:

+
+
-errorcommand cmdPrefix
+

If the value of this option is the empty string, "", then errors +and other exception returns in binding scripts are propagated +normally. Otherwise, it must be a command prefix taking three +additional arguments:

+
    +

  1. a 4-element list {subject hook arglist observer},

    2. +

  2. the result string, and

    3. +

  3. the return options dictionary.

    4. +
+

Given this information, the -errorcommand can choose to log +the error, call interp bgerror, delete the errant binding +(thus preventing the error from arising a second time) and so forth.

+
-tracecommand cmdPrefix
+

The option's value should be a command prefix taking four +arguments:

+
    +

  1. a subject,

    2. +

  2. a hook,

    3. +

  3. a list of the hook's argument values, and

    4. +

  4. a list of objects the hook was called for.

    5. +
+

The command will be called for each hook that is called. This allows +the application to trace hook execution for debugging purposes.

+
+
+
+

Example

+

The ::model module calls the <Update> hook in response to +commands that change the model's data:

+
+     hook call ::model <Update>
+
+

The .view megawidget displays the model state, and needs to +know about model updates. Consequently, it subscribes to the ::model's +<Update> hook.

+
+     hook bind ::model <Update> .view [list .view ModelUpdate]
+
+

When the ::model calls the hook, the .views +ModelUpdate subcommand will be called.

+

Later the .view megawidget is destroyed. In its destructor, +it tells the hook that it no longer exists:

+
+     hook forget .view
+
+

All bindings involving .view are deleted.

+
+

Credits

+

Hook has been designed and implemented by William H. Duquette.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category hook of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/html/html.html Index: embedded/www/tcllib/files/modules/html/html.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/html/html.html @@ -0,0 +1,460 @@ + + +html - HTML Generation + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

html(n) 1.4 tcllib "HTML Generation"

+

Name

+

html - Procedures to generate HTML structures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require html ?1.4?
    • +
+ +
+
+

Description

+

The package html provides commands that generate HTML. +These commands typically return an HTML string as their result. In +particular, they do not output their result to stdout.

+

The command ::html::init should be called early to initialize +the module. You can also use this procedure to define default values +for HTML tag parameters.

+
+
::html::author author
+

Side effect only. Call this before ::html::head to +define an author for the page. The author is noted in a comment in +the HEAD section.

+
::html::bodyTag args
+

Generate a body tag. The tag parameters are taken from args or +from the body.* attributes define with ::html::init.

+
::html::cell param value ?tag?
+

Generate a td (or th) tag, a value, and a closing +td (or th) tag. The +tag parameters come from param or TD.* attributes defined with +::html::init. This uses ::html::font to insert a standard +font tag into the table cell. The tag argument defaults to "td".

+
::html::checkbox name value
+

Generate a checkbox form element with the specified name and value. +This uses ::html::checkValue.

+
::html::checkSet key sep list
+

Generate a set of checkbox form elements and associated labels. The +list should contain an alternating list of labels and values. +This uses ::html::checkbox. All the checkbox buttons share the +same key for their name. The sep is text used to separate +the elements.

+
::html::checkValue name ?value?
+

Generate the "name=name value=value for a checkbox form +element. If the CGI variable name has the value value, +then SELECTED is added to the return value. value defaults to +"1".

+
::html::closeTag
+

Pop a tag off the stack created by ::html::openTag and generate +the corresponding close tag (e.g., </body>).

+
::html::default key ?param?
+

This procedure is used by ::html::tagParam to generate the name, +value list of parameters for a tag. The ::html::default +procedure is used to generate default values for those items not +already in param. If the value identified by key matches +a value in param then this procedure returns the empty string. +Otherwise, it returns a "parameter=value" string for a form element +identified by key. The key has the form "tag.parameter" +(e.g., body.bgcolor). Use ::html::init to register default +values. param defaults to the empty string.

+
::html::description description
+

Side effect only. Call this before ::html::head to +define a description meta tag for the page. This tag is generated +later in the call to ::html::head.

+
::html::end
+

Pop all open tags from the stack and generate the corresponding close +HTML tags, (e.g., </body></html>).

+
::html::eval arg ?args?
+

This procedure is similar to the built-in Tcl eval command. The +only difference is that it returns "" so it can be called from an HTML +template file without appending unwanted results.

+
::html::extractParam param key ?varName?
+

This is a parsing procedure that extracts the value of key from +param, which is a HTML-style "name=quotedvalue" list. +varName is used as the name of a Tcl variable that is changed to +have the value found in the parameters. The function returns 1 if the +parameter was found in param, otherwise it returns 0. If the +varName is not specified, then key is used as the variable +name.

+
::html::font args
+

Generate a standard font tag. The parameters to the tag are taken +from args and the HTML defaults defined with ::html::init.

+
::html::for start test next body
+

This procedure is similar to the built-in Tcl for control +structure. Rather than evaluating the body, it returns the subst'ed +body. Each iteration of the loop causes another string to be +concatenated to the result value.

+
::html::foreach varlist1 list1 ?varlist2 list2 ...? body
+

This procedure is similar to the built-in Tcl foreach control +structure. Rather than evaluating the body, it returns the subst'ed +body. Each iteration of the loop causes another string to be +concatenated to the result value.

+
::html::formValue name ?defvalue?
+

Return a name and value pair, where the value is initialized from +existing CGI data, if any. The result has this form:

+
+  name="fred" value="freds value"
+
+
+
::html::getFormInfo args
+

Generate hidden fields to capture form values. If args is +empty, then hidden fields are generated for all CGI values. Otherwise +args is a list of string match patterns for form element names.

+
::html::getTitle
+

Return the title string, with out the surrounding title tag, +set with a previous call to ::html::title.

+
::html::h level string ?param?
+

Generate a heading (e.g., hlevel) tag. The string is nested in the +heading, and param is used for the tag parameters.

+
::html::h1 string ?param?
+

Generate an h1 tag. See ::html::h.

+
::html::h2 string ?param?
+

Generate an h2 tag. See ::html::h.

+
::html::h3 string ?param?
+

Generate an h3 tag. See ::html::h.

+
::html::h4 string ?param?
+

Generate an h4 tag. See ::html::h.

+
::html::h5 string ?param?
+

Generate an h5 tag. See ::html::h.

+
::html::h6 string ?param?
+

Generate an h6 tag. See ::html::h.

+
::html::hdrRow args
+

Generate a table row, including tr and th tags. +Each value in args is place into its own table cell. +This uses ::html::cell.

+
::html::head title
+

Generate the head section that includes the page title. +If previous calls have been made to +::html::author, +::html::keywords, +::html::description, +or +::html::meta +then additional tags are inserted into the head section. +This leaves an open html tag pushed on the stack with +::html::openTag.

+
::html::headTag string
+

Save a tag for inclusion in the head section generated by +::html::head. The string is everything in the tag except +the enclosing angle brackets, < >.

+
::html::html_entities string
+

This command replaces all special characters in the string with +their HTML entities and returns the modified text.

+
::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
+

This procedure is similar to the built-in Tcl if control +structure. Rather than evaluating the body of the branch that is +taken, it returns the subst'ed body. Note that the syntax is +slightly more restrictive than that of the built-in Tcl if +control structure.

+
::html::init ?list?
+

::html::init accepts a Tcl-style name-value list that defines +values for items with a name of the form "tag.parameter". For +example, a default with key "body.bgcolor" defines the background +color for the body tag.

+
::html::keywords args
+

Side effect only. Call this before ::html::head to +define a keyword meta tag for the page. The meta tag +is included in the result of ::html::head.

+
::html::mailto email ?subject?
+

Generate a hypertext link to a mailto: URL.

+
::html::meta args
+

Side effect only. Call this before ::html::head to +define a meta tag for the page. The args is a Tcl-style name, +value list that is used for the name= and value= parameters for the +meta tag. The meta tag is included in the result of +::html::head.

+
::html::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.

+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/htmlparse/htmlparse.html Index: embedded/www/tcllib/files/modules/htmlparse/htmlparse.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/htmlparse/htmlparse.html @@ -0,0 +1,318 @@ + + +htmlparse - HTML Parser + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

htmlparse(n) 1.2.1 tcllib "HTML Parser"

+

Name

+

htmlparse - Procedures to parse HTML strings

+
+ + +

Description

+

The htmlparse package provides commands that allow libraries +and applications to parse HTML in a string into a representation of +their choice.

+

The following commands are available:

+
+
::htmlparse::parse ?-cmd cmd? ?-vroot tag? ?-split n? ?-incvar var? ?-queue q? html
+

This command is the basic parser for HTML. It takes an HTML string, +parses it and invokes a command prefix for every tag encountered. It +is not necessary for the HTML to be valid for this parser to +function. It is the responsibility of the command invoked for every +tag to check this. Another responsibility of the invoked command is +the handling of tag attributes and character entities (escaped +characters). The parser provides the un-interpreted tag attributes to +the invoked command to aid in the former, and the package at large +provides a helper command, ::htmlparse::mapEscapes, to aid in +the handling of the latter. The parser does ignore leading +DOCTYPE declarations and all valid HTML comments it encounters.

+

All information beyond the HTML string itself is specified via +options, these are explained below.

+

To help understand the options, some more background information about +the parser.

+

It is capable of detecting incomplete tags in the HTML string given to +it. Under normal circumstances this will cause the parser to throw an +error, but if the option -incvar is used to specify a global (or +namespace) variable, the parser will store the incomplete part of the +input into this variable instead. This will aid greatly in the +handling of incrementally arriving HTML, as the parser will handle +whatever it can and defer the handling of the incomplete part until +more data has arrived.

+

Another feature of the parser are its two possible modes of +operation. The normal mode is activated if the option -queue is +not present on the command line invoking the parser. If it is present, +the parser will go into the incremental mode instead.

+

The main difference is that a parser in normal mode will immediately +invoke the command prefix for each tag it encounters. In incremental +mode however the parser will generate a number of scripts which invoke +the command prefix for groups of tags in the HTML string and then +store these scripts in the specified queue. It is then the +responsibility of the caller of the parser to ensure the execution of +the scripts in the queue.

+

Note: The queue object given to the parser has to provide the +same interface as the queue defined in tcllib -> struct. This means, +for example, that all queues created via that tcllib module can be +immediately used here. Still, the queue doesn't have to come from +tcllib -> struct as long as the same interface is provided.

+

In both modes the parser will return an empty string to the caller.

+

The -split option may be given to a parser in incremental mode to +specify the size of the groups it creates. In other words, -split 5 +means that each of the generated scripts will invoke the command +prefix for 5 consecutive tags in the HTML string. A parser in normal +mode will ignore this option and its value.

+

The option -vroot specifies a virtual root tag. A parser in +normal mode will invoke the command prefix for it immediately before +and after it processes the tags in the HTML, thus simulating that the +HTML string is enclosed in a <vroot> </vroot> combination. In +incremental mode however the parser is unable to provide the closing +virtual root as it never knows when the input is complete. In this +case the first script generated by each invocation of the parser will +contain an invocation of the command prefix for the virtual root as +its first command. +The following options are available:

+
+
-cmd cmd
+

The command prefix to invoke for every tag in the HTML +string. Defaults to ::htmlparse::debugCallback.

+
-vroot tag
+

The virtual root tag to add around the HTML in normal mode. In +incremental mode it is the first tag in each chunk processed by the +parser, but there will be no closing tags. Defaults to +hmstart.

+
-split n
+

The size of the groups produced by an incremental mode parser. Ignored +when in normal mode. Defaults to 10. Values <= 0 are not allowed.

+
-incvar var
+

The name of the variable where to store any incomplete HTML into. This +makes most sense for the incremental mode. The parser will throw an +error if it sees incomplete HTML and has no place to store it to. This +makes sense for the normal mode. Only incomplete tags are detected, +not missing tags. Optional, defaults to 'no variable'.

+
+
+
Interface to the command prefix
+

In normal mode the parser will invoke the command prefix with four +arguments appended. See ::htmlparse::debugCallback for a +description.

+

In incremental mode, however, the generated scripts will invoke the +command prefix with five arguments appended. The last four of these +are the same which were mentioned above. The first is a placeholder +string (@win@) for a clientdata value to be supplied later +during the actual execution of the generated scripts. This could be a +tk window path, for example. This allows the user of this package to +preprocess HTML strings without committing them to a specific window, +object, whatever during parsing. This connection can be made +later. This also means that it is possible to cache preprocessed +HTML. Of course, nothing prevents the user of the parser from +replacing the placeholder with an empty string.

+
+
::htmlparse::debugCallback ?clientdata? tag slash param textBehindTheTag
+

This command is the standard callback used by the parser in +::htmlparse::parse if none was specified by the user. It simply +dumps its arguments to stdout. This callback can be used for both +normal and incremental mode of the calling parser. In other words, it +accepts four or five arguments. The last four arguments are described +below. The optional fifth argument contains the clientdata value +passed to the callback by a parser in incremental mode. All callbacks +have to follow the signature of this command in the last four +arguments, and callbacks used in incremental parsing have to follow +this signature in the last five arguments.

+

The first argument, clientdata, is optional and present only if +this command is invoked by a parser in incremental mode. It contains +whatever the user of this package wishes.

+

The second argument, tag, contains the name of the tag which is +currently processed by the parser.

+

The third argument, slash, is either empty or contains a slash +character. It allows the callback to distinguish between opening +(slash is empty) and closing tags (slash contains a slash character).

+

The fourth argument, param, contains the un-interpreted list of +parameters to the tag.

+

The fifth and last argument, textBehindTheTag, contains the text +found by the parser behind the tag named in tag.

+
::htmlparse::mapEscapes html
+

This command takes a HTML string, substitutes all escape sequences +with their actual characters and then returns the resulting string. +HTML strings which do not contain escape sequences are returned +unchanged.

+
::htmlparse::2tree html tree
+

This command is a wrapper around ::htmlparse::parse which takes +an HTML string (in html) and converts it into a tree containing +the logical structure of the parsed document. The name of the tree is +given to the command as its second argument (tree). The command +does not generate the tree by itself but expects that the caller +provided it with an existing and empty tree. It also expects that the +specified tree object follows the same interface as the tree object in +tcllib -> struct. It doesn't have to be from tcllib -> struct, but it +must provide the same interface.

+

The internal callback does some basic checking of HTML validity and +tries to recover from the most basic errors. The command returns the +contents of its second argument. Side effects are the creation and +manipulation of a tree object.

+

Each node in the generated tree represent one tag in the input. The +name of the tag is stored in the attribute type of the +node. Any html attributes coming with the tag are stored unmodified in +the attribute data of the tag. In other words, the command does +not parse html attributes into their names and values.

+

If a tag contains text its node will have children of type +PCDATA containing this text. The text will be stored in the +attribute data of these children.

+
::htmlparse::removeVisualFluff tree
+

This command walks a tree as generated by ::htmlparse::2tree and +removes all the nodes which represent visual tags and not structural +ones. The purpose of the command is to make the tree easier to +navigate without getting bogged down in visual information not +relevant to the search. Its only argument is the name of the tree to +cut down.

+
::htmlparse::removeFormDefs tree
+

Like ::htmlparse::removeVisualFluff this command is here to cut +down on the size of the tree as generated by +::htmlparse::2tree. It removes all nodes representing forms and +form elements. Its only argument is the name of the tree to cut down.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category htmlparse of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/http/autoproxy.html Index: embedded/www/tcllib/files/modules/http/autoproxy.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/http/autoproxy.html @@ -0,0 +1,300 @@ + +autoproxy - HTTP protocol helper modules + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

autoproxy(n) 1.5.3 tcllib "HTTP protocol helper modules"

+

Name

+

autoproxy - Automatic HTTP proxy usage and authentication

+
+ + +

Description

+

This package attempts to automate the use of HTTP proxy servers in Tcl +HTTP client code. It tries to initialize the web access settings from +system standard locations and can be configured to negotiate +authentication with the proxy if required.

+

On Unix the standard for identifying the local HTTP proxy server +seems to be to use the environment variable http_proxy or ftp_proxy and +no_proxy to list those domains to be excluded from proxying. +On Windows we can retrieve the Internet Settings values from the registry +to obtain pretty much the same information. +With this information we can setup a suitable filter procedure for the +Tcl http package and arrange for automatic use of the proxy.

+

There seem to be a number of ways that the http_proxy environment +variable may be set up. Either a plain host:port or more commonly a +URL and sometimes the URL may contain authentication parameters or +these may be requested from the user or provided via http_proxy_user +and http_proxy_pass. This package attempts to deal with all these +schemes. It will do it's best to get the required parameters from the +environment or registry and if it fails can be reconfigured.

+
+

COMMANDS

+
+
::autoproxy::init
+

Initialize the autoproxy package from system resources. Under unix +this means we look for environment variables. Under windows we look +for the same environment variables but also look at the registry +settings used by Internet Explorer.

+
::autoproxy::cget -option
+

Retrieve individual package configuration options. See OPTIONS.

+
::autoproxy::configure ?-option value?
+

Configure the autoproxy package. Calling configure with no +options will return a list of all option names and values. +See OPTIONS.

+
::autoproxy::tls_connect args
+

Connect to a secure socket through a proxy. HTTP proxy servers permit +the use of the CONNECT HTTP command to open a link through the proxy +to the target machine. This function hides the details. For use with +the http package see tls_socket.

+

The args list may contain any of the tls package options but +must end with the host and port as the last two items.

+
::autoproxy::tunnel_connect args
+

Connect to a target host throught a proxy. This uses the same CONNECT +HTTP command as the tls_connect but does not promote the link +security once the connection is established.

+

The args list may contain any of the tls package options but +must end with the host and port as the last two items.

+

Note that many proxy servers will permit CONNECT calls to a limited +set of ports - typically only port 443 (the secure HTTP port).

+
::autoproxy::tls_socket args
+

This function is to be used to register a proxy-aware secure socket +handler for the https protocol. It may only be used with the Tcl http +package and should be registered using the http::register command (see +the examples below). The job of actually creating the tunnelled +connection is done by the tls_connect command and this may be used +when not registering with the http package.

+
+
+

OPTIONS

+
+
-host hostname
+
+
-proxy_host hostname
+

Set the proxy hostname. This is normally set up by init but may +be configured here as well.

+
-port number
+
+
-proxy_port number
+

Set the proxy port number. This is normally set up by init. +e.g. configure -port 3128

+
-no_proxy list
+

You may manipulate the no_proxy list that was setup by +init. The value of this option is a tcl list of +strings that are matched against the http request host using the tcl +string match command. Therefore glob patterns are permitted. +For instance, configure -no_proxy *.localdomain

+
-authProc procedure
+

This option may be used to set an application defined procedure to be +called when configure -basic is called with either no or +insufficient authentication details. This can be used to present a +dialog to the user to request the additional information.

+
-basic
+

Following options are for configuring the Basic authentication +scheme parameters. See Basic Authentication.

+
+
+

Basic Authentication

+

Basic is the simplest and most commonly use HTTP proxy authentication +scheme. It is described in (1 section 11) and also in (2). It offers +no privacy whatsoever and its use should be discouraged in favour of +more secure alternatives like Digest. To perform Basic authentication +the client base64 encodes the username and plaintext password +separated by a colon. This encoded text is prefixed with the word +"Basic" and a space.

+

The following options exists for this scheme:

+
+
-username name
+

The username required to authenticate with the configured proxy.

+
-password password
+

The password required for the username specified.

+
-realm realm
+

This option is not used.

+
+
+

EXAMPLES

+
+package require autoproxy
+autoproxy::init
+autoproxy::configure -basic -username ME -password SEKRET
+set tok [http::geturl http://wiki.tcl.tk/]
+http::data $tok
+
+
+package require http
+package require tls
+package require autoproxy
+autoproxy::init
+http::register https 443 autoproxy::tls_socket
+set tok [http::geturl https://www.example.com/]
+
+
+

REFERENCES

+
    +

  1. Berners-Lee, T., Fielding R. and Frystyk, H. + "Hypertext Transfer Protocol -- HTTP/1.0", + RFC 1945, May 1996, + (http://www.rfc-editor.org/rfc/rfc1945.txt)

    2. +

  2. Franks, J. et al. + "HTTP Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999 + (http://www.rfc-editor.org/rfc/rfc2617.txt)

    3. +
+
+

BUGS

+

At this time only Basic authentication (1) (2) is supported. It is +planned to add support for Digest (2) and NTLM in the future.

+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category http :: autoproxy of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

http(n)

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ident/ident.html Index: embedded/www/tcllib/files/modules/ident/ident.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ident/ident.html @@ -0,0 +1,179 @@ + + +ident - Identification protocol client + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ident(n) 0.42 tcllib "Identification protocol client"

+

Name

+

ident - Ident protocol client

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require ident ?0.42?
    • +
+ +
+
+

Description

+

The ident package provides a client implementation of the ident +protocol as defined in +RFC 1413 (http://www.rfc-editor.org/rfc/rfc1413.txt).

+
+
::ident::query socket ?callback?
+

This command queries the ident daemon on the remote side of the given +socket, and returns the result of the query as a dictionary. +Interpreting the dictionary as list the first key will always be +resp-type, and can have one of the values USERID, +ERROR, and FATAL. These response types have +the following meanings:

+
+
USERID
+

This indicates a successful response. Two more keys and associated +values are returned, opsys, and user-id.

+
ERROR
+

This means the ident server has returned an error. A second key named +error is present whose value contains the error-type +field from the server response.

+
FATAL
+

Fatal errors happen when no ident server is listening on the remote +side, or when the ident server gives a response that does not conform +to the RFC. A detailed error message is returned under the +error key.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ident of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/imap4/imap4.html Index: embedded/www/tcllib/files/modules/imap4/imap4.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/imap4/imap4.html @@ -0,0 +1,453 @@ + +imap4 - imap client + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

imap4(n) 0.4 tcllib "imap client"

+

Name

+

imap4 - imap client-side tcl implementation of imap protocol

+
+ + +

Description

+

The imap4 library package provides the client side of the +Internet Message Access Protocol (IMAP) using standard +sockets or secure connection via TLS/SSL. +The package is fully implemented in Tcl.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::imap4::open hostname ?port?
+

Open a new IMAP connection and initalize the handler, +the imap communication channel (handler) is returned.

+

hostname - mail server

+

port - connection port, defaults to 143

+

The namespace variable ::imap4::use_ssl +can be used to establish to a secure connection +via TSL/SSL if set to true. In this case default connection port +defaults to 993.

+

Note: +For connecting via SSL the Tcl module tls must be already +loaded otherwise an error is raised.

+
+    package require tls              ; # must be loaded for TLS/SSL   
+    set ::imap4::use_ssl 1           ; # request a secure connection
+    set chan [::imap4::open $server] ; # default port is now 993
+
+
::imap4::login chan user pass
+

Login using the IMAP LOGIN command, 0 is returned on successful login.

+

chan - imap channel

+

user - username

+

pass - password

+
::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
+

Get list of matching folders, 0 is returned on success.

+

Wildcards '*' as '%' are allowed for mboxref and mboxname, +command ::imap4::folderinfo can be used to retrieve folder information.

+

chan - imap channel

+

mboxref - mailbox reference, defaults to ""

+

mboxname - mailbox name, defaults to "*"

+

If -inline is specified a compact folderlist is +returned instead of the result code. All flags are converted to +lowercase and leading special characters are removed.

+
{{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}
+
+
::imap4::select chan ?mailbox?
+

Select a mailbox, 0 is returned on success.

+

chan - imap channel

+

mailbox - Path of the mailbox, defaults to INBOX

+

Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

+
::imap4::examine chan ?mailbox?
+

"Examines" a mailbox, read-only equivalent of ::imap4::select.

+

chan - imap channel

+

mailbox - mailbox name or path to mailbox, +defaults to INBOX

+

Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

+
::imap4::fetch chan range ?-inline? ?attr ...?
+

Fetch attributes from messages.

+

The attributes are fetched and stored in the internal state +which can be retrieved with command ::imap4::msginfo, 0 is returned +on success. +If -inline is specified, alle records are returned as list +in order as defined in the attr argument.

+

chan - imap channel

+

range - message index in format FROM:TO

+

attr - imap attributes to fetch

+

Note: +If FROM is omitted, the 1st message is assumed, +if TO is ommitted the last message is assumed. +All message index ranges are 1-based.

+
::imap4::noop chan
+

Send NOOP command to server. May get information as untagged data.

+

chan - imap channel

+
::imap4::check chan
+

Send CHECK command to server. Flush to disk.

+

chan - imap channel

+
::imap4::folderinfo chan ?info?
+

Get information on the recently selected folderlist. +If the info argument is omitted or a null string, the full list +of information available for the mailbox is returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

info - folderlist options to retrieve

+

Currently supported options: +delim - hierarchy delimiter only, +match - ref and mbox search patterns (see ::imap4::folders), +names - list of folder names only, +flags - list of folder names with flags in format +{ {name {flags}} ... } (see also compact format in function +::imap4::folders).

+
+{{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
+
+
+
::imap4::msginfo chan msgid ?info? ?defval?
+

Get information (from previously collected using fetch) from a given +msgid. If the 'info' argument is omitted or a null string, +the list of available information options for the given message is +returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

msgid - message number

+

info - imap keyword to retrieve

+

defval - default value, returned if info is empty

+

Note: +All message index ranges are 1-based.

+
::imap4::mboxinfo chan ?info?
+

Get information on the currently selected mailbox. +If the info argument is omitted or a null string, the list +of available information options for the mailbox is returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

opt - mailbox option to retrieve

+

Currently supported options: +EXISTS (noof msgs), +RECENT (noof 'recent' flagged msgs), +FLAGS

+

In conjunction with OK: +PERMFLAGS, UIDNEXT, UIDVAL, UNSEEN

+

Div. states: +CURRENT, FOUND, PERM.

+
+    ::imap4::select $chan INBOX
+    puts "[::imap4::mboxinfo $chan exists] mails in INBOX"
+
+
::imap4::isableto chan ?capability?
+

Test for capability. +It returns 1 if requested capability is supported, 0 otherwise. +If capability is omitted all capability imap +codes are retured as list.

+

chan - imap channel

+

info - imap keyword to retrieve

+

Note: +Use the capability command to ask the server if not +already done by the user.

+
::imap4::create chan mailbox
+

Create a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::delete chan mailbox
+

Delete a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::rename chan oldname newname
+

Rename a new mailbox.

+

chan - imap channel

+

mailbox - old mailbox name

+

mailbox - new mailbox name

+
::imap4::subscribe chan mailbox
+

Subscribe a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::unsubscribe chan mailbox
+

Unsubscribe a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::search chan expr ?...?
+

Search for mails matching search criterions, 0 is returned on success.

+

chan - imap channel

+

expr - imap search expression

+

Notes: +Currently the following search expressions are handled:

+

Mail header flags: +all mail header entries (ending with a colon ":"), like "From:", "Bcc:", ...

+

Imap message search flags: +ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, +SEEN, NEW, OLD, UNANSWERED, UNDELETED, +UNDRAFT, UNFLAGGED, UNSEEN, ALL

+

Imap header search flags: +BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC

+

Imap conditional search flags: +SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE, SINCE, +BEFORE (not implemented), +UID (not implemented)

+

Logical search conditions: +OR, NOT

+
::imap4::search $chan larger 4000 seen
+puts "Found messages: [::imap4::mboxinfo $chan found]"
+Found messages: 1 3 6 7 8 9 13 14 15 19 20
+
+
::imap4::close chan
+

Close the mailbox. Permanently removes \Deleted messages and +return to the AUTH state.

+

chan - imap channel

+
::imap4::cleanup chan
+

Destroy an IMAP connection and free the used space. +Close the mailbox. Permanently removes \Deleted messages +and return to the AUTH state.

+

chan - imap channel

+
::imap4::debugmode chan ?errormsg?
+

Switch client into command line debug mode.

+

This is a developers mode only that pass the control to the +programmer. Every line entered is sent verbatim to the +server (after the addition of the request identifier). +The ::imap4::debug variable is automatically set to '1' on enter.

+

It's possible to execute Tcl commands starting the line +with a slash.

+

chan - imap channel

+

errormsg - optional error message to display

+
::imap4::store chan range data flaglist
+

Alters data associated with a message in the selected +mailbox.

+

chan - imap channel

+

range - message index in format FROM:TO

+

flaglist - Flags the data operates on.

+

data - The currently defined data items that can be +stored are shown below. Note that all of these data types may +also be suffixed with ".SILENT" to suppress the untagged FETCH +response.

+
+
FLAGS
+

Replace the flags for the message (other than \Recent) with the +flaglist.

+
+FLAGS
+

Add the flags in flaglist to the existing flags for the message.

+
-FLAGS
+

Remove the flags in flaglist to the existing flags for the +message.

+
+

For example:

+
+	::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
+
+
+
::imap4::expunge chan
+

Permanently removes all messages that have the \Deleted flag +set from the currently selected mailbox, without the need to close the +connection.

+

chan - imap channel

+
::imap4::logout chan
+

Informs the server that the client is done with the connection +and closes the network connection. Permanently removes \Deleted +messages.

+

A new connection will need to be established to login once +more.

+

chan - imap channel

+
+
+

EXAMPLES

+
+    set user myusername
+    set pass xtremescrt
+    set server imap.test.tld 
+    set FOLDER INBOX
+    # Connect to server
+    set imap [::imap4::open $server]
+    ::imap4::login $imap $user $pass
+    ::imap4::select $imap $FOLDER
+    # Output all the information about that mailbox
+    foreach info [::imap4::mboxinfo $imap] {
+        puts "$info -> [::imap4::mboxinfo $imap $info]"
+    }
+    # fetch 3 records inline 
+    set fields {from: to: subject: size}
+    foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
+        puts -nonewline "#[incr idx])"
+        for {set j 0} {$j<[llength $fields]} {incr j} {
+            puts "\t[lindex $fields $j] [lindex $rec $j]"
+        }
+    }
+    
+    # Show all the information available about the message ID 1
+    puts "Available info about message 1: [::imap4::msginfo $imap 1]"
+    
+    # Use the capability stuff
+    puts "Capabilities: [::imap4::isableto $imap]"
+    puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
+    
+    # Cleanup
+    ::imap4::cleanup $imap
+
+
+

REFERENCES

+

Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", +RFC 3501, March 2003, http://www.rfc-editor.org/rfc/rfc3501.txt

+

OpenSSL, http://www.openssl.org/

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Only a small part of rfc3501 implemented.

+

Please report such in the category imap4 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/inifile/ini.html Index: embedded/www/tcllib/files/modules/inifile/ini.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/inifile/ini.html @@ -0,0 +1,207 @@ + + +inifile - Parsing of Windows INI files + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

inifile(n) 0.2.5 tcllib "Parsing of Windows INI files"

+

Name

+

inifile - Parsing of Windows INI files

+
+ + +

Description

+

This package provides an interface for easy manipulation of Windows INI files.

+
+
::ini::open file ?access?
+

Opens an INI file and returns a handle that is used by other commands. +access is the same as the first form (non POSIX) of the open +command, with the exception that mode a is not supported. The +default mode is r+.

+
::ini::close ini
+

Close the specified handle. If any changes were made and not written by +commit they are lost.

+
::ini::commit ini
+

Writes the file and all changes to disk. The sections are written in +arbitrary order. The keys in a section are written in alphabetical +order. If the ini was opened in read only mode an error will be thrown.

+
::ini::revert ini
+

Rolls all changes made to the inifile object back to the last +committed state.

+
::ini::filename ini
+

Returns the name of the file the ini object is associated with.

+
::ini::sections ini
+

Returns a list of all the names of the existing sections in the file handle +specified.

+
::ini::keys ini section
+

Returns a list of all they key names in the section and file specified.

+
::ini::get ini section
+

Returns a list of key value pairs that exist in the section and file specified.

+
::ini::exists ini section ?key?
+

Returns a boolean value indicating the existance of the specified section as a +whole or the specified key within that section.

+
::ini::value ini section key ?default?
+

Returns the value of the named key and section. If specified, +the default value will be returned if the key does not exist. If the key does +not exist and no default is specified an error will be thrown.

+
::ini::set ini section key value
+

Sets the value of the key in the specified section. If the section does not +exist then a new one is created.

+
::ini::delete ini section ?key?
+

Removes the key or the entire section and all its keys. A section is not +automatically deleted when it has no remaining keys.

+
::ini::comment ini section ?key? ?text?
+

Reads and modifies comments for sections and keys. To write a section comment use an +empty string for the key. To remove all comments use an empty string for text. +text may consist of a list of lines or one single line. Any embedded newlines in +text are properly handled. Comments may be written to nonexistant +sections or keys and will not return an error. Reading a comment from a nonexistant +section or key will return an empty string.

+
::ini::commentchar ?char?
+

Reads and sets the comment character. Lines that begin with this character are treated as +comments. When comments are written out each line is preceded by this character. The default +is ;.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category inifile of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/interp/deleg_method.html Index: embedded/www/tcllib/files/modules/interp/deleg_method.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/interp/deleg_method.html @@ -0,0 +1,174 @@ + + +deleg_method - Interpreter utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

deleg_method(n) 0.2 tcllib "Interpreter utilities"

+

Name

+

deleg_method - Creation of comm delegates (snit methods)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require snit ?1.1?
    • +
  • package require interp::delegate::method ?0.2?
    • +
+ +
+
+

Description

+

This package provides a single command for use within snit +type definition (i.e. actually a snit::macro) for the convenient +creation of methods which delegate the actual work to a remote +location via a "channel" created by the package comm.

+
+

API

+
+
::interp::delegate::method ?-async? name arguments comm id
+

This commands creates a method which is named by name. All +invokations of this method will delegate the actual work to the remote +location identified by the comm channel comm and the endpoint +id.

+

The name of the remote method invoked by the delegator is identical to +the name of the method itself.

+

Normally the generated method marshalls the arguments, and +returns the result from the remote method as its own result. If +however the option -async was specified then the generated +method will not wait for a result and return immediately.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/interp/deleg_proc.html Index: embedded/www/tcllib/files/modules/interp/deleg_proc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/interp/deleg_proc.html @@ -0,0 +1,173 @@ + + +deleg_proc - Interpreter utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

deleg_proc(n) 0.2 tcllib "Interpreter utilities"

+

Name

+

deleg_proc - Creation of comm delegates (procedures)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require interp::delegate::proc ?0.2?
    • +
+ +
+
+

Description

+

This package provides a single command for the convenient creation of +procedures which delegate the actual work to a remote location via a +"channel" created by the package comm.

+
+

API

+
+
::interp::delegate::proc ?-async? name arguments comm id
+

This commands creates a procedure which is named by name and +returns its fully-qualified name. All invokations of this procedure +will delegate the actual work to the remote location identified by the +comm channel comm and the endpoint id.

+

The name of the remote procedure invoked by the delegator is +[namespace tail name]. I.e., namespace information is +stripped from the call.

+

Normally the generated procedure marshalls the arguments, and +returns the result from the remote procedure as its own result. If +however the option -async was specified then the generated +procedure will not wait for a result and return immediately.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/interp/tcllib_interp.html Index: embedded/www/tcllib/files/modules/interp/tcllib_interp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/interp/tcllib_interp.html @@ -0,0 +1,188 @@ + + +interp - Interpreter utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

interp(n) 0.1.2 tcllib "Interpreter utilities"

+

Name

+

interp - Interp creation and aliasing

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require interp ?0.1.2?
    • +
+ +
+
+

Description

+

This package provides a number of commands for the convenient creation +of Tcl interpreters for highly restricted execution.

+
+

API

+
+
::interp::createEmpty ?path?
+

This commands creates an empty Tcl interpreter and returns it +name. Empty means that the new interpreter has neither namespaces, nor +any commands. It is useful only for the creation of aliases.

+

If a path is specified then it is taken as the name of the new +interpreter.

+
::interp::snitLink path methodlist
+

This command assumes that it was called from within a method of a snit +object, and that the command mymethod is available.

+

It extends the interpreter specified by path with aliases for +all methods found in the methodlist, with the alias directing +execution to the same-named method of the snit object invoking this +command. +Each element of methodlist is actually interpreted as a command +prefix, with the first word of each prefix the name of the method to +link to.

+

The result of the command is the empty string.

+
::interp::snitDictLink path methoddict
+

This command behaves like ::interp::snitLink, except that it +takes a dictionary mapping from commands to methods as its input, and +not a list of methods. +Like for ::interp::snitLink the method references are actually +command prefixes. +This command allows the creation of more complex command-method +mappings than ::interp::snitLink.

+

The result of the command is the empty string.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/irc/irc.html Index: embedded/www/tcllib/files/modules/irc/irc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/irc/irc.html @@ -0,0 +1,322 @@ + + +irc - Low Level Tcl IRC Interface + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

irc(n) 0.6.1 tcllib "Low Level Tcl IRC Interface"

+

Name

+

irc - Create IRC connection and interface.

+
+ + +

Description

+

This package provides low-level commands to deal with the IRC protocol +(Internet Relay Chat) for immediate and interactive multi-cast +communication.

+
+
::irc::config ?key? ?value?
+

Sets configuration ?key? to ?value?. The configuration keys +currently defined are the boolean flags logger and debug. +logger makes irc use the logger package for printing +error. debug requires logger and prints extra debug output. +If no ?key? or ?value? is given the current values are returned.

+
::irc::connection
+

The command creates a new object to deal with an IRC connection. +Creating this IRC object does not automatically create the network +connection. It returns a new irc namespace command which can be used +to interact with the new IRC connection. NOTE: the old form of the +connection command, which took a hostname and port as arguments, is +deprecated. Use connect instead to specify this information.

+
::irc::connections
+

Returns a list of all the current connections that were created with +connection

+
+
+

Per-connection Commands

+

In the following list of available connection methods net +represents a connection command as returned by +::irc::connection.

+
+
net registerevent event script
+

Registers a callback handler for the specific event. Events available +are those described in RFC 1459 +http://www.rfc-editor.org/rfc/rfc1459.txt. +In addition, there are several other events defined. +defaultcmd adds a command that is called if no other callback +is present. EOF is called if the connection signals an End of +File condition. The events defaultcmd, defaultnumeric, +defaultevent, and EOF are required. +script is executed in the connection namespace, which can take +advantage of several commands (see Callback Commands +below) to aid in the parsing of data.

+
net getevent event script
+

Returns the current handler for the event if one exists. Otherwise an +empty string is returned.

+
net eventexists event script
+

Returns a boolean value indicating the existence of the event handler.

+
net connect hostname ?port?
+

This causes the socket to be established. ::irc::connection +created the namespace and the commands to be used, but did not +actually open the socket. This is done here. NOTE: the older form of +'connect' did not require the user to specify a hostname and port, +which were specified with 'connection'. That form is deprecated.

+
net config ?key? ?value?
+

The same as ::irc::config but sets and gets options for the net +connection only.

+
net log level message
+

If logger is turned on by config this will write a log message +at level.

+
net logname
+

Returns the name of the logger instance if logger is turned on.

+
net connected
+

Returns a boolean value indicating if this connection is connected to a server.

+
net sockname
+

Returns a 3 element list consisting of the ip address, the hostname, and the port +of the local end of the connection, if currently connected.

+
net peername
+

Returns a 3 element list consisting of the ip address, the hostname, and the port +of the remote end of the connection, if currently connected.

+
net socket
+

Return the Tcl channel for the socket used by the connection.

+
net user username localhostname localdomainname userinfo
+

Sends USER command to server. username is the username you want +to appear. localhostname is the host portion of your hostname, localdomainname +is your domain name, and userinfo is a short description of who you are. The 2nd and 3rd +arguments are normally ignored by the IRC server.

+
net nick nick
+

NICK command. nick is the nickname you wish to use for the +particular connection.

+
net ping target
+

Send a CTCP PING to target.

+
net serverping
+

PING the server.

+
net join channel ?key?
+

channel is the IRC channel to join. IRC channels typically +begin with a hashmark ("#") or ampersand ("&").

+
net part channel ?message?
+

Makes the client leave channel. Some networks may support the optional +argument message

+
net quit ?message?
+

Instructs the IRC server to close the current connection. The package +will use a generic default if no message was specified.

+
net privmsg target message
+

Sends message to target, which can be either a channel, or +another user, in which case their nick is used.

+
net notice target message
+

Sends a notice with message message to target, +which can be either a channel, or another user, in which case their nick is used.

+
net ctcp target message
+

Sends a CTCP of type message to target

+
net kick channel target ?message?
+

Kicks the user target from the channel channel with a message. +The latter can be left out.

+
net mode target args
+

Sets the mode args on the target target. target may be a channel, +a channel user, or yourself.

+
net topic channel message
+

Sets the topic on channel to message specifying an empty string +will remove the topic.

+
net invite channel target
+

Invites target to join the channel channel

+
net send text
+

Sends text to the IRC server.

+
net destroy
+

Deletes the connection and its associated namespace and information.

+
+
+

Callback Commands

+

These commands can be used within callbacks

+
+
who ?address?
+

Returns the nick of the user who performed a command. The optional +keyword address causes the command to return the user in the +format "username@address".

+
action
+

Returns the action performed, such as KICK, PRIVMSG, MODE, etc... +Normally not useful, as callbacks are bound to a particular event.

+
target
+

Returns the target of a particular command, such as the channel or +user to whom a PRIVMSG is sent.

+
additional
+

Returns a list of any additional arguments after the target.

+
header
+

Returns the entire event header (everything up to the :) as a proper list.

+
msg
+

Returns the message portion of the command (the part after the :).

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category irc of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

rfc 1459

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/irc/picoirc.html Index: embedded/www/tcllib/files/modules/irc/picoirc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/irc/picoirc.html @@ -0,0 +1,247 @@ + + +picoirc - Simple embeddable IRC interface + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

picoirc(n) 0.5 tcllib "Simple embeddable IRC interface"

+

Name

+

picoirc - Small and simple embeddable IRC client.

+
+ + +

Description

+

This package provides a general purpose minimal IRC client suitable for +embedding in other applications. All communication with the parent +application is done via an application provided callback procedure. +Each connection has its own state so you can hook up multiple servers +in a single application instance.

+

To initiate an IRC connection you must call picoirc::connect +with a callback procedure, a nick-name to use on IRC and the IRC URL +that describes the connection. This will return a variable name that +is the irc connection context. See CALLBACK for details.

+

This package is a fairly simple IRC client. If you need something with +more capability investigate the irc package.

+
+

COMMANDS

+
+
::picoirc::connect callback nick url
+

Create a new irc connection to the server specified by url and +login using the nick as the username. The callback must be +as specified in CALLBACK. Returns a package-specific variable +that is used when calling other commands in this package.

+
::picoirc::post context channel message
+

This should be called to process user input and send it to the +server. A number of commands are recognised when prefixed with a +forward-slash (/). Such commands are converted to IRC command +sequences and then sent.

+
::picoirc::splituri uri
+

Splits an IRC scheme uniform resource indicator into its component +parts. Returns a list of server, port and channel. The default port is +6667 and there is no default channel.

+
::picoirc::send context line
+

This command is where all raw output to the server is handled. The +default action is to write the line to the irc socket. However, +before this happens the callback is called with "debug write". This +permits the application author to inspect the raw IRC data and if +desired to return a break error code to halt further processing. In +this way the application can override the default send via the +callback procedure.

+
+
+

CALLBACK

+

The callback must look like:

+
+proc Callback {context state args} {
+}
+
+

where context is the irc context variable name (in case you need to pass +it back to a picoirc procedure). state is one of a number of states as +described below.

+
+
init
+

called just before the socket is created

+
connect
+

called once we have connected, before we join any channels

+
close
+

called when the socket gets closed, before the context is deleted. If +an error occurs before we get connected the only argument will be the +socket error message.

+
userlist channel nicklist
+

called to notify the application of an updated userlist. This is +generated when the output of the NAMES irc command is seen. The +package collects the entire output which can span a number of output +lines from the server and calls this callback when they have all been +received.

+
chat target nick message type
+

called when a message arrives. target is the identity that the +message was targetted for. This can be the logged in nick or a channel +name. nick is the name of the sender of the message. +message is the message text. type is set to "ACTION" if the +message was sent as a CTCP ACTION

+
system channel message
+

called when a system message is received

+
topic channel topic
+

called when the channel topic string is seen. topic is the text +of the channel topic.

+
traffic action channel nick ?newnick?
+

called when users join, leave or change names. +action is either entered, left or nickchange and nick +is the user doing the action. newnick is +the new name if action is nickchange.

+

NOTE: channel is often empty for these messages as nick +activities are global for the irc server. You will have +to manage the nick for all connected channels yourself.

+
version
+

This is called to request a version string to use to +override the internal version. If implemented, you should +return as colon delimited string as

+

Appname:Appversion:LibraryVersion

+

For example, the default is

+

PicoIRC:[package provide picoirc]:Tcl [info patchlevel]

+
debug type raw
+

called when data is either being read or written to the network +socket. type is set to read when reading data and +write if the data is to be written. raw is the +unprocessed IRC protocol data.

+

In both cases the application can return a break error code to +interrupt further processing of the raw data. If this is a +read operation then the package will not handle this line. If +the operation is write then the package will not send the +data. This callback is intended for debugging protocol issues but +could be used to redirect all input and output if desired.

+
+
+

See Also

+

rfc 1459

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/javascript/javascript.html Index: embedded/www/tcllib/files/modules/javascript/javascript.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/javascript/javascript.html @@ -0,0 +1,213 @@ + + +javascript - HTML and Java Script Generation + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

javascript(n) 1.0.2 tcllib "HTML and Java Script Generation"

+

Name

+

javascript - Procedures to generate HTML and Java Script structures.

+
+ + +

Description

+

The ::javascript package provides commands that generate +HTML and Java Script code. These commands typically return an HTML +string as their result. In particular, they do not output their +result to stdout.

+
+
::javascript::makeSelectorWidget id leftLabel leftValueList rightLabel rightValueList rightNameList ?length? ?minWidth?
+

Construct HTML code to create a dual-multi-selection megawidget. This +megawidget consists of two side-by-side multi-selection boxes +separated by a left arrow and a right arrow button. The right arrow +button moves all items selected in the left box to the right box. The +left arrow button moves all items selected in the right box to the +left box. The id argument is the suffix of all HTML objects in +this megawidget. The leftLabel argument is the text that +appears above the left selection box. The leftValueList +argument is the values of items in the left selection box. The +leftNameList argument is the names to appear in the left +selection box. The rightLabel argument is the text that appears +above the right selection box. The rightValueList argument is +the values of items in the right selection box. The +rightNameList argument is the names to appear in the right +selection box. The length argument (optional) determines the +number of elts to show before adding a vertical scrollbar; it defaults +to 8. The minWidth argument (optional) is the number of spaces +to determine the minimum box width; it defaults to 32.

+
::javascript::makeSubmitButton name value
+

Create an HTML submit button that resets a hidden field for each +registered multi-selection box. The name argument is the name +of the HTML button object to create. The value argument is the +label of the HTML button object to create.

+
::javascript::makeProtectedSubmitButton name value msg
+

Create an HTML submit button that prompts the user with a +continue/cancel shutdown warning before the form is submitted. The +name argument is the name of the HTML button object to create. +The value argument is the label of the HTML button object to +create. The msg argument is the message to display when the +button is pressed.

+
::javascript::makeMasterButton master value slavePattern boolean
+

Create an HTML button that sets its slave checkboxs to the boolean +value. The master argument is the name of the child's parent +html checkbox object. The value argument is the value of the +master. The slaves argument is the name of child html checkbox +object to create. The boolean argument is the java script +boolean value that will be given to all the slaves; it must be "true" +or "false".

+
::javascript::makeParentCheckbox parentName childName
+

Create an HTML checkbox and tie its value to that of its child +checkbox. If the parent is unchecked, the child is automatically +unchecked. The parentName argument is the name of parent html +checkbox object to create. The childName argument is the name of +the parent's child html checkbox object.

+
::javascript::makeChildCheckbox parentName childName
+

Create an HTML checkbox and tie its value to that of its parent +checkbox. If the child is checked, the parent is automatically +checked. The parentName argument is the name of the child's +parent html checkbox object. The childName argument is the name +of child html checkbox object to create.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category javascript of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/jpeg/jpeg.html Index: embedded/www/tcllib/files/modules/jpeg/jpeg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/jpeg/jpeg.html @@ -0,0 +1,291 @@ + +jpeg - JPEG image manipulation + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

jpeg(n) 0.4.0 tcllib "JPEG image manipulation"

+

Name

+

jpeg - JPEG querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query and modify JPEG images. JPEG +stands for Joint Photography Experts Group and is a standard +for the lossy compression of photographical images. It is specified at +LINK_HERE.

+
+

COMMANDS

+
+
::jpeg::isJPEG file
+

Returns a boolean value indicating if file is a +JPEG image.

+
::jpeg::imageInfo file
+

Returns a dictionary with keys version, units, +xdensity, ydensity, xthumb, and +ythumb. The values are the associated properties of the JPEG +image in file. +Throws an error if file is not a JPEG image.

+
::jpeg::dimensions file
+

Returns the dimensions of the JPEG file as a list of the +horizontal and vertical pixel count. +Throws an error if file is not a JPEG image.

+
::jpeg::getThumbnail file
+

This procedure will return the binary thumbnail image data, if a JPEG +thumbnail is included in file, and the empty string +otherwise. Note that it is possible to include thumbnails in formats +other than JPEG although that is not common. The command finds +thumbnails that are encoded in either the JFXX or EXIF segments of the +JPEG information. If both are present the EXIF thumbnail will take precedence. +Throws an error if file is not a JPEG image.

+
+    set fh [open thumbnail.jpg w+]
+    fconfigure $fh -translation binary -encoding binary
+    puts -nonewline $fh [::jpeg::getThumbnail photo.jpg]
+    close $fh
+
+
+
::jpeg::getExif file ?section?
+

section must be one of main or thumbnail. +The default is main. +Returns a dictionary containing the EXIF information for the specified section. +For example:

+
+    set exif {
+	Make     Canon
+	Model    {Canon DIGITAL IXUS}
+	DateTime {2001:06:09 15:17:32}
+    }
+
+

Throws an error if file is not a JPEG image.

+
::jpeg::getExifFromChannel channel ?section?
+

This command is as per ::jpeg::getExif except that it uses a +previously opened channel. channel should be a seekable channel +and section is as described in the documentation of +::jpeg::getExif +Note: the jpeg parser expects that the start of the channel is the +start of the image data. If working with an image embedded in a +container file format it may be necessary to read the jpeg data into +a temporary container: either a temporary file or a memory channel.

+
::jpeg::formatExif keys
+

Takes a list of key-value pairs as returned by getExif and formats +many of the values into a more human readable form. As few as one key-value +may be passed in, the entire exif is not required.

+
+    foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] {
+        puts "$key: $val"
+    }
+
+
+    array set exif [::jpeg::getExif photo.jpg]
+    puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]]
+
+
+
::jpeg::exifKeys
+

Returns a list of the EXIF keys which are currently understood. +There may be keys present in getExif data that are not understood. +Those keys will appear in a 4 digit hexadecimal format.

+
::jpeg::removeExif file
+

Removes the Exif data segment from the specified file and replaces +it with a standard JFIF segment. +Throws an error if file is not a JPEG image.

+
::jpeg::stripJPEG file
+

Removes all metadata from the JPEG file leaving only +the image. This includes comments, EXIF segments, JFXX +segments, and application specific segments. +Throws an error if file is not a JPEG image.

+
::jpeg::getComments file
+

Returns a list containing all the JPEG comments found in +the file. +Throws an error if file is not a valid JPEG image.

+
::jpeg::addComment file text...
+

Adds one or more plain text comments to the JPEG image +in file. +Throws an error if file is not a valid JPEG image.

+
::jpeg::removeComments file
+

Removes all comments from the file specified. +Throws an error if file is not a valid JPEG image.

+
::jpeg::replaceComment file text
+

Replaces the first comment in the file with the new text. +This is merely a shortcut for ::jpeg::removeComments +and ::jpeg::addComment +Throws an error if file is not a valid JPEG image.

+
::jpeg::debug file
+

Prints everything we know about the given file in a nice format.

+
::jpeg::markers channel
+

This is an internal helper command, we document it for use by advanced +users of the package. The argument channel is an open file +handle positioned at the start of the first marker (usually 2 +bytes). The command returns a list with one element for each JFIF +marker found in the file. Each element consists of a list of the +marker name, its offset in the file, and its length. The offset points +to the beginning of the sections data, not the marker itself. The +length is the length of the data from the offset listed to the start +of the next marker.

+
+
+

LIMITATIONS

+

can only work with files +cant write exif data +gps exif data not parsed +makernote data not yet implemented

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category jpeg of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/json/json.html Index: embedded/www/tcllib/files/modules/json/json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/json/json.html @@ -0,0 +1,216 @@ + + +json - JSON + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

json(n) 1.1.2 tcllib "JSON"

+

Name

+

json - JSON parser

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require json ?1.1.2?
    • +
+ +
+
+

Description

+

The json package provides a simple Tcl-only library for parsing the +JSON http://www.json.org/ data exchange format as specified in RFC 4627 +http://www.ietf.org/rfc/rfc4627.txt. +There is some ambiguity in parsing JSON because JSON has type information that +is not maintained by the Tcl conversion. The json package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
::json::json2dict txt
+

Parse JSON formatted text txt into a Tcl dict and return the value.

+
+
+

EXAMPLES

+

An example of a JSON array converted to Tcl. A JSON array is returned as a +single item with multiple elements.

+
[
+    {
+       "precision": "zip",
+       "Latitude":  37.7668,
+       "Longitude": -122.3959,
+       "Address":   "",
+       "City":      "SAN FRANCISCO",
+       "State":     "CA",
+       "Zip":       "94107",
+       "Country":   "US"
+    },
+    {
+       "precision": "zip",
+       "Latitude":  37.371991,
+       "Longitude": -122.026020,
+       "Address":   "",
+       "City":      "SUNNYVALE",
+       "State":     "CA",
+       "Zip":       "94085",
+       "Country":   "US"
+    }
+]
+=>
+{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020}
+
+

An example of a JSON object converted to Tcl. A JSON object is returned as a +multi-element list (a dict).

+
{
+    "Image": {
+        "Width":  800,
+        "Height": 600,
+        "Title":  "View from 15th Floor",
+        "Thumbnail": {
+            "Url":    "http://www.example.com/image/481989943",
+            "Height": 125,
+            "Width":  "100"
+        },
+        "IDs": [116, 943, 234, 38793]
+    }
+}
+=>
+Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category json of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

CGI programming

+
+ +
ADDED embedded/www/tcllib/files/modules/json/json_write.html Index: embedded/www/tcllib/files/modules/json/json_write.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/json/json_write.html @@ -0,0 +1,199 @@ + + +json::write - JSON + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

json::write(n) 1.0.2 tcllib "JSON"

+

Name

+

json::write - JSON generation

+
+ + +

Description

+

The json::write package provides a simple Tcl-only library +for generation of text in the JSON http://www.json.org/ data +exchange format as specified in +RFC 4627 http://www.ietf.org/rfc/rfc4627.txt.

+
+

COMMANDS

+
+
::json::write indented
+

This method returns the current state of the indentation setting.

+
::json::write indented flag
+

This and the method aligned configure the layout of the JSON +generated by the package.

+

If this flag is set (default) the package will break the +generated JSON code across lines and indent it according to its inner +structure, with each key of an object on a separate line.

+

If this flag is not set, the whole JSON object will be written on a +single line, with minimum spacing between all elements.

+
::json::write aligned
+

This method returns the current state of the alignment setting.

+
::json::write aligned flag
+

This and the method indented configure the layout of the JSON +generated by the package.

+

If this flag is set (default) the package ensures that the +values for the keys in an object are vertically aligned with each +other, for a nice table effect. To make this work this also implies +that indented is set as well.

+

If this flag is not set, the output is formatted as per the value of +indented, without trying to align the values for object keys.

+
::json::write string s
+

This method takes the string s and returns it properly quoted +for JSON as its result.

+
::json::write array arg...
+

This method takes a series of JSON formatted arguments and returns +them as a properly formatted JSON array as its result.

+
::json::write object key value...
+

This method takes a series of key/value arguments, the values already +formatted for JSON, and returns them as a properly formatted JSON +object as its result, with the keys formatted as JSON strings.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category json of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

CGI programming

+
+ +
ADDED embedded/www/tcllib/files/modules/lambda/lambda.html Index: embedded/www/tcllib/files/modules/lambda/lambda.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/lambda/lambda.html @@ -0,0 +1,209 @@ + + +lambda - Utility commands for anonymous procedures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

lambda(n) 1 tcllib "Utility commands for anonymous procedures"

+

Name

+

lambda - Utility commands for anonymous procedures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require lambda ?1?
    • +
+ +
+
+

Description

+

This package provides two convenience commands to make the writing of +anonymous procedures, i.e. lambdas more proc-like. Instead of, +for example, to write

+
+     set f {::apply {{x} {
+        ....
+     }}}
+
+

with its deep nesting of braces, or

+
+     set f [list ::apply {{x y} {
+        ....
+     }} $value_for_x]
+
+

with a list command to insert some of the arguments of a partial +application, just write

+
+     set f [lambda {x} {
+        ....
+     }]
+
+

and

+
+     set f [lambda {x y} {
+        ....
+     } $value_for_x]
+
+
+

COMMANDS

+
+
::lambda arguments body ?arg...?
+

The command constructs an anonymous procedure from the list of +arguments, body script and (optional) predefined argument values and +returns a command prefix representing this anonymous procedure.

+

When invoked the body is run in a new procedure scope +just underneath the global scope, with the arguments set to the values +supplied at both construction and invokation time.

+
::lambda@ namespace arguments body ?arg...?
+

The command constructs an anonymous procedure from the namespace name, +list of arguments, body script and (optional) predefined argument +values and returns a command prefix representing this anonymous +procedure.

+

When invoked the body is run in a new procedure scope in +the namespace, with the arguments set to the values supplied at +both construction and invokation time.

+
+
+

AUTHORS

+

Andreas Kupries

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category lambda of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

apply(n), proc(n)

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/ldap/ldap.html Index: embedded/www/tcllib/files/modules/ldap/ldap.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ldap/ldap.html @@ -0,0 +1,510 @@ + + +ldap - LDAP client + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ldap(n) 1.6.9 tcllib "LDAP client"

+

Name

+

ldap - LDAP client

+
+ + +

Description

+

The ldap package provides a Tcl-only client library +for the LDAPv3 protocol as specified in +RFC 4511 (http://www.rfc-editor.org/rfc/rfc4511.txt). +It works by opening the standard (or secure) LDAP socket on the +server, and then providing a Tcl API to access the LDAP protocol +commands. All server errors are returned as Tcl errors (thrown) which +must be caught with the Tcl catch command.

+
+

COMMANDS

+
+
::ldap::connect host ?port?
+

Opens a LDAPv3 connection to the specified host, at the given +port, and returns a token for the connection. This token is the +handle argument for all other commands. If no port is +specified it will default to 389.

+

The command blocks until the connection has been established, or +establishment definitely failed.

+
::ldap::secure_connect host ?port?
+

Like ::ldap::connect, except that the created connection is +secured by SSL. The port defaults to 636. This command +depends on the availability of the package TLS, which is a +SSL binding for Tcl. If TLS is not available, then this +command will fail.

+

The command blocks until the connection has been established, or +establishment definitely failed.

+
::ldap::disconnect handle
+

Closes the ldap connection refered to by the token +handle. Returns the empty string as its result.

+
::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
+

Start TLS negotiation on the connection denoted by handle. +This is currently experimental and subject to change, more control over the TLS details +will probably be exposed later, to allow users to fine tune the negotiation according +to their security needs.

+
::ldap::bind handle ?name? ?password?
+

This command authenticates the ldap connection refered to by the token +in handle, with a user name and associated password. It blocks +until a response from the ldap server arrives. Its result is the empty +string. +Both name and passwd default to the empty string if they +are not specified. +By leaving out name and passwd you can make an anonymous bind to +the ldap server. +You can issue ::ldap::bind again to bind with different credentials.

+
::ldap::bindSASL handle ?name? ?password?
+

This command uses SASL authentication mechanisms to do a multistage bind. +Its otherwise identical to the standard ::ldap::bind. +This feature is currently experimental and subject to change. See the documentation +for the SASL and the "SASL.txt" in the tcllib CVS repository for +details how to setup and use SASL with openldap.

+
::ldap::unbind handle
+

This command asks the ldap server to release the last bind done for +the connection refered to by the token in handle. +The handle is invalid after the unbind, as the server closes the connection. +So this is effectivly just a more polite disconnect operation.

+
::ldap::search handle baseObject filterString attributes options
+

This command performs a LDAP search below the baseObject tree +using a complex LDAP search expression filterString and returns +the specified attributes of all matching objects (DNs). If the +list of attributes was empty all attributes are returned. The +command blocks until it has received all results. +The valid options are identical to the options listed for ::ldap::searchInit.

+

An example of a search expression is

+
+    set filterString "|(cn=Linus*)(sn=Torvalds*)"
+
+

The return value of the command is a list of nested dictionaries. The +first level keys are object identifiers (DNs), second levels keys are +attribute names. In other words, it is in the form

+
+    {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
+
+
+
::ldap::searchInit handle baseObject filterString attributes options
+

This command initiates a LDAP search below the baseObject tree +using a complex LDAP search expression filterString. +The search gets the specified attributes of all matching objects (DNs). +The command itself just starts the search, to retrieve the actual results, use +::ldap::searchNext. +A search can be terminated at any time by +::ldap::searchEnd. This informs the server that no further results should be sent by sending and ABANDON message +and cleans up the internal state of the search. +Only one ::ldap::search can be active at a given time, this +includes the introspection commands ::ldap::info saslmechanisms, ldap::info control and +ldap::info extensions, which invoke a search internally. +Error responses from the server due to wrong arguments or similar things are returned +with the first ::ldap::searchNext call and should be checked and dealed with there. +If the list of requested attributes is empty all attributes will be returned. +The parameter options specifies the options to be used in the search, +and has the following format:

+
+    {-option1 value1 -option2 value2 ... }
+
+

Following options are available:

+
+
-scope base one sub
+

Control the scope of the search to be one of base, one, or sub, to specify a base +object, one-level or subtree search. The default is sub.

+
-derefaliases never search find always
+

Control how aliases dereferencing is done. Should be one of never, always, search, or find to +specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or +dereferenced only when locating the base object for the search. +The default is to never dereference aliases.

+
-sizelimit num
+

Determines the maximum number of entries to return in a search. If specified as +0 no limit is enforced. The server may enforce a configuration dependent sizelimit, +which may be lower than the one given by this option. The default is 0, no limit.

+
-timelimit seconds
+

Asks the server to use a timelimit of seconds for the search. Zero means no +limit. The default is 0, no limit.

+
-attrsonly boolean
+

If set to 1 only the attribute names but not the values will be present in the search result. +The default is to retrieve attribute names and values.

+
-referencevar varname
+

If set the search result reference LDAPURIs, if any, are returned in the given variable. +The caller can than decide to follow those references and query other LDAP servers for +further results.

+
+
::ldap::searchNext handle
+

This command returns the next entry from a LDAP search initiated +by ::ldap::searchInit. It returns only after a new result is received +or when no further results are available, but takes care to keep +the event loop alive. +The returned entry is a list with +two elements: the first is the DN of the entry, the second is the +list of attributes and values, under the format:

+
+    dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
+
+

The ::ldap::searchNext command returns an empty list at the +end of the search.

+
::ldap::searchEnd handle
+

This command terminates a LDAP search initiated +by ::ldap::searchInit. It also cleans up +the internal state so a new search can be initiated. +If the client has not yet received all results, the client +sends an ABANDON message to inform the server that no +further results for the previous search should to be sent.

+
::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
+

This command modifies the object dn on the ldap server we are +connected to via handle. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are dictionaries mapping attribute names to values. The +optional arguments default to the empty dictionary, which means that +no attributes will be deleted nor added.

+
+
dictionary attrValToReplace (in)
+

No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +replace all attributes known to the object.

+
dictionary attrToDelete (in)
+

No attributes will be deleted if this argument is empty. The +dictionary values are restrictions on the deletion. An attribute +listed here will be deleted if and only if its current value at the +server matches the value specified in the dictionary, or if the value +in the dictionary is the empty string.

+
dictionary attrValToAdd (in)
+

No attributes will be added if this argument is empty. The dictionary +values are the values for the new attributes.

+
+

The command blocks until all modifications have completed. Its result +is the empty string.

+
::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attrValToAdd?
+

This command modifies the object dn on the ldap server we are +connected to via handle. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are lists with the format:

+
+    attr1 {val11 val12 ...} attr2 {val21...} ...
+
+

where each value list may be empty for deleting all attributes. +The optional arguments default to empty lists of attributes to +delete and to add.

+
+
list attrValToReplace (in)
+

No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +replace all attributes known to the object.

+
list attrValToDelete (in)
+

No attributes will be deleted if this argument is empty. If no +value is specified, the whole set of values for an attribute +will be deleted.

+
list attrValToAdd (in)
+

No attributes will be added if this argument is empty.

+
+

The command blocks until all modifications have completed. Its result +is the empty string.

+
::ldap::add handle dn attrValueTuples
+

This command creates a new object using the specified dn. The +attributes of the new object are set to the values in the list +attrValueTuples. +Multiple valuated attributes may be specified using multiple tuples. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::addMulti handle dn attrValueTuples
+

This command is the preferred one to create +a new object using the specified dn. The +attributes of the new object are set to the values in the dictionary +attrValueTuples (which is keyed by the attribute names). +Each tuple is a list containing multiple values. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::delete handle dn
+

This command removes the object specified by dn, and all its +attributes from the server. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
+

] +This command moves or copies the object specified by dn +to a new location in the tree of object. This location is +specified by newrdn, a relative designation, +or by newrdn and newSuperior, a absolute designation. +The optional argument deleteOld defaults to true, +i.e. a move operation. If deleteOld is not set, then the +operation will create a copy of dn in the new location. +The optional argument newSuperior defaults an empty string, +meaning that the object must not be relocated in another branch of +the tree. If this argument is given, the argument deleteOld +must be specified also. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::info ip handle
+

This command returns the IP address of the remote LDAP server the handle is connected to.

+
::ldap::info bound handle
+

This command returns 1 if a handle has successfully completed a ::ldap::bind. +If no bind was done or it failed, a 0 is returned.

+
::ldap::info bounduser handle
+

This command returns the username used in the bind operation if a handle has successfully completed a ::ldap::bind. +If no bound was done or it failed, an empty string is returned.

+
::ldap::info connections
+

This command returns all currently existing ldap connection handles.

+
::ldap::info tls handle
+

This command returns 1 if the ldap connection handle used TLS/SSL for +connection via ldap::secure_connect or completed ldap::starttls, 0 otherwise.

+
::ldap::info saslmechanisms handle
+

Return the supported SASL mechanisms advertised by the server. Only valid in a +bound state (anonymous or other).

+
::ldap::info control handle
+

Return the supported controls advertised by the server as a list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change.

+
::ldap::info extensions extensions
+

Returns the supported LDAP extensions as list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change.

+
::ldap::info whoami handle
+

Returns authzId for the current connection. This implements the RFC 4532 +protocol extension.

+
+
+

EXAMPLES

+

A small example, extracted from the test application coming with this +code.

+
+    package require ldap
+    # Connect, bind, add a new object, modify it in various ways
+    set handle [ldap::connect localhost 9009]
+    set dn "cn=Manager, o=University of Michigan, c=US"
+    set pw secret
+    ldap::bind $handle $dn $pw
+    set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
+    ldap::add $handle $dn {
+	objectClass     OpenLDAPperson
+	cn              {Test User}
+	mail            test.user@google.com
+	uid             testuid
+	sn              User
+	telephoneNumber +31415926535
+	telephoneNumber +27182818285
+    }
+    set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
+    ldap::addMulti $handle $dn {
+	objectClass     {OpenLDAPperson}
+	cn              {{Anotther User}}
+	mail            {test.user@google.com}
+	uid             {testuid}
+	sn              {User}
+	telephoneNumber {+31415926535 +27182818285}
+    }
+    # Replace all attributes
+    ldap::modify $handle $dn [list drink icetea uid JOLO]
+    # Add some more
+    ldap::modify $handle $dn {} {} [list drink water  drink orangeJuice pager "+1 313 555 7671"]
+    # Delete
+    ldap::modify $handle $dn {} [list drink water  pager ""]
+    # Move
+    ldap::modifyDN $handle $dn "cn=Tester"
+    # Kill the test object, and shut the connection down.
+    set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
+    ldap::delete $handle $dn
+ 
+    ldap::unbind     $handle
+    ldap::disconnect $handle
+
+

And a another example, a simple query, and processing the +results.

+
+    package require ldap
+    set handle [ldap::connect ldap.acme.com 389]
+    ldap::bind $handle
+    set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
+    foreach result $results {
+	foreach {object attributes} $result break
+	# The processing here is similar to what 'parray' does.
+	# I.e. finding the longest attribute name and then
+	# generating properly aligned output listing all attributes
+	# and their values.
+	set width 0
+	set sortedAttribs {}
+	foreach {type values} $attributes {
+	    if {[string length $type] > $width} {
+		set width [string length $type] 
+	    }
+	    lappend sortedAttribs [list $type $values]
+	}     
+	puts "object='$object'"
+	foreach sortedAttrib  $sortedAttribs {
+	    foreach {type values} $sortedAttrib break
+	    foreach value $values {
+		regsub -all "\[\x01-\x1f\]" $value ? value
+		puts [format "  %-${width}s %s" $type $value]
+	    }
+	}
+	puts ""
+    }
+    ldap::unbind $handle
+    ldap::disconnect $handle
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ldap of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +One know bug is the usage of vwait inside the dispatch mechanism, which makes +it currently unsafe to use this code in code that also enters the event loop.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/ldap/ldapx.html Index: embedded/www/tcllib/files/modules/ldap/ldapx.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ldap/ldapx.html @@ -0,0 +1,751 @@ + + +ldapx - LDAP extended object interface + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ldapx(n) 0.2.5 tcllib "LDAP extended object interface"

+

Name

+

ldapx - LDAP extended object interface

+
+ + +

Description

+

The ldapx package provides an extended Tcl interface to +LDAP directores and LDIF files. The ldapx package is built +upon the ldap package in order to get low level LDAP access.

+

LDAP access is compatible with RFC 2251 +(http://www.rfc-editor.org/rfc/rfc2251.txt). +LDIF access is compatible with RFC 2849 +(http://www.rfc-editor.org/rfc/rfc2849.txt).

+
+

OVERVIEW

+

The ldapx package provides objects to interact with LDAP +directories and LDIF files with an easy to use programming interface. +It implements three snit::type classes.

+

The first class, entry, is used to store individual entries. +Two different formats are available: the first one is the +standard format, which represents an entry as read from the +directory. The second format is the change format, which +stores differences between two standard entries.

+

With these entries, an application which wants to modify an entry +in a directory needs to read a (standard) entry from the directory, +create a fresh copy into a new (standard) entry, modify the new +copy, and then compute the differences between the two entries into +a new (change) entry, which may be commited to the directory.

+

Such kinds of modifications are so heavily used that standard entries +may contain their own copy of the original data. With such a copy, +the application described above reads a (standard) entry from the +directory, backs-up the original data, modifies the entry, and +computes the differences between the entry and its backup. These +differences are then commited to the directory.

+

Methods are provided to compute differences between two entries, +to apply differences to an entry in order to get a new entry, and +to get or set attributes in standard entries.

+

The second class is the ldap class. It provides a method +to connect and bind to the directory with a uniform access +to LDAP and LDAPS through an URL (ldap:// or ldaps://). The +traverse control structure executes a body for each entry +found in the directory. The commit method applies some +changes (represented as entry objects) to the directory. +Since some attributes are represented as UTF-8 strings, the option +-utf8 controls which attributes must be converted and +which attributes must not be converted.

+

The last class is the ldif class. It provides a method to +associate a standard Tcl channel to an LDIF object. Then, +methods read and write read or write entries from +or to this channel. This class can make use of standard or change +entries, according to the type of the LDIF file which may contain +either standard entries or change entries (but not both at the same +time). The option -utf8 works exactly as with the +ldap class.

+
+

ENTRY CLASS

+

Entry Instance Data

+

An instance of the entry class keeps the following data:

+
+ +
dn
+

This is the DN of the entry, which includes (in LDAP + terminology) the RDN (relative DN) and the Superior parts.

+
format
+

The format may be uninitialized (entry not yet used), + standard or change. Most methods check the + format of the entry, which can be reset with the + reset method.

+
attrvals
+

In a standard entry, this is where the attributes + and associated values are stored. Many methods provide + access to these informations. Attribute names are always + converted into lower case.

+
backup
+

In a standard entry, the backup may contain a copy + of the dn and all attributes and values. Methods + backup and restore manipulate these data, + and method diff may use this backup.

+
change
+

In a change entry, these data represent the + modifications. Such modifications are handled by specialized + methods such as apply or commit. + Detailed format should not be used directly by programs.

+

Internally, modifications are represented as a list of + elements, each element has one of the following formats + (which match the corresponding LDAP operations):

+
    + +

  1. {add {attr1 {val1...valn} attr2 {...} ...}}

    +

    Addition of a new entry.

    2. +

  2. {mod {modop {attr1 ?val1...valn?} attr2 ...} {modop ...} ...}

    +

    Modification of one or more attributes and/or values, + where <modop> can be modadd, moddel + or modrepl (see the LDAP modify operation).

    3. +

  3. {del}

    +

    Deletion of an old entry.

    4. +

  4. {modrdn newrdn deleteoldrdn ?newsuperior?}

    +

    Renaming of an entry.

    5. +
+
+
+

Entry Options

+

No option is defined by this class.

+
+

Methods for all kinds of entries

+
+ +
e reset
+

This method resets the entry to an uninitialized state.

+
e dn ?newdn?
+

This method returns the current DN of the entry. If the + optional newdn is specified, it replaces the current + DN of the entry.

+
e rdn
+

This method returns the RDN part of the DN of the entry.

+
e superior
+

This method returns the superior part of the DN of the entry.

+
e print
+

This method returns the entry as a string ready to be printed.

+
+
+

Methods for standard entries only

+

In all methods, attribute names are converted in lower case.

+
+ +
se isempty
+

This method returns 1 if the entry is empty (i.e. without + any attribute).

+
se get attr
+

This method returns all values of the attribute attr, + or the empty list if the attribute is not fond.

+
se get1 attr
+

This method returns the first value of the attribute.

+
se set attr values
+

This method sets the values (list values) of the + attribute attr. If the list is empty, this method + deletes all

+
se set1 attr value
+

This method sets the values of the attribute attr to + be an unique value value. Previous values, if any, + are replaced by the new value.

+
se add attr values
+

This method adds all elements the list values to the + values of the attribute attr.

+
se add1 attr value
+

This method adds a single value given by the parameter + value to the attribute attr.

+
se del attr ?values?
+

If the optional list values is specified, this method + deletes all specified values from the attribute attr. + If the argument values is not specified, this method + deletes all values.

+
se del1 attr value
+

This method deletes a unique value from the attribute + attr.

+
se getattr
+

This method returns all attributes names.

+
se getall
+

This method returns all attributes and values from the + entry, packed in a list of pairs <attribute, list of values>.

+
se setall avpairs
+

This method sets at once all attributes and values. The + format of the avpairs argument is the same as the one + returned by method getall.

+
se backup ?other?
+

This method stores in an other standard entry object + a copy of the current DN and attributes/values. If the + optional other argument is not specified, copy is + done in the current entry (in a specific place, see section + OVERVIEW).

+
se swap
+

This method swaps the current and backup contexts of the + entry.

+
se restore ?other?
+

If the optional argument other is given, which must + then be a standard entry, this method restores the + current entry into the other entry. If the argument + other argument is not specified, this methods restores + the current entry from its internal backup (see section + OVERVIEW).

+
se apply centry
+

This method applies changes defined in the centry + argument, which must be a change entry.

+
+
+

Methods for change entries only

+
+ +
ce change ?new?
+

If the optional argument new is specified, this method + modifies the change list (see subsection Entry Instance Data for + the exact format). In both cases, current change list is + returned. + Warning: values returned by this method should only be used + by specialized methods such as apply or + commit.

+
ce diff new ?old?
+

This method computes the differences between the new + and old entries under the form of a change list, and + stores this list into the current change entry. If + the optional argument old is not specified, difference + is computed from the entry and its internal backup (see + section OVERVIEW). Return value is the computed + change list.

+
+
+

Entry Example

+
+    package require ldapx
+    #
+    # Create an entry and fill it as a standard entry with
+    # attributes and values
+    #
+    ::ldapx::entry create e
+    e dn "uid=joe,ou=people,o=mycomp"
+    e set1 "uid"             "joe"
+    e set  "objectClass"     {person anotherObjectClass}
+    e set1 "givenName"       "Joe"
+    e set1 "sn"              "User"
+    e set  "telephoneNumber" {+31415926535 +2182818}
+    e set1 "anotherAttr"     "This is a beautiful day, isn't it?"
+    puts stdout "e\n[e print]"
+    #
+    # Create a second entry as a backup of the first, and
+    # make some changes on it.
+    # Entry is named automatically by snit.
+    #
+    set b [::ldapx::entry create %AUTO%]
+    e backup $b
+    puts stdout "$b\n[$b print]"
+    $b del  "anotherAttr"
+    $b del1 "objectClass" "anotherObjectClass"
+    #
+    # Create a change entry, a compute differences between first
+    # and second entry.
+    #
+    ::ldapx::entry create c
+    c diff e $b
+    puts stdout "$c\n[$c print]"
+    #
+    # Apply changes to first entry. It should be the same as the
+    # second entry, now.
+    #
+    e apply c
+    ::ldapx::entry create nc
+    nc diff e $b
+    puts stdout "nc\n[nc print]"
+    #
+    # Clean-up
+    #
+    e destroy
+    $b destroy
+    c destroy
+    nc destroy
+
+
+
+

LDAP CLASS

+

Ldap Instance Data

+

An instance of the ldap class keeps the following data:

+
+ +
channel
+

This is the channel used by the ldap package for + communication with the LDAP server.

+
lastError
+

This variable contains the error message which appeared in + the last method of the ldap class (this string is + modified in nearly all methods). The error method + may be used to fetch this message.

+
+
+

Ldap Options

+

A first set of options of the ldap class is used during +search operations (methods traverse, search and +read, see below).

+
+ +
-scope base|one|sub
+

Specify the scope of the LDAP search to be one of + base, one or sub to specify + a base object, one-level or subtree search.

+

The default is sub.

+
-derefaliases never|seach|find|always
+

Specify how aliases dereferencing is handled: + never is used to specify that aliases are never derefenced, + always that aliases are always derefenced, + search that aliases are dereferenced when searching, + or find that aliases are dereferenced only when + locating the base object for the search.

+

The default is never.

+
-sizelimit integer
+

Specify the maximum number of entries to be retreived + during a search. A value of 0 means no limit.

+

Default is 0.

+
-timelimit integer
+

Specify the time limit for a search to complete. + A value of 0 means no limit.

+

Default is 0.

+
-attrsonly 0|1
+

Specify if only attribute names are to be retrieved (value + 1). Normally (value 0), attribute values + are also retrieved.

+

Default is 0.

+
+

The last option is used when getting entries or committing changes +in the directory:

+
+ +
-utf8 pattern-yes pattern-no
+

Specify which attribute values are encoded in UTF-8. This + information is specific to the LDAP schema in use by the + application, since some attributes such as jpegPhoto, for + example, are not encoded in UTF-8. This option takes the + form of a list with two regular expressions suitable for + the regexp command (anchored by ^ and $). + The first specifies which attribute names are to be UTF-8 + encoded, and the second selects, among those, the attribute + names which will not be UTF-8 encoded. It is thus possible + to say: convert all attributes, except jpegPhoto.

+

Default is {{.*} {}}, meaning: all attributes are converted, + without exception.

+
+
+

Ldap Methods

+
+ +
la error ?newmsg?
+

This method returns the error message that occurred in the + last call to a ldap class method. If the optional + argument newmsg is supplied, it becomes the last + error message.

+
la connect url ?binddn? ?bindpw?
+

This method connects to the LDAP server using given URL + (which can be of the form ldap://host:port or + ldaps://host:port). If an optional binddn + argument is given together with the bindpw argument, + the connect binds to the LDAP server using the + specified DN and password.

+
la disconnect
+

This method disconnects (and unbinds, if necessary) from + the LDAP server.

+
la traverse base filter attrs entry body
+

This method is a new control structure. It searches the + LDAP directory from the specified base DN (given by the + base argument) and selects entries based on the + argument filter. For each entry found, this method + fetches attributes specified by the attrs argument + (or all attributes if it is an empty list), stores them in + the entry instance of class entry and executes + the script defined by the argument body. Options are + used to refine the search.

+

Caution: when this method is used, the script body + cannot perform another LDAP search (methods traverse, + search or read).

+
la search base filter attrs
+

This method searches the directory using the same way as + method traverse. All found entries are stored in + newly created instances of class entry, which are + returned in a list. The newly created instances should be + destroyed when they are no longer used.

+
la read base filter entry ... entry
+

This method reads one or more entries, using the same search + criteria as methods traverse and search. + All attributes are stored in the entries. This method + provides a quick way to read some entries. It returns the + number of entries found in the directory (which may be more + than the number of read entries). If called without any + entry argument, this method just returns the number + of entries found, without returning any data.

+
la commit entry ... entry
+

This method commits the changes stored in the entry + arguments. Each entry may be either a change + entry, or a standard entry with a backup.

+

Note: in the future, this method should use the LDAP + transaction extension provided by OpenLDAP 2.3 and later.

+
+
+

Ldap Example

+
+    package require ldapx
+    #
+    # Connects to the LDAP directory
+    #
+    ::ldapx::ldap create l
+    set url "ldap://server.mycomp.com"
+    if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
+	puts stderr "error: [l error]"
+	exit 1
+    }
+    #
+    # Search all entries matching some criterion
+    #
+    l configure -scope one
+    ::ldapx::ldap create e
+    set n 0
+    l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
+	puts "dn: [e dn]"
+	puts "  sn:        [e get1 sn]"
+	puts "  givenName: [e get1 givenName]"
+	incr n
+    }
+    puts "$n entries found"
+    e destroy
+    #
+    # Add a telephone number to some entries
+    # Note this modification cannot be done in the "traverse" operation.
+    #
+    set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
+    ::ldapx::ldap create c
+    foreach e $lent {
+	$e backup
+	$e add1 "telephoneNumber" "+31415926535"
+	c diff $e
+	if {! [l commit c]} then {
+	    puts stderr "error: [l error]"
+	    exit 1
+	}
+	$e destroy
+    }
+    l disconnect
+    l destroy
+
+
+
+

LDIF CLASS

+

Ldif Instance Data

+

An instance of the ldif class keeps the following data:

+
+ +
channel
+

This is the Tcl channel used to retrieve or store LDIF file + contents. The association between an instance and a channel + is made by the method channel. There is no need + to disrupt this association when the LDIF file operation + has ended.

+
format
+

LDIF files may contain standard entries or + change entries, but not both. This variable contains + the detected format of the file (when reading) or the format + of entries written to the file (when writing).

+
lastError
+

This variable contains the error message which appeared in + the last method of the ldif class (this string is + modified in nearly all methods). The error method + may be used to fetch this message.

+
version
+

This is the version of the LDIF file. Only version 1 is + supported: the method read can only read from + version 1 files, and method write only creates + version 1 files.

+
+
+

Ldif Options

+

This class defines two options:

+
+ +
-ignore list-of-attributes
+

This option is used to ignore certain attribute names on + reading. For example, to read OpenLDAP replica files (replog), + one must ignore replica and time attributes + since they do not conform to the RFC 2849 standard for LDIF + files.

+

Default is empty list: no attribute is ignored.

+
-utf8 pattern-yes pattern-no
+

Specify which attribute values are encoded in UTF-8. This + information is specific to the LDAP schema in use by the + application, since some attributes such as jpegPhoto, for + example, are not encoded in UTF-8. This option takes the + form of a list with two regular expressions suitable for + the regexp command (anchored by ^ and $). + The first specifies which attribute names are to be UTF-8 + encoded, and the second selects, among those, the attribute + names which will not be UTF-8 encoded. It is thus possible + to say: convert all attributes, except jpegPhoto.

+

Default is {{.*} {}}, meaning: all attributes are converted, + without exception.

+
+
+

Ldif Methods

+
+ +
li channel chan
+

This method associates the Tcl channel named chan + with the LDIF instance. It resets the type of LDIF object + to uninitialized.

+
li error ?newmsg?
+

This method returns the error message that occurred in the + last call to a ldif class method. If the optional + argument newmsg is supplied, it becomes the last + error message.

+
li read entry
+

This method reads the next entry from the LDIF file and + stores it in the entry object of class entry. + The entry may be a standard or change entry.

+
li write entry
+

This method writes the entry given in the argument + entry to the LDIF file.

+
+
+

Ldif Example

+
+    package require ldapx
+    # This examples reads a LDIF file containing entries,
+    # compare them to a LDAP directory, and writes on standard
+    # output an LDIF file containing changes to apply to the
+    # LDAP directory to match exactly the LDIF file.
+    ::ldapx::ldif create liin
+    liin channel stdin
+    ::ldapx::ldif create liout
+    liout channel stdout
+    ::ldapx::ldap create la
+    if {! [la connect "ldap://server.mycomp.com"]} then {
+	puts stderr "error: [la error]"
+	exit 1
+    }
+    la configure -scope one
+    # Reads LDIF file
+    ::ldapx::entry create e1
+    ::ldapx::entry create e2
+    ::ldapx::entry create c
+    while {[liin read e1] != 0} {
+	set base [e1 superior]
+	set id [e1 rdn]
+	if {[la read $base "($id)" e2] == 0} then {
+	    e2 reset
+	}
+	c diff e1 e2
+	if {[llength [c change]] != 0} then {
+	    liout write c
+	}
+    }
+    la disconnect
+    la destroy
+    e1 destroy
+    e2 destroy
+    c destroy
+    liout destroy
+    liin destroy
+
+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ldap of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/log/log.html Index: embedded/www/tcllib/files/modules/log/log.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/log/log.html @@ -0,0 +1,349 @@ + + +log - Logging facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

log(n) 1.3 tcllib "Logging facility"

+

Name

+

log - Procedures to log messages of libraries and applications.

+
+ + +

Description

+

The log package provides commands that allow libraries and +applications to selectively log information about their internal +operation and state.

+

To use the package just execute

+
+    package require log
+    log::log notice "Some message"
+
+

As can be seen above, each message given to the log facility is +associated with a level determining the importance of the +message. The user can then select which levels to log, what commands +to use for the logging of each level and the channel to write the +message to. In the following example the logging of all message with +level debug is deactivated.

+
+    package require log
+    log::lvSuppress debug
+    log::log debug "Unseen message" ; # No output
+
+

By default all messages associated with an error-level +(emergency, alert, critical, and +error) are written to stderr. Messages with any +other level are written to stdout. In the following example +the log module is reconfigured to write debug messages to +stderr too.

+
+    package require log
+    log::lvChannel debug stderr
+    log::log debug "Written to stderr"
+
+

Each message level is also associated with a command to use when +logging a message with that level. The behaviour above for example +relies on the fact that all message levels use by default the standard +command ::log::Puts to log any message. In the following example +all messages of level notice are given to the non-standard +command toText for logging. This disables the channel setting +for such messages, assuming that toText does not use it by +itself.

+
+    package require log
+    log::lvCmd notice toText
+    log::log notice "Handled by \"toText\""
+
+

Another database maintained by this facility is a map from message +levels to colors. The information in this database has no +influence on the behaviour of the module. It is merely provided as a +convenience and in anticipation of the usage of this facility in +tk-based application which may want to colorize message +logs.

+
+

API

+

The following commands are available:

+
+
::log::levels
+

Returns the names of all known levels, in alphabetical order.

+
::log::lv2longform level
+

Converts any unique abbreviation of a level name to the full level +name.

+
::log::lv2color level
+

Converts any level name including unique abbreviations to the +corresponding color.

+
::log::lv2priority level
+

Converts any level name including unique abbreviations to the +corresponding priority.

+
::log::lv2cmd level
+

Converts any level name including unique abbreviations to the command +prefix used to write messages with that level.

+
::log::lv2channel level
+

Converts any level name including unique abbreviations to the channel +used by ::log::Puts to write messages with that level.

+
::log::lvCompare level1 level2
+

Compares two levels (including unique abbreviations) with respect to +their priority. This command can be used by the -command option of +lsort. The result is one of -1, 0 or 1 or an error. A result of -1 +signals that level1 is of less priority than level2. 0 signals that +both levels have the same priority. 1 signals that level1 has higher +priority than level2.

+
::log::lvSuppress level {suppress 1}
+

] +(Un)suppresses the output of messages having the specified +level. Unique abbreviations for the level are allowed here too.

+
::log::lvSuppressLE level {suppress 1}
+

] +(Un)suppresses the output of messages having the specified level or +one of lesser priority. Unique abbreviations for the level are allowed +here too.

+
::log::lvIsSuppressed level
+

Asks the package whether the specified level is currently +suppressed. Unique abbreviations of level names are allowed.

+
::log::lvCmd level cmd
+

Defines for the specified level with which command to write the +messages having this level. Unique abbreviations of level names are +allowed. The command is actually a command prefix and this facility +will append 2 arguments before calling it, the level of the message +and the message itself, in this order.

+
::log::lvCmdForall cmd
+

Defines for all known levels with which command to write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order.

+
::log::lvChannel level chan
+

Defines for the specified level into which channel ::log::Puts +(the standard command) shall write the messages having this +level. Unique abbreviations of level names are allowed. The command is +actually a command prefix and this facility will append 2 arguments +before calling it, the level of the message and the message itself, in +this order.

+
::log::lvChannelForall chan
+

Defines for all known levels with which which channel +::log::Puts (the standard command) shall write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order.

+
::log::lvColor level color
+

Defines for the specified level the color to return for it in a call +to ::log::lv2color. Unique abbreviations of level names are +allowed.

+
::log::lvColorForall color
+

Defines for all known levels the color to return for it in a call to +::log::lv2color. Unique abbreviations of level names are +allowed.

+
::log::log level text
+

Log a message according to the specifications for commands, channels +and suppression. In other words: The command will do nothing if the +specified level is suppressed. If it is not suppressed the actual +logging is delegated to the specified command. If there is no command +specified for the level the message won't be logged. The standard +command ::log::Puts will write the message to the channel +specified for the given level. If no channel is specified for the +level the message won't be logged. Unique abbreviations of level names +are allowed. Errors in the actual logging command are not +caught, but propagated to the caller, as they may indicate +misconfigurations of the log facility or errors in the callers code +itself.

+
::log::logarray level arrayvar ?pattern?
+

Like ::log::log, but logs the contents of the specified array +variable arrayvar, possibly restricted to entries matching the +pattern. The pattern defaults to * (i.e. all entries) if +none was specified.

+
::log::loghex level text data
+

Like ::log::log, but assumes that data contains binary +data. It converts this into a mixed hex/ascii representation before +writing them to the log.

+
::log::logMsg text
+

Convenience wrapper around ::log::log. +Equivalent to ::log::log info text.

+
::log::logError text
+

Convenience wrapper around ::log::log. +Equivalent to ::log::log error text.

+
::log::Puts level text
+

The standard log command, it writes messages and their levels to +user-specified channels. Assumes that the suppression checks were done +by the caller. Expects full level names, abbreviations are +not allowed.

+
+
+

LEVELS

+

The package currently defines the following log levels, the level of +highest importance listed first.

+
    +

  • emergency

    • +

  • alert

    • +

  • critical

    • +

  • error

    • +

  • warning

    • +

  • notice

    • +

  • info

    • +

  • debug

    • +
+

Note that by default all messages with levels warning down to +debug are suppressed. This is done intentionally, because (we believe +that) in most situations debugging output is not wanted. Most people wish to +have such output only when actually debugging an application.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category log of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/log/logger.html Index: embedded/www/tcllib/files/modules/log/logger.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/log/logger.html @@ -0,0 +1,474 @@ + + +logger - Object Oriented logging facility + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

logger(n) 0.9.3 tcllib "Object Oriented logging facility"

+

Name

+

logger - System to control logging of events.

+
+ + +

Description

+

The logger package provides a flexible system for logging messages +from different services, at priority levels, with different commands.

+

To begin using the logger package, we do the following:

+
+    package require logger
+    set log [logger::init myservice]
+    ${log}::notice "Initialized myservice logging"
+    ... code ...
+    ${log}::notice "Ending myservice logging"
+    ${log}::delete
+
+

In the above code, after the package is loaded, the following things +happen:

+
+
logger::init service
+

Initializes the service service for logging. The service names +are actually Tcl namespace names, so they are separated with '::'. +The service name may not be the empty string or only ':'s. +When a logger service is initialized, it "inherits" properties from its +parents. For instance, if there were a service foo, and +we did a logger::init foo::bar (to create a bar +service underneath foo), bar would copy the current +configuration of the foo service, although it would of +course, also be possible to then separately configure bar. +If a logger service is initialized and the parent does not yet exist, the +parent is also created. +The new logger service is initialized with the default loglevel set +with logger::setlevel.

+
logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service
+

Import the logger service commands into the current namespace. Without the -all option +only the commands corresponding to the log levels are imported. If -all is given, +all the ${log}::cmd style commands are imported. If the import would overwrite a command +an error is returned and no command is imported. Use the -force option to force the import +and overwrite existing commands without complaining. +If the -prefix option is given, the commands are imported with the given prefix +prepended to their names. +If the -namespace option is given, the commands are imported into the given namespace. If the +namespace does not exist, it is created. If a namespace without a leading :: is given, it is interpreted as +a child namespace to the current namespace.

+
logger::initNamespace ns ?level?
+

Convenience command for setting up a namespace for logging. Creates a +logger service named after the namespace ns (a :: prefix is +stripped), imports all the log commands into the namespace, and sets +the default logging level, either to the specified level, or the +default level, "warn".

+
logger::services
+

Returns a list of all the available services.

+
logger::enable level
+

Globally enables logging at and "above" the given level. Levels are +debug, info, notice, warn, error, +critical, alert, emergency.

+
logger::disable level
+

Globally disables logging at and "below" the given level. Levels are +those listed above.

+
logger::setlevel level
+

Globally enable logging at and "above" the given level. Levels are those +listed above. This command changes the default loglevel for new loggers +created with logger::init.

+
logger::levels
+

Returns a list of the available log levels (also listed above under enable).

+
logger::servicecmd service
+

Returns the ${log} token created by logger::init for this service.

+
${log}::debug message
+
+
${log}::info message
+
+
${log}::notice message
+
+
${log}::warn message
+
+
${log}::error message
+
+
${log}::critical message
+
+
${log}::alert message
+
+
${log}::emergency message
+

These are the commands called to actually log a message about an +event. ${log} is the variable obtained from logger::init.

+
${log}::setlevel level
+

Enable logging, in the service referenced by ${log}, and its +children, at and above the level specified, and disable logging below +it.

+
${log}::enable level
+

Enable logging, in the service referenced by ${log}, and its +children, at and above the level specified. Note that this does not disable logging below this level, so you should probably use +setlevel instead.

+
${log}::disable level
+

Disable logging, in the service referenced by ${log}, and its +children, at and below the level specified. Note that this does not enable logging above this level, +so you should probably use setlevel instead. +Disabling the loglevel emergency switches logging off for the service and its children.

+
${log}::lvlchangeproc command
+
+
${log}::lvlchangeproc
+

Set the script to call when the log instance in question changes its log level. +If called without a command it returns the currently registered command. The command gets two arguments +appended, the old and the new loglevel. The callback is invoked after all changes have been done. +If child loggers are affected, their callbacks are called before their parents callback.

+
+ 	proc lvlcallback {old new} {
+ 	    puts "Loglevel changed from $old to $new"
+ 	}
+ 	${log}::lvlchangeproc lvlcallback
+
+
+
${log}::logproc level
+
+
${log}::logproc level command
+
+
${log}::logproc level argname body
+

This command comes in three forms - the third, older one is deprecated +and may be removed from future versions of the logger package. +The current set version takes one argument, a command to be executed when the +level is called. The callback command takes on argument, the text to +be logged. If called only with a valid level logproc returns the name of the command +currently registered as callback command. +logproc specifies which command will perform the actual logging +for a given level. The logger package ships with default commands for +all log levels, but with logproc it is possible to replace them +with custom code. This would let you send your logs over the network, +to a database, or anything else. For example:

+
+    proc logtoserver {txt} {
+        variable socket
+        puts $socket "Notice: $txt"
+    }
+    ${log}::logproc notice logtoserver
+
+

Trace logs are slightly different: instead of a plain text argument, +the argument provided to the logproc is a dictionary consisting of the +enter or leave keyword along with another dictionary of +details about the trace. These include:

+
    +

  • proc - Name of the procedure being traced.

    • +

  • level - The stack level for the procedure invocation +(from info level).

    • +

  • script - The name of the file in which the procedure is +defined, or an empty string if defined in interactive mode.

    • +

  • caller - The name of the procedure calling the procedure +being traced, or an empty string if the procedure was called from the +global scope (stack level 0).

    • +

  • procargs - A dictionary consisting of the names of arguments +to the procedure paired with values given for those arguments (enter +traces only).

    • +

  • status - The Tcl return code (e.g. ok, +continue, etc.) (leave traces only).

    • +

  • result - The value returned by the procedure (leave +traces only).

    • +
+
${log}::services
+

Returns a list of the registered logging services which are children of this service.

+
${log}::servicename
+

Returns the name of this service.

+
${log}::currentloglevel
+

Returns the currently enabled log level for this service. If no logging is enabled returns none.

+
${log}::delproc command
+
+
${log}::delproc
+

Set the script to call when the log instance in question is deleted. +If called without a command it returns the currently registered command. +For example:

+
+    ${log}::delproc [list closesock $logsock]
+
+
+
${log}::delete
+

This command deletes a particular logging service, and its children. +You must call this to clean up the resources used by a service.

+
${log}::trace command
+

This command controls logging of enter/leave traces for specified procedures. +It is used to enable and disable tracing, query tracing status, and +specify procedures are to be traced. Trace handlers are unregistered when +tracing is disabled. As a result, there is not performance impact to a +library when tracing is disabled, just as with other log level commands.

+
+  proc tracecmd { dict } {
+      puts $dict
+  }
+  set log [::logger::init example]
+  ${log}::logproc trace tracecmd
+  proc foo { args } {
+      puts "In foo"
+      bar 1
+      return "foo_result"
+  }
+    
+  proc bar { x } {
+      puts "In bar"
+      return "bar_result"
+  }
+  ${log}::trace add foo bar
+  ${log}::trace on
+  foo
+# Output:
+enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
+In foo
+enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
+In bar
+leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
+leave {proc ::foo level 1 script {} caller {} status ok result foo_result}
+
+
+
${log}::trace on
+

Turns on trace logging for procedures registered through the trace +add command. This is similar to the enable command for other +logging levels, but allows trace logging to take place at any level. +The trace logging mechanism takes advantage of the execution trace feature +of Tcl 8.4 and later. The trace on command will return an +error if called from earlier versions of Tcl.

+
${log}::trace off
+

Turns off trace logging for procedures registered for trace logging +through the trace add command. This is similar to the +disable command for other logging levels, but allows trace logging +to take place at any level. +Procedures are not unregistered, so logging for them can be turned back +on with the trace on command. There is no overhead imposed +by trace registration when trace logging is disabled.

+
${log}::trace status ?procName? ?...?
+

This command returns a list of the procedures currently registered for +trace logging, or a flag indicating whether or not a trace is registered +for one or more specified procedures.

+
${log}::trace add procName ?...?
+
+
${log}::trace add ?-ns? nsName ?...?
+

This command registers one or more procedures for logging of entry/exit +traces. Procedures can be specified via a list of procedure names or +namespace names (in which case all procedure within the namespace +are targeted by the operation). By default, each name is first +interpreted as a procedure name or glob-style search pattern, and if +not found its interpreted as a namespace name. The -ns option can +be used to force interpretation of all provided arguments as namespace names. +Procedures must be defined prior to registering them for tracing +through the trace add command. Any procedure or namespace +names/patterns that don't match any existing procedures will be +silently ignored.

+
${log}::trace remove procName ?...?
+
+
${log}::trace remove ?-ns? nsName ?...?
+

This command unregisters one or more procedures so that they will no +longer have trace logging performed, with the same matching rules as +that of the trace add command.

+
+
+

IMPLEMENTATION

+

The logger package is implemented in such a way as to optimize (for +Tcl 8.4 and newer) log procedures which are disabled. They are +aliased to a proc which has no body, which is compiled to a no op in +bytecode. This should make the peformance hit minimal. If you really +want to pull out all the stops, you can replace the ${log} token in +your code with the actual namespace and command (${log}::warn becomes +::logger::tree::myservice::warn), so that no variable lookup is done. +This puts the performance of disabled logger commands very close to no +logging at all.

+

The "object orientation" is done through a hierarchy of namespaces. +Using an actual object oriented system would probably be a better way +of doing things, or at least provide for a cleaner implementation.

+

The service "object orientation" is done with namespaces.

+
+

Logprocs and Callstack

+

The logger package takes extra care to keep the logproc out of the call stack. +This enables logprocs to execute code in the callers scope by using uplevel or +linking to local variables by using upvar. This may fire traces with all usual +side effects.

+
+     # Print caller and current vars in the calling proc
+     proc log_local_var {txt} {
+          set caller [info level -1]
+          set vars [uplevel 1 info vars]
+          foreach var [lsort $vars] {
+             if {[uplevel 1 [list array exists $var]] == 1} {
+             	lappend val $var <Array>
+             } else {
+             	lappend val $var [uplevel 1 [list set $var]]
+             }
+          }
+          puts "$txt"
+          puts "Caller: $caller"
+          puts "Variables in callers scope:"
+          foreach {var value} $val {
+          	puts "$var = $value"
+          }
+     }
+     
+     # install as logproc
+     ${log}::logproc debug log_local_var
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/log/loggerAppender.html Index: embedded/www/tcllib/files/modules/log/loggerAppender.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/log/loggerAppender.html @@ -0,0 +1,177 @@ + + +logger::appender - Object Oriented logging facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

logger::appender(n) 1.2 tcllib "Object Oriented logging facility"

+

Name

+

logger::appender - Collection of predefined appenders for logger

+
+ + +

Description

+

This package provides a predefined set of logger templates.

+
+
::logger::appender::console -level level -service service ?options...?
+
+
-level level
+

Name of the level to fill in as "priority" in the log procedure.

+
-service service
+

Name of the service to fill in as "category" in the log procedure.

+
-appenderArgs appenderArgs
+

Any additional arguments for the log procedure in list form

+
-conversionPattern conversionPattern
+

The log pattern to use (see logger::utils::createLogProc for the +allowed substitutions).

+
-procName procName
+

Explicitly set the name of the created procedure.

+
-procNameVar procNameVar
+

Name of the variable to set in the calling context. This variable will +contain the name of the procedure.

+
+
::logger::appender::colorConsole -level level -service service ?options...?
+

See ::logger::appender::colorConsole for a description of the +applicable options.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/log/loggerUtils.html Index: embedded/www/tcllib/files/modules/log/loggerUtils.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/log/loggerUtils.html @@ -0,0 +1,243 @@ + + +logger::utils - Object Oriented logging facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

logger::utils(n) 1.3 tcllib "Object Oriented logging facility"

+

Name

+

logger::utils - Utilities for logger

+
+ + +

Description

+

This package adds template based appenders.

+
+
::logger::utils::createFormatCmd formatString
+

This command translates formatString into an expandable command +string. +The following strings are the known substitutions (from log4perl) +allowed to occur in the formatString:

+
+
%c
+

Category of the logging event

+
%C
+

Fully qualified name of logging event

+
%d
+

Current date in yyyy/MM/dd hh:mm:ss

+
%H
+

Hostname

+
%m
+

Message to be logged

+
%M
+

Method where logging event was issued

+
%p
+

Priority of logging event

+
%P
+

Pid of current process

+
+
::logger::utils::createLogProc -procName procName ?options...?
+

This command ...

+
+
-procName procName
+

The name of the procedure to create.

+
-conversionPattern pattern
+

See ::logger::utils::createFormatCmd for the substitutions +allowed in the pattern.

+
-category category
+

The category (service).

+
-priority priority
+

The priority (level).

+
-outputChannel channel
+

channel to output on (default stdout)

+
+
::logger::utils::applyAppender -appender appenderType ?options...?
+

This command will create an appender for the specified logger +services. If no service is specified then the appender will be added +as the default appender for the specified levels. If no levels are +specified, then all levels are assumed.

+
+
-service loggerservices
+
+
-serviceCmd loggerserviceCmds
+

Name of the logger instance to modify. -serviceCmd takes as +input the return of logger::init.

+
-appender appenderType
+

Type of the appender to use. +One of console, colorConsole.

+
-conversionPattern pattern
+

See ::logger::utils::createFormatCmd for the +format of the pattern. If this option is not provided +the default pattern

+
[%d] [%c] [%M] [%p] %m
+

is used.

+
-levels levelList
+

The list of levels to apply this appender to. If not specified all +levels are assumed.

+
+

Example of usage:

+
+   % set log [logger::init testLog]
+   ::logger::tree::testLog
+   % logger::utils::applyAppender -appender console -serviceCmd $log
+   % ${log}::error "this is an error"
+   [2005/08/22 10:14:13] [testLog] [global] [error] this is an error
+
+
+
::logger::utils::autoApplyAppender command command-string log op args...
+

This command is designed to be added via trace leave to calls +of logger::init. It will look at preconfigured state (via +::logger::utils::applyAppender) to autocreate appenders for +newly created logger instances. +It will return its argument log.

+

Example of usage:

+
+  logger::utils::applyAppender -appender console
+  set log [logger::init applyAppender-3]
+  ${log}::error "this is an error"
+
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html Index: embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html @@ -0,0 +1,224 @@ + + +map::geocode::nominatim - Mapping utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

map::geocode::nominatim(n) 0.1 tcllib "Mapping utilities"

+

Name

+

map::geocode::nominatim - Resolving geographical names with a Nominatim service

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require http
    • +
  • package require json
    • +
  • package require uri
    • +
  • package require snit
    • +
  • package require map::geocode::nominatim ?0.1?
    • +
+ +
+
+

Description

+

This package provides a class for accessing geocoding services which implement +the Nominatim interface (see References)

+
+

API

+
+
::map::geocode::nominatim requestor ?-baseurl url? ?-callback callback? ?-error error callback?
+

Creates a geocoding request object requestor, which will send its requests to +the Nominatim server.

+

The result of the command is name.

+
+

Options

+
+
-baseurl url
+

The base URL of the Nominatim service. Default value is OpenStreetMap's service at +http://nominatim.openstreetmap.org/search A possible free alternative is at +http://open.mapquestapi.com//nominatim/v1/search

+
-callback cmdprefix
+

A command prefix to be invoked when search result become available. +The default setting, active when nothing was specified on object creation, is to print +the result (see below) to stdout. The result of the command prefix is +ignored. Errors thrown by the command prefix are caught and cause the invokation of +the error callback (see option -error below), with the error message as argument.

+

The signature of the command prefix is:

+
+
$cmdprefix result
+

The result is a list of dictionaries, containing one item per hit. +Each dictionary will have the following entries:

+
+
place_id
+

The place ID (FIXME: what's this?)

+
licence
+

The data licence string

+
osm_type
+

The OSM type of the location

+
osm_id
+

FIXME

+
boundingbox
+

The coordinates of the bounding box (min and max latitude, min and max longitude)

+
lat
+

The location's latitude

+
lon
+

The location's longitude

+
display_name
+

the location's human readable name

+
class
+

FIXME

+
type
+

FIXME

+
icon
+

FIXME

+
+
+
-error cmdprefix
+

A command prefix to be invoked when encountering errors. Typically these are HTTP errors. +The default setting, active when nothing was specified on object creation, is to print +the errorstring (see below) to stderr. The result of the command prefix is +ignored. Errors thrown by the command prefix are passed to higher levels.

+

The signature of the command prefix is:

+
+
$cmdprefix errorstring
+
+
+
+
+

Methods

+
+
requestor search query
+

This method returns a list of dictionaries, one item per hit for the specified query.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy.html Index: embedded/www/tcllib/files/modules/map/map_slippy.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/map/map_slippy.html @@ -0,0 +1,282 @@ + + +map::slippy - Mapping utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

map::slippy(n) 0.5 tcllib "Mapping utilities"

+

Name

+

map::slippy - Common code for slippy based map packages

+
+ + +

Description

+

This package provides a number of methods doing things needed by all +types of slippy-based map packages.

+
+

API

+
+
::map::slippy length level
+

This method returns the width/height of a slippy-based map at the +specified zoom level, in pixels. This is, in essence, the result +of

+
+	expr { [tiles $level] * [tile size] }
+
+
+
::map::slippy tiles level
+

This method returns the width/height of a slippy-based map at the +specified zoom level, in tiles.

+
::map::slippy tile size
+

This method returns the width/height of a tile in a slippy-based map, +in pixels.

+
::map::slippy tile valid tile levels ?msgvar?
+

This method checks whether tile described a valid tile in a +slippy-based map containing that many zoom levels. The result is +a boolean value, true if the tile is valid, and false +otherwise. For the latter a message is left in the variable named by +msgvar, should it be specified.

+

A tile identifier as stored in tile is a list containing zoom +level, tile row, and tile column, in this order. The command +essentially checks this, i.e. the syntax, that the zoom level is +between 0 and "levels-1", and that the row/col information is +within the boundaries for the zoom level, i.e. 0 ... +"[tiles $zoom]-1".

+
::map::slippy geo 2tile geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses pure integer numbers for the tile +coordinates, for all geographic coordinates mapping to that tile.

+
::map::slippy geo 2tile.float geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses floating point numbers for the tile +coordinates, representing not only the tile the geographic coordinates +map to, but also the fractional location inside of that tile.

+
::map::slippy geo 2point geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +pixel position (list containing zoom level, y, and x) at that level.

+
::map::slippy tile 2geo tile
+

Converts a tile identifier at a zoom level (tile, list +containing zoom level, row, and column) to a geographical location +(list containing zoom level, latitude, and longitude, in this order) +at that level.

+
::map::slippy tile 2point tile
+

Converts a tile identifier at a zoom level (tile, a list +containing zoom level, row, and column, in this order) to a pixel +position (list containing zoom level, y, and x) at that level.

+
::map::slippy point 2geo point
+

Converts a pixel position at a zoom level (point, list +containing zoom level, y, and x) to a geographical location (list +containing zoom level, latitude, and longitude, in this order) at that +level.

+
::map::slippy point 2tile point
+

Converts a pixel position at a zoom level (point, a list +containing zoom level, y, and x, in this order) to a tile identifier +(list containing zoom level, row, and column) at that level.

+
::map::slippy fit geobox canvdim geobox zmin zmax
+

Calculates the zoom level (whithin the bounds zmin and +zmax) such that geobox (a 4-element list containing the +latitudes and longitudes lat0, lat1, lon0 and lon1 of a geo box, +in this order) fits into a viewport given by canvdim, a +2-element list containing the width and height of the viewport, in +this order.

+
+
+

Coordinate systems

+

The commands of this package operate on three distinct coordinate +systems, which are explained below.

+

Geographic

+

Geographical coordinates are represented by Latitude and +Longitude, each of which is measured in degrees, as they are +essentially angles.

+

Zero longitude is the Greenwich meridian, with +positive values going east, and negative values going +west, for a total range of +/- 180 degrees. Note that +180 and +-180 longitude are the same meridian, opposite to greenwich.

+

zero latitude the Equator, with positive values +going north and negative values going south. While the +true range is +/- 90 degrees the projection used by the package +requires us to cap the range at +/- 85.05112877983284 degrees. This +means that north and south pole are not representable and not part of +any map.

+
+

Tiles

+

While Geographical coordinates of the previous section are +independent of zoom level the tile coordinates are not.

+

Generally the integer part of tile coordinates represent the +row and column number of the tile in question, wheras the fractional +parts signal how far inside the tile the location in question is, with +pure integer coordinates (no fractional part) representing the upper +left corner of the tile.

+

The zero point of the map is at the upper left corner, +regardless of zoom level, with larger coordinates going right (east) +and down (south), and smaller coordinates going left (west) and up +(north). Again regardless of zxoom level.

+

Negative tile coordinates are not allowed.

+

At zoom level 0 the whole map is represented by a single, +putting the geographic zero at 1/2, 1/2 of tile coordinates, and the +range of tile coordinates as [0...1].

+

To go from a zoom level N to the next deeper level N+1 each +tile of level N is split into its four quadrants, which then are the +tiles of level N+1.

+

This means that at zoom level N the map is sliced (horizontally +and vertically) into 2^N stripes, for a total of 4^N tiles, with tile +coordinates ranging from 0 to 2^N+1.

+
+

Pixels/Points

+

pixel coordinates, also called point coordinates are +in essence tile coordinates scaled by the size of +the image representing a tile. This tile size currently has a fixed +value, 256.

+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy_cache.html Index: embedded/www/tcllib/files/modules/map/map_slippy_cache.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/map/map_slippy_cache.html @@ -0,0 +1,199 @@ + + +map::slippy::cache - Mapping utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

map::slippy::cache(n) 0.2 tcllib "Mapping utilities"

+

Name

+

map::slippy::cache - Management of a tile cache in the local filesystem

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require Tk 8.4
    • +
  • package require img::png
    • +
  • package require map::slippy
    • +
  • package require map::slippy::cache ?0.2?
    • +
+ +
+
+

Description

+

This package provides a class for managing a cache of tiles for +slippy-based maps in the local filesystem.

+
+

API

+
+
::map::slippy::cache cacheName cachedir provider
+

Creates the cache cacheName and configures it with both the path +to the directory contaiing the locally cached tiles (cachedir), +and the command prefix from which it will pull tiles asked for and not +yet known to the cache itself (provider).

+

The result of the command is cacheName.

+
+

Methods

+
+
cacheName valid tile ?msgvar?
+

This method checks the validity of a the given tile identifier. +This is a convenience wrapper to ::map::slippy tile valid and +has the same interface.

+
cacheName exists tile
+

This methods tests whether the cache contains the specified tile +or not. The result is a boolean value, true if the tile is +known, and false otherwise. The tile is identified by a list +containing three elements, zoom level, row, and column number, in this +order.

+
cacheName get tile donecmd
+

This is the main method of the cache, retrieving the image for the +specified tile from the cache. The tile identifier is a list +containing three elements, the zoom level, row, and column number of +the tile, in this order.

+

The command refix donecmd will be invoked when the cache +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e.

+
    +

  1. The string set, the tile, and the image.

    2. +

  2. The string unset, and the tile.

    3. +
+

These two possibilities are used to either signal the image for the +tile, or that the tile has no image defined for it.

+

When the cache has no information about the tile it will invoke the +provider command prefix specified during its construction, +adding three arguments: The string get, the tile, and a +callback into the cache. The latter will be invoked by the provider to +either transfer the image to the cache, or signal that the tile has no +image.

+

When multiple requests for the same tile are made only one request +will be issued to the provider.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html Index: embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html @@ -0,0 +1,188 @@ + + +map::slippy::fetcher - Mapping utilities + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

map::slippy::fetcher(n) 0.3 tcllib "Mapping utilities"

+

Name

+

map::slippy::fetcher - Accessing a server providing tiles for slippy-based maps

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require Tk 8.4
    • +
  • package require img::png
    • +
  • package require map::slippy
    • +
  • package require map::slippy::fetcher ?0.3?
    • +
+ +
+
+

Description

+

This package provides a class for accessing http servers providing +tiles for slippy-based maps.

+
+

API

+
+
::map::slippy::fetcher fetcherName levels url
+

Creates the fetcher fetcherName and configures it with the +number of zoom levels supported by the tile server, and the +url it is listening on for tile requests.

+

The result of the command is fetcherName.

+
+

Methods

+
+
fetcherName levels
+

This method returns the number of zoom levels supported by the fetcher +object, and the tile server it is accessing.

+
fetcherName tileheight
+

This method returns the height of tiles served, in pixels.

+
fetcherName tilewidth
+

This method returns the width of tiles served, in pixels.

+
fetcherName get tile donecmd
+

This is the main method of the fetcher, retrieving the image for the +specified tile. The tile identifier is a list containing three +elements, the zoom level, row, and column number of the tile, in this +order.

+

The command refix donecmd will be invoked when the fetcher +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e.

+
    +

  1. The string set, the tile, and the image.

    2. +

  2. The string unset, and the tile.

    3. +
+

These two possibilities are used to either signal the image for the +tile, or that the tile has no image defined for it.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/mapproj/mapproj.html Index: embedded/www/tcllib/files/modules/mapproj/mapproj.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/mapproj/mapproj.html @@ -0,0 +1,453 @@ + + +mapproj - Tcl Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

mapproj(n) 0.1 tcllib "Tcl Library"

+

Name

+

mapproj - Map projection routines

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.4?
    • +
  • package require math::interpolate ?1.0?
    • +
  • package require math::special ?0.2.1?
    • +
  • package require mapproj ?1.0?
    • +
+ +
+
+

Description

+

The mapproj package provides a set of procedures for +converting between world co-ordinates (latitude and longitude) and map +co-ordinates on a number of different map projections.

+
+

Commands

+

The following commands convert between world co-ordinates and +map co-ordinates:

+
+
::mapproj::toPlateCarree lambda_0 phi_0 lambda phi
+

Converts to the plate carrée (cylindrical equidistant) +projection.

+
::mapproj::fromPlateCarree lambda_0 phi_0 x y
+

Converts from the plate carrée (cylindrical equidistant) +projection.

+
::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the cylindrical equal-area projection.

+
::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y
+

Converts from the cylindrical equal-area projection.

+
::mapproj::toMercator lambda_0 phi_0 lambda phi
+

Converts to the Mercator (cylindrical conformal) projection.

+
::mapproj::fromMercator lambda_0 phi_0 x y
+

Converts from the Mercator (cylindrical conformal) projection.

+
::mapproj::toMillerCylindrical lambda_0 lambda phi
+

Converts to the Miller Cylindrical projection.

+
::mapproj::fromMillerCylindrical lambda_0 x y
+

Converts from the Miller Cylindrical projection.

+
::mapproj::toSinusoidal lambda_0 phi_0 lambda phi
+

Converts to the sinusoidal (Sanson-Flamsteed) projection. +projection.

+
::mapproj::fromSinusoidal lambda_0 phi_0 x y
+

Converts from the sinusoidal (Sanson-Flamsteed) projection. +projection.

+
::mapproj::toMollweide lambda_0 lambda phi
+

Converts to the Mollweide projection.

+
::mapproj::fromMollweide lambda_0 x y
+

Converts from the Mollweide projection.

+
::mapproj::toEckertIV lambda_0 lambda phi
+

Converts to the Eckert IV projection.

+
::mapproj::fromEckertIV lambda_0 x y
+

Converts from the Eckert IV projection.

+
::mapproj::toEckertVI lambda_0 lambda phi
+

Converts to the Eckert VI projection.

+
::mapproj::fromEckertVI lambda_0 x y
+

Converts from the Eckert VI projection.

+
::mapproj::toRobinson lambda_0 lambda phi
+

Converts to the Robinson projection.

+
::mapproj::fromRobinson lambda_0 x y
+

Converts from the Robinson projection.

+
::mapproj::toCassini lambda_0 phi_0 lambda phi
+

Converts to the Cassini (transverse cylindrical equidistant) +projection.

+
::mapproj::fromCassini lambda_0 phi_0 x y
+

Converts from the Cassini (transverse cylindrical equidistant) +projection.

+
::mapproj::toPeirceQuincuncial lambda_0 lambda phi
+

Converts to the Peirce Quincuncial Projection.

+
::mapproj::fromPeirceQuincuncial lambda_0 x y
+

Converts from the Peirce Quincuncial Projection.

+
::mapproj::toOrthographic lambda_0 phi_0 lambda phi
+

Converts to the orthographic projection.

+
::mapproj::fromOrthographic lambda_0 phi_0 x y
+

Converts from the orthographic projection.

+
::mapproj::toStereographic lambda_0 phi_0 lambda phi
+

Converts to the stereographic (azimuthal conformal) projection.

+
::mapproj::fromStereographic lambda_0 phi_0 x y
+

Converts from the stereographic (azimuthal conformal) projection.

+
::mapproj::toGnomonic lambda_0 phi_0 lambda phi
+

Converts to the gnomonic projection.

+
::mapproj::fromGnomonic lambda_0 phi_0 x y
+

Converts from the gnomonic projection.

+
::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi
+

Converts to the azimuthal equidistant projection.

+
::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y
+

Converts from the azimuthal equidistant projection.

+
::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the Lambert azimuthal equal-area projection.

+
::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y
+

Converts from the Lambert azimuthal equal-area projection.

+
::mapproj::toHammer lambda_0 lambda phi
+

Converts to the Hammer projection.

+
::mapproj::fromHammer lambda_0 x y
+

Converts from the Hammer projection.

+
::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the conic equidistant projection.

+
::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the conic equidistant projection.

+
::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the Albers equal-area conic projection.

+
::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the Albers equal-area conic projection.

+
::mapproj::toLambertConformalConic lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the Lambert conformal conic projection.

+
::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the Lambert conformal conic projection.

+
+

Among the cylindrical equal-area projections, there are a number of +choices of standard parallels that have names:

+
+
::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the Lambert cylindrical equal area projection. (standard parallel +is the Equator.)

+
::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y
+

Converts from the Lambert cylindrical equal area projection. (standard parallel +is the Equator.)

+
::mapproj::toBehrmann lambda_0 phi_0 lambda phi
+

Converts to the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South)

+
::mapproj::fromBehrmann lambda_0 phi_0 x y
+

Converts from the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South.)

+
::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi
+

Converts to the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South)

+
::mapproj::fromTrystanEdwards lambda_0 phi_0 x y
+

Converts from the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South.)

+
::mapproj::toHoboDyer lambda_0 phi_0 lambda phi
+

Converts to the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South)

+
::mapproj::fromHoboDyer lambda_0 phi_0 x y
+

Converts from the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South.)

+
::mapproj::toGallPeters lambda_0 phi_0 lambda phi
+

Converts to the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South)

+
::mapproj::fromGallPeters lambda_0 phi_0 x y
+

Converts from the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South.)

+
::mapproj::toBalthasart lambda_0 phi_0 lambda phi
+

Converts to the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South)

+
::mapproj::fromBalthasart lambda_0 phi_0 x y
+

Converts from the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South.)

+
+
+

Arguments

+

The following arguments are accepted by the projection commands:

+
+
lambda
+

Longitude of the point to be projected, in degrees.

+
phi
+

Latitude of the point to be projected, in degrees.

+
lambda_0
+

Longitude of the center of the sheet, in degrees. For many projections, +this figure is also the reference meridian of the projection.

+
phi_0
+

Latitude of the center of the sheet, in degrees. For the azimuthal +projections, this figure is also the latitude of the center of the projection.

+
phi_1
+

Latitude of the first reference parallel, for projections that use reference +parallels.

+
phi_2
+

Latitude of the second reference parallel, for projections that use reference +parallels.

+
x
+

X co-ordinate of a point on the map, in units of Earth radii.

+
y
+

Y co-ordinate of a point on the map, in units of Earth radii.

+
+
+

Results

+

For all of the procedures whose names begin with 'to', the return value +is a list comprising an x co-ordinate and a y co-ordinate. +The co-ordinates are relative to the center of the map sheet to be drawn, +measured in Earth radii at the reference location on the map. +For all of the functions whose names begin with 'from', the return value +is a list comprising the longitude and latitude, in degrees.

+
+

Choosing a projection

+

This package offers a great many projections, because no single projection +is appropriate to all maps. This section attempts to provide guidance +on how to choose a projection.

+

First, consider the type of data that you intend to display on the map. +If the data are directional (e.g., winds, ocean currents, or +magnetic fields) then you need to use a projection that preserves +angles; these are known as conformal projections. Conformal +projections include the Mercator, the Albers azimuthal equal-area, +the stereographic, and the Peirce Quincuncial projection. If the +data are thematic, describing properties of land or water, such +as temperature, population density, land use, or demographics; then +you need a projection that will show these data with the areas on the map +proportional to the areas in real life. These so-called equal area +projections include the various cylindrical equal area projections, +the sinusoidal projection, the Lambert azimuthal equal-area projection, +the Albers equal-area conic projection, and several of the world-map +projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, +and Hammer). If the significant factor in your data is distance from a +central point or line (such as air routes), then you will do best with +an equidistant projection such as plate carrée, +Cassini, azimuthal equidistant, or conic equidistant. If direction from +a central point is a critical factor in your data (for instance, +air routes, radio antenna pointing), then you will almost surely want to +use one of the azimuthal projections. Appropriate choices are azimuthal +equidistant, azimuthal equal-area, stereographic, and perhaps orthographic.

+

Next, consider how much of the Earth your map will cover, and the general +shape of the area of interest. For maps of the entire Earth, +the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer +projections are good overall choices. The Mercator projection is traditional, +but the extreme distortions of area at high latitudes make it +a poor choice unless a conformal projection is required. The Peirce +projection is a better choice of conformal projection, having less distortion +of landforms. The Miller Cylindrical is a compromise designed to give +shapes similar to the traditional Mercator, but with less polar stretching. +The Peirce Quincuncial projection shows all the continents with acceptable +distortion if a reference meridian close to +20 degrees is chosen. +The Robinson projection yields attractive maps for things like political +divisions, but should be avoided in presenting scientific data, since other +projections have moe useful geometric properties.

+

If the map will cover a hemisphere, then choose stereographic, +azimuthal-equidistant, Hammer, or Mollweide projections; these all project +the hemisphere into a circle.

+

If the map will cover a large area (at least a few hundred km on a side), +but less than +a hemisphere, then you have several choices. Azimuthal projections +are usually good (choose stereographic, azimuthal equidistant, or +Lambert azimuthal equal-area according to whether shapes, distances from +a central point, or areas are important). Azimuthal projections (and possibly +the Cassini projection) are the only +really good choices for mapping the polar regions.

+

If the large area is in one of the temperate zones and is round or has +a primarily east-west extent, then the conic projections are good choices. +Choose the Lambert conformal conic, the conic equidistant, or the Albers +equal-area conic according to whether shape, distance, or area are the +most important parameters. For any of these, the reference parallels +should be chosen at approximately 1/6 and 5/6 of the range of latitudes +to be displayed. For instance, maps of the 48 coterminous United States +are attractive with reference parallels of 28.5 and 45.5 degrees.

+

If the large area is equatorial and is round or has a primarily east-west +extent, then the Mercator projection is a good choice for a conformal +projection; Lambert cylindrical equal-area and sinusoidal projections are +good equal-area projections; and the plate carrée is a +good equidistant projection.

+

Large areas having a primarily North-South aspect, particularly those +spanning the Equator, need some other choices. The Cassini projection +is a good choice for an equidistant projection (for instance, a Cassini +projection with a central meridian of 80 degrees West produces an +attractive map of the Americas). The cylindrical equal-area, Albers +equal-area conic, sinusoidal, Mollweide and Hammer +projections are possible choices for equal-area projections. +A good conformal projection in this situation is the Transverse +Mercator, which alas, is not yet implemented.

+

Small areas begin to get into a realm where the ellipticity of the +Earth affects the map scale. This package does not attempt to +handle accurate mapping for large-scale topographic maps. If +slight scale errors are acceptable in your application, then any +of the projections appropriate to large areas should work for +small ones as well.

+

There are a few projections that are included for their special +properties. The orthographic projection produces views of the +Earth as seen from space. The gnomonic projection produces a +map on which all great circles (the shortest distance between +two points on the Earth's surface) are rendered as straight lines. +While this projection is useful for navigational planning, it +has extreme distortions of shape and area, and can display +only a limited area of the Earth (substantially less than a hemisphere).

+
+ + +
ADDED embedded/www/tcllib/files/modules/math/bigfloat.html Index: embedded/www/tcllib/files/modules/math/bigfloat.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/bigfloat.html @@ -0,0 +1,575 @@ + +math::bigfloat - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::bigfloat(n) 2.0.1 tcllib "Tcl Math Library"

+

Name

+

math::bigfloat - Arbitrary precision floating-point numbers

+
+ + +

Description

+

The bigfloat package provides arbitrary precision floating-point math +capabilities to the Tcl language. It is designed to work with Tcl 8.5, +but for Tcl 8.4 is provided an earlier version of this package. +See WHAT ABOUT TCL 8.4 ? for more explanations. +By convention, we will talk about the numbers treated in this library as :

+
    +

  • BigFloat for floating-point numbers of arbitrary length.

    • +

  • integers for arbitrary length signed integers, just as basic integers since Tcl 8.5.

    • +
+

Each BigFloat is an interval, namely [m-d, m+d], +where m is the mantissa and d the uncertainty, representing the +limitation of that number's precision. +This is why we call such mathematics interval computations. +Just take an example in physics : when you measure a temperature, not all +digits you read are significant. Sometimes you just cannot trust all digits - not to mention if doubles (f.p. numbers) can handle all these digits. +BigFloat can handle this problem - trusting the digits you get - plus the ability to store numbers with an arbitrary precision. +BigFloats are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to :

+
    +

  • perform math operations on BigFloats and (optionnaly) with integers.

    • +

  • convert BigFloats from their internal representations to strings, and vice versa.

    • +
+
+

INTRODUCTION

+
+
fromstr number ?trailingZeros?
+

Converts number into a BigFloat. Its precision +is at least the number of digits provided by number. +If the number contains only digits and eventually a minus sign, it is considered as +an integer. Subsequently, no conversion is done at all.

+

trailingZeros - the number of zeros to append at the end of the floating-point number +to get more precision. It cannot be applied to an integer.

+
+# x and y are BigFloats : the first string contained a dot, and the second an e sign
+set x [fromstr -1.000000]
+set y [fromstr 2000e30]
+# let's see how we get integers
+set t 20000000000000
+# the old way (package 1.2) is still supported for backwards compatibility :
+set m [fromstr 10000000000]
+# but we do not need fromstr for integers anymore
+set n -39
+# t, m and n are integers
+
+

The number's last digit is considered by the procedure to be true at +/-1, +For example, 1.00 is the interval [0.99, 1.01], +and 0.43 the interval [0.42, 0.44]. +The Pi constant may be approximated by the number "3.1415". +This string could be considered as the interval [3.1414 , 3.1416] by fromstr. +So, when you mean 1.0 as a double, you may have to write 1.000000 to get enough precision. +To learn more about this subject, see PRECISION.

+

For example :

+
+set x [fromstr 1.0000000000]
+# the next line does the same, but smarter
+set y [fromstr 1. 10]
+
+
+
tostr ?-nosci? number
+

Returns a string form of a BigFloat, in which all digits are exacts. +All exact digits means a rounding may occur, for example to zero, +if the uncertainty interval does not clearly show the true digits. +number may be an integer, causing the command to return exactly the input argument. +With the -nosci option, the number returned is never shown in scientific +notation, i.e. not like '3.4523e+5' but like '345230.'.

+
+puts [tostr [fromstr 0.99999]] ;# 1.0000
+puts [tostr [fromstr 1.00001]] ;# 1.0000
+puts [tostr [fromstr 0.002]] ;# 0.e-2
+
+

See PRECISION for that matter. +See also iszero for how to detect zeros, which is useful when performing a division.

+
fromdouble double ?decimals?
+

Converts a double (a simple floating-point value) to a BigFloat, with +exactly decimals digits. Without the decimals argument, +it behaves like fromstr. +Here, the only important feature you might care of is the ability +to create BigFloats with a fixed number of decimals.

+
+tostr [fromstr 1.111 4]
+# returns : 1.111000 (3 zeros)
+tostr [fromdouble 1.111 4]
+# returns : 1.111
+
+
+
todouble number
+

Returns a double, that may be used in expr, +from a BigFloat.

+
isInt number
+

Returns 1 if number is an integer, 0 otherwise.

+
isFloat number
+

Returns 1 if number is a BigFloat, 0 otherwise.

+
int2float integer ?decimals?
+

Converts an integer to a BigFloat with decimals trailing zeros. +The default, and minimal, number of decimals is 1. +When converting back to string, one decimal is lost:

+
+set n 10
+set x [int2float $n]; # like fromstr 10.0
+puts [tostr $x]; # prints "10."
+set x [int2float $n 3]; # like fromstr 10.000
+puts [tostr $x]; # prints "10.00"
+
+
+
+
+

ARITHMETICS

+
+
add x y
+
+
sub x y
+
+
mul x y
+

Return the sum, difference and product of x by y. +x - may be either a BigFloat or an integer +y - may be either a BigFloat or an integer +When both are integers, these commands behave like expr.

+
div x y
+
+
mod x y
+

Return the quotient and the rest of x divided by y. +Each argument (x and y) can be either a BigFloat or an integer, +but you cannot divide an integer by a BigFloat +Divide by zero throws an error.

+
abs x
+

Returns the absolute value of x

+
opp x
+

Returns the opposite of x

+
pow x n
+

Returns x taken to the nth power. +It only works if n is an integer. +x might be a BigFloat or an integer.

+
+
+

COMPARISONS

+
+
iszero x
+

Returns 1 if x is :

+
    +

  • a BigFloat close enough to zero to raise "divide by zero".

    • +

  • the integer 0.

    • +
+

See here how numbers that are close to zero are converted to strings:

+
+tostr [fromstr 0.001] ; # -> 0.e-2
+tostr [fromstr 0.000000] ; # -> 0.e-5
+tostr [fromstr -0.000001] ; # -> 0.e-5
+tostr [fromstr 0.0] ; # -> 0.
+tostr [fromstr 0.002] ; # -> 0.e-2
+set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003
+tostr  $a ; # 0.e-2
+iszero $a ; # false
+set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002
+tostr  $a ; # 0.e-2
+iszero $a ; # true
+
+
+
equal x y
+

Returns 1 if x and y are equal, 0 elsewhere.

+
compare x y
+

Returns 0 if both BigFloat arguments are equal, +1 if x is greater than y, +and -1 if x is lower than y. +You would not be able to compare an integer to a BigFloat : +the operands should be both BigFloats, or both integers.

+
+
+

ANALYSIS

+
+
sqrt x
+
+
log x
+
+
exp x
+
+
cos x
+
+
sin x
+
+
tan x
+
+
cotan x
+
+
acos x
+
+
asin x
+
+
atan x
+
+
cosh x
+
+
sinh x
+
+
tanh x
+

The above functions return, respectively, the following : +square root, logarithm, exponential, cosine, sine, +tangent, cotangent, arc cosine, arc sine, arc tangent, hyperbolic +cosine, hyperbolic sine, hyperbolic tangent, of a BigFloat named x.

+
pi n
+

Returns a BigFloat representing the Pi constant with n digits after the dot. +n is a positive integer.

+
rad2deg radians
+
+
deg2rad degrees
+

radians - angle expressed in radians (BigFloat)

+

degrees - angle expressed in degrees (BigFloat)

+

Convert an angle from radians to degrees, and vice versa.

+
+
+

ROUNDING

+
+
round x
+
+
ceil x
+
+
floor x
+

The above functions return the x BigFloat, +rounded like with the same mathematical function in expr, +and returns it as an integer.

+
+
+

PRECISION

+

How do conversions work with precision ?

+
    +

  • When a BigFloat is converted from string, the internal representation +holds its uncertainty as 1 at the level of the last digit.

    • +

  • During computations, the uncertainty of each result +is internally computed the closest to the reality, thus saving the memory used.

    • +

  • When converting back to string, the digits that are printed +are not subject to uncertainty. However, some rounding is done, as not doing so +causes severe problems.

    • +
+

Uncertainties are kept in the internal representation of the number ; +it is recommended to use tostr only for outputting data (on the screen or in a file), +and NEVER call fromstr with the result of tostr. +It is better to always keep operands in their internal representation. +Due to the internals of this library, the uncertainty interval may be slightly +wider than expected, but this should not cause false digits.

+

Now you may ask this question : What precision am I going to get +after calling add, sub, mul or div? +First you set a number from the string representation and, +by the way, its uncertainty is set:

+
+set a [fromstr 1.230]
+# $a belongs to [1.229, 1.231]
+set a [fromstr 1.000]
+# $a belongs to [0.999, 1.001]
+# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value)
+
+

The uncertainty of the sum, or the difference, of two numbers, is the sum +of their respective uncertainties.

+
+set a [fromstr 1.230]
+set b [fromstr 2.340]
+set sum [add $a $b]]
+# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2)
+tostr $sum ; # 3.57
+
+

But when, for example, we add or substract an integer to a BigFloat, +the relative uncertainty of the result is unchanged. So it is desirable +not to convert integers to BigFloats:

+
+set a [fromstr 0.999999999]
+# now something dangerous
+set b [fromstr 2.000]
+# the result has only 3 digits
+tostr [add $a $b]
+# how to keep precision at its maximum
+puts [tostr [add $a 2]]
+
+

For multiplication and division, the relative uncertainties of the product +or the quotient, is the sum of the relative uncertainties of the operands. +Take care of division by zero : check each divider with iszero.

+
+set num [fromstr 4.00]
+set denom [fromstr 0.01]
+puts [iszero $denom];# true
+set quotient [div $num $denom];# error : divide by zero
+# opposites of our operands
+puts [compare $num [opp $num]]; # 1
+puts [compare $denom [opp $denom]]; # 0 !!!
+# No suprise ! 0 and its opposite are the same...
+
+

Effects of the precision of a number considered equal to zero +to the cos function:

+
+puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000
+puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000
+puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000
+puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000
+
+

BigFloats with different internal representations may be converted +to the same string.

+

For most analysis functions (cosine, square root, logarithm, etc.), determining the precision +of the result is difficult. +It seems however that in many cases, the loss of precision in the result +is of one or two digits. +There are some exceptions : for example,

+
+tostr [exp [fromstr 100.0 10]]
+# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry
+# has 14 digits of precision.
+
+
+

WHAT ABOUT TCL 8.4 ?

+

If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be loaded, +switching back to math::bigfloat 1.2. Indeed, an important function introduced in Tcl 8.5 +is required - the ability to handle bignums, that we can do with expr. +Before 8.5, this ability was provided by several packages, +including the pure-Tcl math::bignum package provided by tcllib. +In this case, all you need to know, is that arguments to the commands explained here, +are expected to be in their internal representation. +So even with integers, you will need to call fromstr +and tostr in order to convert them between string and internal representations.

+
+#
+# with Tcl 8.5
+# ============
+set a [pi 20]
+# round returns an integer and 'everything is a string' applies to integers
+# whatever big they are
+puts [round [mul $a 10000000000]]
+#
+# the same with Tcl 8.4
+# =====================
+set a [pi 20]
+# bignums (arbitrary length integers) need a conversion hook
+set b [fromstr 10000000000]
+# round returns a bignum:
+# before printing it, we need to convert it with 'tostr'
+puts [tostr [round [mul $a $b]]]
+
+
+

NAMESPACES AND OTHER PACKAGES

+

We have not yet discussed about namespaces +because we assumed that you had imported public commands into the global namespace, +like this:

+
+namespace import ::math::bigfloat::*
+
+

If you matter much about avoiding names conflicts, +I considere it should be resolved by the following :

+
+package require math::bigfloat
+# beware: namespace ensembles are not available in Tcl 8.4 
+namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat}
+# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands
+set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]]
+puts [bigfloat tostr $a]
+
+
+

EXAMPLES

+

Guess what happens when you are doing some astronomy. Here is an example :

+
+# convert acurrate angles with a millisecond-rated accuracy
+proc degree-angle {degrees minutes seconds milliseconds} {
+    set result 0
+    set div 1
+    foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] {
+        # we convert each entry var into milliseconds
+        set div [expr {$div*$factor}]
+        incr result [expr {$var*$div}]
+    }
+    return [div [int2float $result] $div]
+}
+# load the package
+package require math::bigfloat
+namespace import ::math::bigfloat::*
+# work with angles : a standard formula for navigation (taking bearings)
+set angle1 [deg2rad [degree-angle 20 30 40   0]]
+set angle2 [deg2rad [degree-angle 21  0 50 500]]
+set opposite3 [deg2rad [degree-angle 51  0 50 500]]
+set sinProduct [mul [sin $angle1] [sin $angle2]]
+set cosProduct [mul [cos $angle1] [cos $angle2]]
+set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]]
+puts "angle3 : [tostr [rad2deg $angle3]]"
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: bignum :: float of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/bignum.html Index: embedded/www/tcllib/files/modules/math/bignum.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/bignum.html @@ -0,0 +1,349 @@ + + +math::bignum - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::bignum(n) 3.1 tcllib "Tcl Math Library"

+

Name

+

math::bignum - Arbitrary precision integer numbers

+
+ + +

Description

+

The bignum package provides arbitrary precision integer math +(also known as "big numbers") capabilities to the Tcl language. +Big numbers are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to:

+
    +

  • perform math operations

    • +

  • convert bignums from the internal representation to a string in +the desired radix and vice versa.

    • +
+

But the two constants "0" and "1" are automatically converted to +the internal representation, in order to easily compare a number to zero, +or increment a big number.

+

The bignum interface is opaque, so +operations on bignums that are not returned by procedures +in this package (but created by hand) may lead to unspecified behaviours. +It's safe to treat bignums as pure values, so there is no need +to free a bignum, or to duplicate it via a special operation.

+
+

EXAMPLES

+

This section shows some simple example. This library being just +a way to perform math operations, examples may be the simplest way +to learn how to work with it. Consult the API section of +this man page for information about individual procedures.

+
+    package require math::bignum
+    # Multiplication of two bignums
+    set a [::math::bignum::fromstr 88888881111111]
+    set b [::math::bignum::fromstr 22222220000000]
+    set c [::math::bignum::mul $a $b]
+    puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000
+    set c [::math::bignum::sqrt $c]
+    puts [::math::bignum::tostr $c] ; # => will output 44444440277777
+    # From/To string conversion in different radix
+    set a [::math::bignum::fromstr 1100010101010111001001111010111 2]
+    puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7
+    # Factorial example
+    proc fact n {
+        # fromstr is not needed for 0 and 1
+        set z 1
+        for {set i 2} {$i <= $n} {incr i} {
+            set z [::math::bignum::mul $z [::math::bignum::fromstr $i]]
+        }
+        return $z
+    }
+    puts [::math::bignum::tostr [fact 100]]
+
+
+

API

+
+
::math::bignum::fromstr string ?radix?
+

Convert string into a bignum. If radix is omitted or zero, +the string is interpreted in hex if prefixed with +0x, in octal if prefixed with ox, +in binary if it's pefixed with bx, as a number in +radix 10 otherwise. If instead the radix argument +is specified in the range 2-36, the string is interpreted +in the given radix. Please note that this conversion is +not needed for two constants : 0 and 1. (see the example)

+
::math::bignum::tostr bignum ?radix?
+

Convert bignum into a string representing the number +in the specified radix. If radix is omitted, the +default is 10.

+
::math::bignum::sign bignum
+

Return the sign of the bignum. +The procedure returns 0 if the number is positive, 1 if it's negative.

+
::math::bignum::abs bignum
+

Return the absolute value of the bignum.

+
::math::bignum::cmp a b
+

Compare the two bignums a and b, returning 0 if a == b, +1 if a > b, and -1 if a < b.

+
::math::bignum::iszero bignum
+

Return true if bignum value is zero, otherwise false is returned.

+
::math::bignum::lt a b
+

Return true if a < b, otherwise false is returned.

+
::math::bignum::le a b
+

Return true if a <= b, otherwise false is returned.

+
::math::bignum::gt a b
+

Return true if a > b, otherwise false is returned.

+
::math::bignum::ge a b
+

Return true if a >= b, otherwise false is returned.

+
::math::bignum::eq a b
+

Return true if a == b, otherwise false is returned.

+
::math::bignum::ne a b
+

Return true if a != b, otherwise false is returned.

+
::math::bignum::isodd bignum
+

Return true if bignum is odd.

+
::math::bignum::iseven bignum
+

Return true if bignum is even.

+
::math::bignum::add a b
+

Return the sum of the two bignums a and b.

+
::math::bignum::sub a b
+

Return the difference of the two bignums a and b.

+
::math::bignum::mul a b
+

Return the product of the two bignums a and b. +The implementation uses Karatsuba multiplication if both +the numbers are bigger than a given threshold, otherwise +the direct algorith is used.

+
::math::bignum::divqr a b
+

Return a two-elements list containing as first element +the quotient of the division between the two bignums +a and b, and the remainder of the division as second element.

+
::math::bignum::div a b
+

Return the quotient of the division between the two +bignums a and b.

+
::math::bignum::rem a b
+

Return the remainder of the division between the two +bignums a and b.

+
::math::bignum::mod n m
+

Return n modulo m. This operation is +called modular reduction.

+
::math::bignum::pow base exp
+

Return base raised to the exponent exp.

+
::math::bignum::powm base exp m
+

Return base raised to the exponent exp, +modulo m. This function is often used in the field +of cryptography.

+
::math::bignum::sqrt bignum
+

Return the integer part of the square root of bignum

+
::math::bignum::rand bits
+

Return a random number of at most bits bits. +The returned number is internally generated using Tcl's expr rand() +function and is not suitable where an unguessable and cryptographically +secure random number is needed.

+
::math::bignum::lshift bignum bits
+

Return the result of left shifting bignum's binary +representation of bits positions on the left. +This is equivalent to multiplying by 2^bits but much faster.

+
::math::bignum::rshift bignum bits
+

Return the result of right shifting bignum's binary +representation of bits positions on the right. +This is equivalent to dividing by 2^bits but much faster.

+
::math::bignum::bitand a b
+

Return the result of doing a bitwise AND operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::bitor a b
+

Return the result of doing a bitwise OR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::bitxor a b
+

Return the result of doing a bitwise XOR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::setbit bignumVar bit
+

Set the bit at bit position to 1 in the bignum stored +in the variable bignumVar. Bit 0 is the least significant.

+
::math::bignum::clearbit bignumVar bit
+

Set the bit at bit position to 0 in the bignum stored +in the variable bignumVar. Bit 0 is the least significant.

+
::math::bignum::testbit bignum bit
+

Return true if the bit at the bit position of bignum +is on, otherwise false is returned. If bit is out of +range, it is considered as set to zero.

+
::math::bignum::bits bignum
+

Return the number of bits needed to represent bignum in radix 2.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: bignum of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/calculus.html Index: embedded/www/tcllib/files/modules/math/calculus.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/calculus.html @@ -0,0 +1,474 @@ + +math::calculus - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::calculus(n) 0.7.1 tcllib "Tcl Math Library"

+

Name

+

math::calculus - Integration and ordinary differential equations

+
+ + +

Description

+

This package implements several simple mathematical algorithms:

+
    +

  • The integration of a function over an interval

    • +

  • The numerical integration of a system of ordinary differential +equations.

    • +

  • Estimating the root(s) of an equation of one variable.

    • +
+

The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, well-known +algorithms have been used in a straightforward manner.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::math::calculus::integral begin end nosteps func
+

Determine the integral of the given function using the Simpson +rule. The interval for the integration is [begin, end]. +The remaining arguments are:

+
+
nosteps
+

Number of steps in which the interval is divided.

+
func
+

Function to be integrated. It should take one single argument.

+
+
::math::calculus::integralExpr begin end nosteps expression
+

Similar to the previous proc, this one determines the integral of +the given expression using the Simpson rule. +The interval for the integration is [begin, end]. +The remaining arguments are:

+
+
nosteps
+

Number of steps in which the interval is divided.

+
expression
+

Expression to be integrated. It should +use the variable "x" as the only variable (the "integrate")

+
+
::math::calculus::integral2D xinterval yinterval func
+
+
::math::calculus::integral2D_accurate xinterval yinterval func
+

The commands integral2D and integral2D_accurate calculate the +integral of a function of two variables over the rectangle given by the +first two arguments, each a list of three items, the start and +stop interval for the variable and the number of steps.

+

The command integral2D evaluates the function at the centre of +each rectangle, whereas the command integral2D_accurate uses a +four-point quadrature formula. This results in an exact integration of +polynomials of third degree or less.

+

The function must take two arguments and return the function +value.

+
::math::calculus::integral3D xinterval yinterval zinterval func
+
+
::math::calculus::integral3D_accurate xinterval yinterval zinterval func
+

The commands integral3D and integral3D_accurate are the +three-dimensional equivalent of integral2D and integral3D_accurate. +The function func takes three arguments and is integrated over the block in +3D space given by three intervals.

+
::math::calculus::eulerStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Euler's.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::heunStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Heun's.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::rungeKuttaStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Runge-Kutta 4th +order.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::boundaryValueSecondOrder coeff_func force_func leftbnd rightbnd nostep
+

Solve a second order linear differential equation with boundary +values at two sides. The equation has to be of the form (the +"conservative" form):

+
+         d      dy     d
+         -- A(x)--  +  -- B(x)y + C(x)y  =  D(x)
+         dx     dx     dx
+
+

Ordinarily, such an equation would be written as:

+
+             d2y        dy
+         a(x)---  + b(x)-- + c(x) y  =  D(x)
+             dx2        dx
+
+

The first form is easier to discretise (by integrating over a +finite volume) than the second form. The relation between the two +forms is fairly straightforward:

+
+         A(x)  =  a(x)
+         B(x)  =  b(x) - a'(x)
+         C(x)  =  c(x) - B'(x)  =  c(x) - b'(x) + a''(x)
+
+

Because of the differentiation, however, it is much easier to ask +the user to provide the functions A, B and C directly.

+
+
coeff_func
+

Procedure returning the three coefficients +(A, B, C) of the equation, taking as its one argument the x-coordinate.

+
force_func
+

Procedure returning the right-hand side +(D) as a function of the x-coordinate.

+
leftbnd
+

A list of two values: the x-coordinate of the +left boundary and the value at that boundary.

+
rightbnd
+

A list of two values: the x-coordinate of the +right boundary and the value at that boundary.

+
nostep
+

Number of steps by which to discretise the +interval. +The procedure returns a list of x-coordinates and the approximated +values of the solution.

+
+
::math::calculus::solveTriDiagonal acoeff bcoeff ccoeff dvalue
+

Solve a system of linear equations Ax = b with A a tridiagonal +matrix. Returns the solution as a list.

+
+
acoeff
+

List of values on the lower diagonal

+
bcoeff
+

List of values on the main diagonal

+
ccoeff
+

List of values on the upper diagonal

+
dvalue
+

List of values on the righthand-side

+
+
::math::calculus::newtonRaphson func deriv initval
+

Determine the root of an equation given by

+
+    func(x) = 0
+
+

using the method of Newton-Raphson. The procedure takes the following +arguments:

+
+
func
+

Procedure that returns the value the function at x

+
deriv
+

Procedure that returns the derivative of the function at x

+
initval
+

Initial value for x

+
+
::math::calculus::newtonRaphsonParameters maxiter tolerance
+

Set the numerical parameters for the Newton-Raphson method:

+
+
maxiter
+

Maximum number of iteration steps (defaults to 20)

+
tolerance
+

Relative precision (defaults to 0.001)

+
+
::math::calculus::regula_falsi f xb xe eps
+

Return an estimate of the zero or one of the zeros of the function +contained in the interval [xb,xe]. The error in this estimate is of the +order of eps*abs(xe-xb), the actual error may be slightly larger.

+

The method used is the so-called regula falsi or +false position method. It is a straightforward implementation. +The method is robust, but requires that the interval brackets a zero or +at least an uneven number of zeros, so that the value of the function at +the start has a different sign than the value at the end.

+

In contrast to Newton-Raphson there is no need for the computation of +the function's derivative.

+
+
command f
+

Name of the command that evaluates the function for +which the zero is to be returned

+
float xb
+

Start of the interval in which the zero is supposed +to lie

+
float xe
+

End of the interval

+
float eps
+

Relative allowed error (defaults to 1.0e-4)

+
+
+

Notes:

+

Several of the above procedures take the names of procedures as +arguments. To avoid problems with the visibility of these +procedures, the fully-qualified name of these procedures is determined +inside the calculus routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance:

+
+    namespace eval ::mySpace {
+       namespace export calcfunc
+       proc calcfunc { x } { return $x }
+    }
+    #
+    # Use a fully-qualified name
+    #
+    namespace eval ::myCalc {
+       proc detIntegral { begin end } {
+          return [integral $begin $end 100 ::mySpace::calcfunc]
+       }
+    }
+    #
+    # Import the name
+    #
+    namespace eval ::myCalc {
+       namespace import ::mySpace::calcfunc
+       proc detIntegral { begin end } {
+          return [integral $begin $end 100 calcfunc]
+       }
+    }
+
+

Enhancements for the second-order boundary value problem:

+
    +

  • Other types of boundary conditions (zero gradient, zero flux)

    • +

  • Other schematisation of the first-order term (now central +differences are used, but upstream differences might be useful too).

    • +
+
+

EXAMPLES

+

Let us take a few simple examples:

+

Integrate x over the interval [0,100] (20 steps):

+
+proc linear_func { x } { return $x }
+puts "Integral: [::math::calculus::integral 0 100 20 linear_func]"
+
+

For simple functions, the alternative could be:

+
+puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]"
+
+

Do not forget the braces!

+

The differential equation for a dampened oscillator:

+
+x'' + rx' + wx = 0
+
+

can be split into a system of first-order equations:

+
+x' = y
+y' = -ry - wx
+
+

Then this system can be solved with code like this:

+
+proc dampened_oscillator { t xvec } {
+   set x  [lindex $xvec 0]
+   set x1 [lindex $xvec 1]
+   return [list $x1 [expr {-$x1-$x}]]
+}
+set xvec   { 1.0 0.0 }
+set t      0.0
+set tstep  0.1
+for { set i 0 } { $i < 20 } { incr i } {
+   set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator]
+   puts "Result ($t): $result"
+   set t      [expr {$t+$tstep}]
+   set xvec   $result
+}
+
+

Suppose we have the boundary value problem:

+
+    Dy'' + ky = 0
+    x = 0: y = 1
+    x = L: y = 0
+
+

This boundary value problem could originate from the diffusion of a +decaying substance.

+

It can be solved with the following fragment:

+
+   proc coeffs { x } { return [list $::Diff 0.0 $::decay] }
+   proc force  { x } { return 0.0 }
+   set Diff   1.0e-2
+   set decay  0.0001
+   set length 100.0
+   set y [::math::calculus::boundaryValueSecondOrder \
+      coeffs force {0.0 1.0} [list $length 0.0] 100]
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

romberg

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/combinatorics.html Index: embedded/www/tcllib/files/modules/math/combinatorics.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/combinatorics.html @@ -0,0 +1,201 @@ + + +math::combinatorics - Tcl Math Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::combinatorics(n) 1.2.3 tcllib "Tcl Math Library"

+

Name

+

math::combinatorics - Combinatorial functions in the Tcl Math Library

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require math ?1.2.3?
    • +
+ +
+
+

Description

+

The math package contains implementations of several +functions useful in combinatorial problems.

+
+

COMMANDS

+
+
::math::ln_Gamma z
+

Returns the natural logarithm of the Gamma function for the argument +z.

+

The Gamma function is defined as the improper integral from zero to +positive infinity of

+
+  t**(x-1)*exp(-t) dt
+
+

The approximation used in the Tcl Math Library is from Lanczos, +ISIAM J. Numerical Analysis, series B, volume 1, p. 86. +For "x > 1", the absolute error of the result is claimed to be +smaller than 5.5*10**-10 -- that is, the resulting value of Gamma when

+
+  exp( ln_Gamma( x) ) 
+
+

is computed is expected to be precise to better than nine significant +figures.

+
::math::factorial x
+

Returns the factorial of the argument x.

+

For integer x, 0 <= x <= 12, an exact integer result is +returned.

+

For integer x, 13 <= x <= 21, an exact floating-point +result is returned on machines with IEEE floating point.

+

For integer x, 22 <= x <= 170, the result is exact to 1 +ULP.

+

For real x, x >= 0, the result is approximated by +computing Gamma(x+1) using the ::math::ln_Gamma +function, and the result is expected to be precise to better than nine +significant figures.

+

It is an error to present x <= -1 or x > 170, or a value +of x that is not numeric.

+
::math::choose n k
+

Returns the binomial coefficient C(n, k)

+
+   C(n,k) = n! / k! (n-k)!
+
+

If both parameters are integers and the result fits in 32 bits, the +result is rounded to an integer.

+

Integer results are exact up to at least n = 34. Floating point +results are precise to better than nine significant figures.

+
::math::Beta z w
+

Returns the Beta function of the parameters z and w.

+
+   Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w)
+
+

Results are returned as a floating point number precise to better than +nine significant digits provided that w and z are both at +least 1.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/constants.html Index: embedded/www/tcllib/files/modules/math/constants.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/constants.html @@ -0,0 +1,212 @@ + + +math::constants - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::constants(n) 1.0.1 tcllib "Tcl Math Library"

+

Name

+

math::constants - Mathematical and numerical constants

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.3?
    • +
  • package require math::constants ?1.0.1?
    • +
+ +
+
+

Description

+

This package defines some common mathematical and numerical constants. +By using the package you get consistent values for numbers like pi and +ln(10).

+

It defines two commands:

+
    +

  • One for importing the constants

    • +

  • One for reporting which constants are defined and what values they +actually have.

    • +
+

The motivation for this package is that quite often, with +(mathematical) computations, you need a good approximation to, say, +the ratio of degrees to radians. You can, of course, define this +like:

+
+    variable radtodeg [expr {180.0/(4.0*atan(1.0))}]
+
+

and use the variable radtodeg whenever you need the conversion.

+

This has two drawbacks:

+
    +

  • You need to remember the proper formula or value and that is +error-prone.

    • +

  • Especially with the use of mathematical functions like atan +you assume that they have been accurately implemented. This is seldom or +never the case and for each platform you can get subtle differences.

    • +
+

Here is the way you can do it with the math::constants package:

+
+    package require math::constants
+    ::math::constants::constants radtodeg degtorad
+
+

which creates two variables, radtodeg and (its reciprocal) degtorad +in the calling namespace.

+

Constants that have been defined (their values are mostly taken +from mathematical tables with more precision than usually can be +handled) include:

+
    +

  • basic constants like pi, e, gamma (Euler's constant)

    • +

  • derived values like ln(10) and sqrt(2)

    • +

  • purely numerical values such as 1/3 that are included for convenience +and for the fact that certain seemingly trivial computations like:

    +
    +    set value [expr {3.0*$onethird}]
+
    +

    give exactly the value you expect (if IEEE arithmetic is +available).

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::constants::constants args
+

Import the constants whose names are given as arguments

+
::math::constants::print-constants args
+

Print the constants whose names are given as arguments on the screen +(name, value and description) or, if no arguments are given, print all +defined constants. This is mainly a convenience procedure.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: constants of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/decimal.html Index: embedded/www/tcllib/files/modules/math/decimal.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/decimal.html @@ -0,0 +1,325 @@ + + +math::decimal - Tcl Decimal Arithmetic Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::decimal(n) 1.0.2 tcllib "Tcl Decimal Arithmetic Library"

+

Name

+

math::decimal - General decimal arithmetic

+
+ + +

Description

+

The decimal package provides decimal arithmetic support for both limited +precision floating point and arbitrary precision floating point. +Additionally, integer arithmetic is supported.

+

More information and the specifications on which this package depends can be +found on the general decimal arithmetic page at http://speleotrove.com/decimal +This package provides for:

+
    +

  • A new data type decimal which is represented as a list containing sign, +mantissa and exponent.

    • +

  • Arithmetic operations on those decimal numbers such as addition, subtraction, +multiplication, etc...

    • +
+

Numbers are converted to decimal format using the operation ::math::decimal::fromstr.

+

Numbers are converted back to string format using the operation +::math::decimal::tostr.

+
+

EXAMPLES

+

This section shows some simple examples. Since the purpose of this library +is to perform decimal math operations, examples may be the simplest way +to learn how to work with it and to see the difference between using this +package and sticking with expr. Consult the API section of +this man page for information about individual procedures.

+
+    package require decimal
+    # Various operations on two numbers.
+    # We first convert them to decimal format.
+    set a [::math::decimal::fromstr 8.2]
+    set b [::math::decimal::fromstr .2]
+    # Then we perform our operations. Here we multiply
+    set c [::math::decimal::* $a $b]
+    # Finally we convert back to string format for presentation to the user.
+    puts [::math::decimal::tostr $c] ; # => will output 8.4
+    # Other examples
+    #
+    # Subtraction
+    set c [::math::decimal::- $a $b]
+    puts [::math::decimal::tostr $c] ; # => will output 8.0
+    # Why bother using this instead of simply expr?
+    puts 8.399999999999999 ; # => will output 8.399999999999999
+    puts 7.999999999999999 ; # => will output 7.999999999999999
+    # See http://speleotrove.com/decimal to learn more about why this happens.
+
+
+

API

+
+
::math::decimal::fromstr string
+

Convert string into a decimal.

+
::math::decimal::tostr decimal
+

Convert decimal into a string representing the number in base 10.

+
::math::decimal::setVariable variable setting
+

Sets the variable to setting. Valid variables are:

+
    +

  • rounding - Method of rounding to use during rescale. Valid + methods are round_half_even, round_half_up, round_half_down, + round_down, round_up, round_floor, round_ceiling.

    • +

  • precision - Maximum number of digits allowed in mantissa.

    • +

  • extended - Set to 1 for extended mode. 0 for simplified mode.

    • +

  • maxExponent - Maximum value for the exponent. Defaults to 999.

    • +

  • minExponent - Minimum value for the exponent. Default to -998.

    • +
+
::math::decimal::add a b
+
+
::math::decimal::+ a b
+

Return the sum of the two decimals a and b.

+
::math::decimal::subtract a b
+
+
::math::decimal::- a b
+

Return the differnece of the two decimals a and b.

+
::math::decimal::multiply a b
+
+
::math::decimal::* a b
+

Return the product of the two decimals a and b.

+
::math::decimal::divide a b
+
+
::math::decimal::/ a b
+

Return the quotient of the division between the two +decimals a and b.

+
::math::decimal::divideint a b
+

Return a the integer portion of the quotient of the division between +decimals a and b

+
::math::decimal::remainder a b
+

Return the remainder of the division between the two +decimals a and b.

+
::math::decimal::abs decimal
+

Return the absolute value of the decimal.

+
::math::decimal::compare a b
+

Compare the two decimals a and b, returning 0 if a == b, +1 if a > b, and -1 if a < b.

+
::math::decimal::max a b
+

Compare the two decimals a and b, and return a if a >= b, and b if a < b.

+
::math::decimal::maxmag a b
+

Compare the two decimals a and b while ignoring their signs, and return a if abs(a) >= abs(b), and b if abs(a) < abs(b).

+
::math::decimal::min a b
+

Compare the two decimals a and b, and return a if a <= b, and b if a > b.

+
::math::decimal::minmag a b
+

Compare the two decimals a and b while ignoring their signs, and return a if abs(a) <= abs(b), and b if abs(a) > abs(b).

+
::math::decimal::plus a
+

Return the result from ::math::decimal::+ 0 $a.

+
::math::decimal::minus a
+

Return the result from ::math::decimal::- 0 $a.

+
::math::decimal::copynegate a
+

Returns a with the sign flipped.

+
::math::decimal::copysign a b
+

Returns a with the sign set to the sign of the b.

+
::math::decimal::is-signed decimal
+

Return the sign of the decimal. +The procedure returns 0 if the number is positive, 1 if it's negative.

+
::math::decimal::is-zero decimal
+

Return true if decimal value is zero, otherwise false is returned.

+
::math::decimal::is-NaN decimal
+

Return true if decimal value is NaN (not a number), otherwise false is returned.

+
::math::decimal::is-infinite decimal
+

Return true if decimal value is Infinite, otherwise false is returned.

+
::math::decimal::is-finite decimal
+

Return true if decimal value is finite, otherwise false is returned.

+
::math::decimal::fma a b c
+

Return the result from first multiplying a by b and then adding c. Rescaling only occurs after completion of all operations. In this way the result may vary from that returned by performing the operations individually.

+
::math::decimal::round_half_even decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round so the final digit is even.

+
::math::decimal::round_half_up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round up.

+
::math::decimal::round_half_down decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round down.

+
::math::decimal::round_down decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward 0. (Truncate)

+
::math::decimal::round_up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round away from 0

+
::math::decimal::round_floor decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward -Infinity.

+
::math::decimal::round_ceiling decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward Infinity

+
::math::decimal::round_05up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow +the result is the same as for round-down.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category Decimal of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/fourier.html Index: embedded/www/tcllib/files/modules/math/fourier.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/fourier.html @@ -0,0 +1,246 @@ + +math::fourier - Tcl Math Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::fourier(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::fourier - Discrete and fast fourier transforms

+
+ + +

Description

+

The math::fourier package implements two versions of discrete +Fourier transforms, the ordinary transform and the fast Fourier +transform. It also provides a few simple filter procedures as an +illustrations of how such filters can be implemented.

+

The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. We also refer to the original Wiki page on the subject +which describes some of the considerations behind the current +implementation.

+
+

GENERAL INFORMATION

+

The two top-level procedures defined are

+
    +

  • dft data-list

    • +

  • inverse_dft data-list

    • +
+

Both take a list of complex numbers and apply a Discrete Fourier +Transform (DFT) or its inverse respectively to these lists of numbers. +A "complex number" in this case is either (i) a pair (two element list) of +numbers, interpreted as the real and imaginary parts of the complex number, +or (ii) a single number, interpreted as the real part of a complex number +whose imaginary part is zero. The return value is always in the +first format. (The DFT generally produces complex results even if the +input is purely real.) Applying first one and then the other of these +procedures to a list of complex numbers will (modulo rounding errors +due to floating point arithmetic) return the original list of numbers.

+

If the input length N is a power of two then these procedures will +utilize the O(N log N) Fast Fourier Transform algorithm. If input +length is not a power of two then the DFT will instead be computed +using a the naive quadratic algorithm.

+

Some examples:

+
+    % dft {1 2 3 4}
+    {10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}
+    % inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}}
+    {1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0}
+    % dft {1 2 3 4 5}
+    {15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}
+    % inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}}
+    {1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17}
+
+

In the last case, the imaginary parts <1e-16 would have been zero in exact +arithmetic, but aren't here due to rounding errors.

+

Internally, the procedures use a flat list format where every even +index element of a list is a real part and every odd index element +is an imaginary part. This is reflected in the variable names by Re_ +and Im_ prefixes.

+

The package includes two simple filters. They have an analogue +equivalent in a simple electronic circuit, a resistor and a capacitance +in series. Using these filters requires the +math::complexnumbers package.

+
+

PROCEDURES

+

The public Fourier transform procedures are:

+
+
::math::fourier::dft in_data
+

Determine the Fourier transform of the given list of complex +numbers. The result is a list of complex numbers representing the +(complex) amplitudes of the Fourier components.

+
+
list in_data
+

List of data

+
+
::math::fourier::inverse_dft in_data
+

Determine the inverse Fourier transform of the given list of +complex numbers (interpreted as amplitudes). The result is a list of +complex numbers representing the original (complex) data

+
+
list in_data
+

List of data (amplitudes)

+
+
::math::fourier::lowpass cutoff in_data
+

Filter the (complex) amplitudes so that high-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance.

+
+
float cutoff
+

Cut-off frequency

+
list in_data
+

List of data (amplitudes)

+
+
::math::fourier::highpass cutoff in_data
+

Filter the (complex) amplitudes so that low-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance.

+
+
float cutoff
+

Cut-off frequency

+
list in_data
+

List of data (amplitudes)

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: fourier of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/fuzzy.html Index: embedded/www/tcllib/files/modules/math/fuzzy.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/fuzzy.html @@ -0,0 +1,247 @@ + +math::fuzzy - Tcl Math Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::fuzzy(n) 0.2 tcllib "Tcl Math Library"

+

Name

+

math::fuzzy - Fuzzy comparison of floating-point numbers

+
+ + +

Description

+

The package Fuzzy is meant to solve common problems with floating-point +numbers in a systematic way:

+
    +

  • Comparing two numbers that are "supposed" to be identical, like +1.0 and 2.1/(1.2+0.9) is not guaranteed to give the +intuitive result.

    • +

  • Rounding a number that is halfway two integer numbers can cause +strange errors, like int(100.0*2.8) != 28 but 27

    • +
+

The Fuzzy package is meant to help sorting out this type of problems +by defining "fuzzy" comparison procedures for floating-point numbers. +It does so by allowing for a small margin that is determined +automatically - the margin is three times the "epsilon" value, that is +three times the smallest number eps such that 1.0 and 1.0+$eps +canbe distinguished. In Tcl, which uses double precision floating-point +numbers, this is typically 1.1e-16.

+
+

PROCEDURES

+

Effectively the package provides the following procedures:

+
+
::math::fuzzy::teq value1 value2
+

Compares two floating-point numbers and returns 1 if their values +fall within a small range. Otherwise it returns 0.

+
::math::fuzzy::tne value1 value2
+

Returns the negation, that is, if the difference is larger than +the margin, it returns 1.

+
::math::fuzzy::tge value1 value2
+

Compares two floating-point numbers and returns 1 if their values +either fall within a small range or if the first number is larger +than the second. Otherwise it returns 0.

+
::math::fuzzy::tle value1 value2
+

Returns 1 if the two numbers are equal according to +[teq] or if the first is smaller than the second.

+
::math::fuzzy::tlt value1 value2
+

Returns the opposite of [tge].

+
::math::fuzzy::tgt value1 value2
+

Returns the opposite of [tle].

+
::math::fuzzy::tfloor value
+

Returns the integer number that is lower or equal +to the given floating-point number, within a well-defined +tolerance.

+
::math::fuzzy::tceil value
+

Returns the integer number that is greater or equal to the given +floating-point number, within a well-defined tolerance.

+
::math::fuzzy::tround value
+

Rounds the floating-point number off.

+
::math::fuzzy::troundn value ndigits
+

Rounds the floating-point number off to the +specified number of decimals (Pro memorie).

+
+

Usage:

+
+if { [teq $x $y] } { puts "x == y" }
+if { [tne $x $y] } { puts "x != y" }
+if { [tge $x $y] } { puts "x >= y" }
+if { [tgt $x $y] } { puts "x > y" }
+if { [tlt $x $y] } { puts "x < y" }
+if { [tle $x $y] } { puts "x <= y" }
+set fx      [tfloor $x]
+set fc      [tceil  $x]
+set rounded [tround $x]
+set roundn  [troundn $x $nodigits]
+
+
+

TEST CASES

+

The problems that can occur with floating-point numbers are illustrated +by the test cases in the file "fuzzy.test":

+
    +

  • Several test case use the ordinary comparisons, and they +fail invariably to produce understandable results

    • +

  • One test case uses [expr] without braces ({ and }). It too +fails.

    • +
+

The conclusion from this is that any expression should be surrounded by +braces, because otherwise very awkward things can happen if you need +accuracy. Furthermore, accuracy and understandable results are +enhanced by using these "tolerant" or fuzzy comparisons.

+

Note that besides the Tcl-only package, there is also a C-based version.

+
+

REFERENCES

+

Original implementation in Fortran by dr. H.D. Knoble (Penn State +University).

+

P. E. Hagerty, "More on Fuzzy Floor and Ceiling," +APL QUOTE QUAD 8(4):20-24, June 1978. Note that TFLOOR=FL5 took five +years of refereed evolution (publication).

+

L. M. Breed, "Definitions for Fuzzy Floor and Ceiling", +APL QUOTE QUAD 8(3):16-23, March 1978.

+

D. Knuth, Art of Computer Programming, +Vol. 1, Problem 1.2.4-5.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: fuzzy of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/interpolate.html Index: embedded/www/tcllib/files/modules/math/interpolate.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/interpolate.html @@ -0,0 +1,338 @@ + + +math::interpolate - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::interpolate(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::interpolate - Interpolation routines

+
+ + +

Description

+

This package implements several interpolation algorithms:

+
    +

  • Interpolation into a table (one or two independent variables), this is useful +for example, if the data are static, like with tables of statistical functions.

    • +

  • Linear interpolation into a given set of data (organised as (x,y) pairs).

    • +

  • Lagrange interpolation. This is mainly of theoretical interest, because there is +no guarantee about error bounds. One possible use: if you need a line or +a parabola through given points (it will calculate the values, but not return +the coefficients).

    +

    A variation is Neville's method which has better behaviour and error +bounds.

    • +

  • Spatial interpolation using a straightforward distance-weight method. This procedure +allows any number of spatial dimensions and any number of dependent variables.

    • +

  • Interpolation in one dimension using cubic splines.

    • +
+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

The interpolation package defines the following public procedures:

+
+
::math::interpolate::defineTable name colnames values
+

Define a table with one or two independent variables (the distinction is implicit in +the data). The procedure returns the name of the table - this name is used whenever you +want to interpolate the values. Note: this procedure is a convenient wrapper for the +struct::matrix procedure. Therefore you can access the data at any location in your program.

+
+
string name (in)
+

Name of the table to be created

+
list colnames (in)
+

List of column names

+
list values (in)
+

List of values (the number of elements should be a +multiple of the number of columns. See EXAMPLES for more information on the +interpretation of the data.

+

The values must be sorted with respect to the independent variable(s).

+
+
::math::interpolate::interp-1d-table name xval
+

Interpolate into the one-dimensional table "name" and return a list of values, one for +each dependent column.

+
+
string name (in)
+

Name of an existing table

+
float xval (in)
+

Value of the independent row variable

+
+
::math::interpolate::interp-table name xval yval
+

Interpolate into the two-dimensional table "name" and return the interpolated value.

+
+
string name (in)
+

Name of an existing table

+
float xval (in)
+

Value of the independent row variable

+
float yval (in)
+

Value of the independent column variable

+
+
::math::interpolate::interp-linear xyvalues xval
+

Interpolate linearly into the list of x,y pairs and return the interpolated value.

+
+
list xyvalues (in)
+

List of pairs of (x,y) values, sorted to increasing x. +They are used as the breakpoints of a piecewise linear function.

+
float xval (in)
+

Value of the independent variable for which the value of y +must be computed.

+
+
::math::interpolate::interp-lagrange xyvalues xval
+

Use the list of x,y pairs to construct the unique polynomial of lowest degree +that passes through all points and return the interpolated value.

+
+
list xyvalues (in)
+

List of pairs of (x,y) values

+
float xval (in)
+

Value of the independent variable for which the value of y +must be computed.

+
+
::math::interpolate::prepare-cubic-splines xcoord ycoord
+

Returns a list of coefficients for the second routine +interp-cubic-splines to actually interpolate.

+
+
list xcoord
+

List of x-coordinates for the value of the +function to be interpolated is known. The coordinates must be strictly +ascending. At least three points are required.

+
list ycoord
+

List of y-coordinates (the values of the +function at the given x-coordinates).

+
+
::math::interpolate::interp-cubic-splines coeffs x
+

Returns the interpolated value at coordinate x. The coefficients are +computed by the procedure prepare-cubic-splines.

+
+
list coeffs
+

List of coefficients as returned by +prepare-cubic-splines

+
float x
+

x-coordinate at which to estimate the function. Must +be between the first and last x-coordinate for which values were given.

+
+
::math::interpolate::interp-spatial xyvalues coord
+

Use a straightforward interpolation method with weights as function of the +inverse distance to interpolate in 2D and N-dimensional space

+

The list xyvalues is a list of lists:

+
+    {   {x1 y1 z1 {v11 v12 v13 v14}}
+	{x2 y2 z2 {v21 v22 v23 v24}}
+	...
+    }
+
+

The last element of each inner list is either a single number or a list in itself. +In the latter case the return value is a list with the same number of elements.

+

The method is influenced by the search radius and the power of the inverse distance

+
+
list xyvalues (in)
+

List of lists, each sublist being a list of coordinates and +of dependent values.

+
list coord (in)
+

List of coordinates for which the values must be calculated

+
+
::math::interpolate::interp-spatial-params max_search power
+

Set the parameters for spatial interpolation

+
+
float max_search (in)
+

Search radius (data points further than this are ignored)

+
integer power (in)
+

Power for the distance (either 1 or 2; defaults to 2)

+
+
::math::interpolate::neville xlist ylist x
+

Interpolates between the tabulated values of a function +whose abscissae are xlist +and whose ordinates are ylist to produce an estimate for the value +of the function at x. The result is a two-element list; the first +element is the function's estimated value, and the second is an estimate +of the absolute error of the result. Neville's algorithm for polynomial +interpolation is used. Note that a large table of values will use an +interpolating polynomial of high degree, which is likely to result in +numerical instabilities; one is better off using only a few tabulated +values near the desired abscissa.

+
+
+

EXAMPLES

+

TODO +Example of using the cubic splines:

+

Suppose the following values are given:

+
+    x       y
+  0.1     1.0
+  0.3     2.1
+  0.4     2.2
+  0.8     4.11
+  1.0     4.12
+
+

Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:

+
+   set coeffs [::math::interpolate::prepare-cubic-splines  {0.1 0.3 0.4 0.8  1.0}  {1.0 2.1 2.2 4.11 4.12}]
+   foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} {
+      puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]"
+   }
+
+

to get the following output:

+
+0.1: 1.0
+0.2: 1.68044117647
+0.3: 2.1
+0.4: 2.2
+0.5: 3.11221507353
+0.6: 4.25242647059
+0.7: 5.41804227941
+0.8: 4.11
+0.9: 3.95675857843
+1.0: 4.12
+
+

As you can see, the values at the abscissae are reproduced perfectly.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: interpolate of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/linalg.html Index: embedded/www/tcllib/files/modules/math/linalg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/linalg.html @@ -0,0 +1,993 @@ + + +math::linearalgebra - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::linearalgebra(n) 1.1 tcllib "Tcl Math Library"

+

Name

+

math::linearalgebra - Linear Algebra

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.4?
    • +
  • package require math::linearalgebra ?1.1?
    • +
+ +
+
+

Description

+

This package offers both low-level procedures and high-level algorithms +to deal with linear algebra problems:

+
    +

  • robust solution of linear equations or least squares problems

    • +

  • determining eigenvectors and eigenvalues of symmetric matrices

    • +

  • various decompositions of general matrices or matrices of a specific +form

    • +

  • (limited) support for matrices in band storage, a common type of sparse +matrices

    • +
+

It arose as a re-implementation of Hume's LA package and the desire to +offer low-level procedures as found in the well-known BLAS library. +Matrices are implemented as lists of lists rather linear lists with +reserved elements, as in the original LA package, as it was found that +such an implementation is actually faster.

+

It is advisable, however, to use the procedures that are offered, such +as setrow and getrow, rather than rely on this +representation explicitly: that way it is to switch to a possibly even +faster compiled implementation that supports the same API.

+

Note: When using this package in combination with Tk, there may +be a naming conflict, as both this package and Tk define a command +scale. See the NAMING CONFLICT section below.

+
+

PROCEDURES

+

The package defines the following public procedures (several exist as +specialised procedures, see below):

+

Constructing matrices and vectors

+
+
::math::linearalgebra::mkVector ndim value
+

Create a vector with ndim elements, each with the value value.

+
+
integer ndim
+

Dimension of the vector (number of components)

+
double value
+

Uniform value to be used (default: 0.0)

+
+
::math::linearalgebra::mkUnitVector ndim ndir
+

Create a unit vector in ndim-dimensional space, along the +ndir-th direction.

+
+
integer ndim
+

Dimension of the vector (number of components)

+
integer ndir
+

Direction (0, ..., ndim-1)

+
+
::math::linearalgebra::mkMatrix nrows ncols value
+

Create a matrix with nrows rows and ncols columns. All +elements have the value value.

+
+
integer nrows
+

Number of rows

+
integer ncols
+

Number of columns

+
double value
+

Uniform value to be used (default: 0.0)

+
+
::math::linearalgebra::getrow matrix row ?imin? ?imax?
+

Returns a single row of a matrix as a list

+
+
list matrix
+

Matrix in question

+
integer row
+

Index of the row to return

+
integer imin
+

Minimum index of the column (default: 0)

+
integer imax
+

Maximum index of the column (default: ncols-1)

+
+
::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?
+

Set a single row of a matrix to new values (this list must have the same +number of elements as the number of columns in the matrix)

+
+
list matrix
+

name of the matrix in question

+
integer row
+

Index of the row to update

+
list newvalues
+

List of new values for the row

+
integer imin
+

Minimum index of the column (default: 0)

+
integer imax
+

Maximum index of the column (default: ncols-1)

+
+
::math::linearalgebra::getcol matrix col ?imin? ?imax?
+

Returns a single column of a matrix as a list

+
+
list matrix
+

Matrix in question

+
integer col
+

Index of the column to return

+
integer imin
+

Minimum index of the row (default: 0)

+
integer imax
+

Maximum index of the row (default: nrows-1)

+
+
::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?
+

Set a single column of a matrix to new values (this list must have +the same number of elements as the number of rows in the matrix)

+
+
list matrix
+

name of the matrix in question

+
integer col
+

Index of the column to update

+
list newvalues
+

List of new values for the column

+
integer imin
+

Minimum index of the row (default: 0)

+
integer imax
+

Maximum index of the row (default: nrows-1)

+
+
::math::linearalgebra::getelem matrix row col
+

Returns a single element of a matrix/vector

+
+
list matrix
+

Matrix or vector in question

+
integer row
+

Row of the element

+
integer col
+

Column of the element (not present for vectors)

+
+
::math::linearalgebra::setelem matrix row ?col? newvalue
+

Set a single element of a matrix (or vector) to a new value

+
+
list matrix
+

name of the matrix in question

+
integer row
+

Row of the element

+
integer col
+

Column of the element (not present for vectors)

+
+
::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?
+

Swap two rows in a matrix completely or only a selected part

+
+
list matrix
+

name of the matrix in question

+
integer irow1
+

Index of first row

+
integer irow2
+

Index of second row

+
integer imin
+

Minimum column index (default: 0)

+
integer imin
+

Maximum column index (default: ncols-1)

+
+
::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?
+

Swap two columns in a matrix completely or only a selected part

+
+
list matrix
+

name of the matrix in question

+
integer irow1
+

Index of first column

+
integer irow2
+

Index of second column

+
integer imin
+

Minimum row index (default: 0)

+
integer imin
+

Maximum row index (default: nrows-1)

+
+
+

Querying matrices and vectors

+
+
::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?
+

Return a string representing the vector or matrix, for easy printing. +(There is currently no way to print fixed sets of columns)

+
+
list obj
+

Matrix or vector in question

+
string format
+

Format for printing the numbers (default: %6.4f)

+
string rowsep
+

String to use for separating rows (default: newline)

+
string colsep
+

String to use for separating columns (default: space)

+
+
::math::linearalgebra::dim obj
+

Returns the number of dimensions for the object (either 0 for a scalar, +1 for a vector and 2 for a matrix)

+
+
any obj
+

Scalar, vector, or matrix

+
+
::math::linearalgebra::shape obj
+

Returns the number of elements in each dimension for the object (either +an empty list for a scalar, a single number for a vector and a list of +the number of rows and columns for a matrix)

+
+
any obj
+

Scalar, vector, or matrix

+
+
::math::linearalgebra::conforming type obj1 obj2
+

Checks if two objects (vector or matrix) have conforming shapes, that is +if they can be applied in an operation like addition or matrix +multiplication.

+
+
string type
+

Type of check:

+
    +

  • "shape" - the two objects have the same shape (for all element-wise +operations)

    • +

  • "rows" - the two objects have the same number of rows (for use as A and +b in a system of linear equations Ax = b

    • +

  • "matmul" - the first object has the same number of columns as the number +of rows of the second object. Useful for matrix-matrix or matrix-vector +multiplication.

    • +
+
list obj1
+

First vector or matrix (left operand)

+
list obj2
+

Second vector or matrix (right operand)

+
+
::math::linearalgebra::symmetric matrix ?eps?
+

Checks if the given (square) matrix is symmetric. The argument eps +is the tolerance.

+
+
list matrix
+

Matrix to be inspected

+
float eps
+

Tolerance for determining approximate equality +(defaults to 1.0e-8)

+
+
+

Basic operations

+
+
::math::linearalgebra::norm vector type
+

Returns the norm of the given vector. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm.

+
+
list vector
+

Vector, list of coefficients

+
string type
+

Type of norm (default: 2, the Euclidean norm)

+
+
::math::linearalgebra::norm_one vector
+

Returns the L1 norm of the given vector, the sum of absolute values

+
+
list vector
+

Vector, list of coefficients

+
+
::math::linearalgebra::norm_two vector
+

Returns the L2 norm of the given vector, the ordinary Euclidean norm

+
+
list vector
+

Vector, list of coefficients

+
+
::math::linearalgebra::norm_max vector ?index?
+

Returns the Linf norm of the given vector, the maximum absolute +coefficient

+
+
list vector
+

Vector, list of coefficients

+
integer index
+

(optional) if non zero, returns a list made of the maximum +value and the index where that maximum was found. +if zero, returns the maximum value.

+
+
::math::linearalgebra::normMatrix matrix type
+

Returns the norm of the given matrix. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm.

+
+
list matrix
+

Matrix, list of row vectors

+
string type
+

Type of norm (default: 2, the Euclidean norm)

+
+
::math::linearalgebra::dotproduct vect1 vect2
+

Determine the inproduct or dot product of two vectors. These must have +the same shape (number of dimensions)

+
+
list vect1
+

First vector, list of coefficients

+
list vect2
+

Second vector, list of coefficients

+
+
::math::linearalgebra::unitLengthVector vector
+

Return a vector in the same direction with length 1.

+
+
list vector
+

Vector to be normalized

+
+
::math::linearalgebra::normalizeStat mv
+

Normalize the matrix or vector in a statistical sense: the mean of the +elements of the columns of the result is zero and the standard deviation +is 1.

+
+
list mv
+

Vector or matrix to be normalized in the above sense

+
+
::math::linearalgebra::axpy scale mv1 mv2
+

Return a vector or matrix that results from a "daxpy" operation, that +is: compute a*x+y (a a scalar and x and y both vectors or matrices of +the same shape) and return the result.

+

Specialised variants are: axpy_vect and axpy_mat (slightly faster, +but no check on the arguments)

+
+
double scale
+

The scale factor for the first vector/matrix (a)

+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::add mv1 mv2
+

Return a vector or matrix that is the sum of the two arguments (x+y)

+

Specialised variants are: add_vect and add_mat (slightly faster, +but no check on the arguments)

+
+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::sub mv1 mv2
+

Return a vector or matrix that is the difference of the two arguments +(x-y)

+

Specialised variants are: sub_vect and sub_mat (slightly faster, +but no check on the arguments)

+
+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::scale scale mv
+

Scale a vector or matrix and return the result, that is: compute a*x.

+

Specialised variants are: scale_vect and scale_mat (slightly faster, +but no check on the arguments)

+
+
double scale
+

The scale factor for the vector/matrix (a)

+
list mv
+

Vector or matrix (x)

+
+
::math::linearalgebra::rotate c s vect1 vect2
+

Apply a planar rotation to two vectors and return the result as a list +of two vectors: c*x-s*y and s*x+c*y. In algorithms you can often easily +determine the cosine and sine of the angle, so it is more efficient to +pass that information directly.

+
+
double c
+

The cosine of the angle

+
double s
+

The sine of the angle

+
list vect1
+

First vector (x)

+
list vect2
+

Seocnd vector (x)

+
+
::math::linearalgebra::transpose matrix
+

Transpose a matrix

+
+
list matrix
+

Matrix to be transposed

+
+
::math::linearalgebra::matmul mv1 mv2
+

Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector.

+
+
list mv1
+

First vector/matrix (x)

+
list mv2
+

Second vector/matrix (y)

+
+
::math::linearalgebra::angle vect1 vect2
+

Compute the angle between two vectors (in radians)

+
+
list vect1
+

First vector

+
list vect2
+

Second vector

+
+
::math::linearalgebra::crossproduct vect1 vect2
+

Compute the cross product of two (three-dimensional) vectors

+
+
list vect1
+

First vector

+
list vect2
+

Second vector

+
+
::math::linearalgebra::matmul mv1 mv2
+

Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector.

+
+
list mv1
+

First vector/matrix (x)

+
list mv2
+

Second vector/matrix (y)

+
+
+

Common matrices and test matrices

+
+
::math::linearalgebra::mkIdentity size
+

Create an identity matrix of dimension size.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkDiagonal diag
+

Create a diagonal matrix whose diagonal elements are the elements of the +vector diag.

+
+
list diag
+

Vector whose elements are used for the diagonal

+
+
::math::linearalgebra::mkRandom size
+

Create a square matrix whose elements are uniformly distributed random +numbers between 0 and 1 of dimension size.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkTriangular size ?uplo? ?value?
+

Create a triangular matrix with non-zero elements in the upper or lower +part, depending on argument uplo.

+
+
integer size
+

Dimension of the matrix

+
string uplo
+

Fill the upper (U) or lower part (L)

+
double value
+

Value to fill the matrix with

+
+
::math::linearalgebra::mkHilbert size
+

Create a Hilbert matrix of dimension size. +Hilbert matrices are very ill-conditioned with respect to +eigenvalue/eigenvector problems. Therefore they +are good candidates for testing the accuracy +of algorithms and implementations.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkDingdong size
+

Create a "dingdong" matrix of dimension size. +Dingdong matrices are imprecisely represented, +but have the property of being very stable in +such algorithms as Gauss elimination.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkOnes size
+

Create a square matrix of dimension size whose entries are all 1.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkMoler size
+

Create a Moler matrix of size size. (Moler matrices have +a very simple Choleski decomposition. It has one small eigenvalue +and it can easily upset elimination methods for systems of linear +equations.)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkFrank size
+

Create a Frank matrix of size size. (Frank matrices are +fairly well-behaved matrices)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkBorder size
+

Create a bordered matrix of size size. (Bordered matrices have +a very low rank and can upset certain specialised algorithms.)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkWilkinsonW+ size
+

Create a Wilkinson W+ of size size. This kind of matrix +has pairs of eigenvalues that are very close together. Usually +the order (size) is odd.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkWilkinsonW- size
+

Create a Wilkinson W- of size size. This kind of matrix +has pairs of eigenvalues with opposite signs, when the order (size) +is odd.

+
+
integer size
+

Dimension of the matrix

+
+
+

Common algorithms

+
+
::math::linearalgebra::solveGauss matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination. +Returns the solution (x) as a vector or matrix of the same shape as +bvect.

+
+
list matrix
+

Square matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solvePGauss matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination with +partial pivoting. Returns the solution (x) as a vector or matrix of the +same shape as bvect.

+
+
list matrix
+

Square matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solveTriangular matrix bvect ?uplo?
+

Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular.

+
+
list matrix
+

Lower or upper-triangular matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
string uplo
+

Indicates whether the matrix is lower-triangular +(L) or upper-triangular (U). Defaults to "U".

+
+
::math::linearalgebra::solveGaussBand matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination, +where the matrix is stored as a band matrix (cf. STORAGE). +Returns the solution (x) as a vector or matrix of the same shape as +bvect.

+
+
list matrix
+

Square matrix (matrix A; in band form)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solveTriangularBand matrix bvect
+

Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular and stored in band form.

+
+
list matrix
+

Upper-triangular matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::determineSVD A eps
+

Determines the Singular Value Decomposition of a matrix: A = U S Vtrans. +Returns a list with the matrix U, the vector of singular values S and +the matrix V.

+
+
list A
+

Matrix to be decomposed

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::eigenvectorsSVD A eps
+

Determines the eigenvectors and eigenvalues of a real +symmetric matrix, using SVD. Returns a list with the matrix of +normalized eigenvectors and their eigenvalues.

+
+
list A
+

Matrix whose eigenvalues must be determined

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::leastSquaresSVD A y qmin eps
+

Determines the solution to a least-sqaures problem Ax ~ y via singular +value decomposition. The result is the vector x.

+

Note that if you add a column of 1s to the matrix, then this column will +represent a constant like in: y = a*x1 + b*x2 + c. To force the +intercept to be zero, simply leave it out.

+
+
list A
+

Matrix of independent variables

+
list y
+

List of observed values

+
float qmin
+

Minimum singular value to be considered (defaults to 0.0)

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::choleski matrix
+

Determine the Choleski decomposition of a symmetric positive +semidefinite matrix (this condition is not checked!). The result +is the lower-triangular matrix L such that L Lt = matrix.

+
+
list matrix
+

Matrix to be decomposed

+
+
::math::linearalgebra::orthonormalizeColumns matrix
+

Use the modified Gram-Schmidt method to orthogonalize and normalize +the columns of the given matrix and return the result.

+
+
list matrix
+

Matrix whose columns must be orthonormalized

+
+
::math::linearalgebra::orthonormalizeRows matrix
+

Use the modified Gram-Schmidt method to orthogonalize and normalize +the rows of the given matrix and return the result.

+
+
list matrix
+

Matrix whose rows must be orthonormalized

+
+
::math::linearalgebra::dger matrix alpha x y ?scope?
+

Perform the rank 1 operation A + alpha*x*y' inline (that is: the matrix A is adjusted). +For convenience the new matrix is also returned as the result.

+
+
list matrix
+

Matrix whose rows must be adjusted

+
double alpha
+

Scale factor

+
list x
+

A column vector

+
list y
+

A column vector

+
list scope
+

If not provided, the operation is performed on all rows/columns of A +if provided, it is expected to be the list {imin imax jmin jmax} +where:

+
    +

  • imin Minimum row index

    • +

  • imax Maximum row index

    • +

  • jmin Minimum column index

    • +

  • jmax Maximum column index

    • +
+
+
::math::linearalgebra::dgetrf matrix
+

Computes an LU factorization of a general matrix, using partial, +pivoting with row interchanges. Returns the permutation vector.

+

The factorization has the form

+
+   P * A = L * U
+
+

where P is a permutation matrix, L is lower triangular with unit +diagonal elements, and U is upper triangular. +Returns the permutation vector, as a list of length n-1. +The last entry of the permutation is not stored, since it is +implicitely known, with value n (the last row is not swapped +with any other row). +At index #i of the permutation is stored the index of the row #j +which is swapped with row #i at step #i. That means that each +index of the permutation gives the permutation at each step, not the +cumulated permutation matrix, which is the product of permutations.

+
+
list matrix
+

On entry, the matrix to be factored. +On exit, the factors L and U from the factorization +P*A = L*U; the unit diagonal elements of L are not stored.

+
+
::math::linearalgebra::det matrix
+

Returns the determinant of the given matrix, based on PA=LU +decomposition, i.e. Gauss partial pivotal.

+
+
list matrix
+

Square matrix (matrix A)

+
list ipiv
+

The pivots (optionnal). +If the pivots are not provided, a PA=LU decomposition +is performed. +If the pivots are provided, we assume that it +contains the pivots and that the matrix A contains the +L and U factors, as provided by dgterf. +b-vectors

+
+
::math::linearalgebra::largesteigen matrix tolerance maxiter
+

Returns a list made of the largest eigenvalue (in magnitude) +and associated eigenvector. +Uses iterative Power Method as provided as algorithm #7.3.3 of Golub & Van Loan. +This algorithm is used here for a dense matrix (but is usually +used for sparse matrices).

+
+
list matrix
+

Square matrix (matrix A)

+
double tolerance
+

The relative tolerance of the eigenvalue (default:1.e-8).

+
integer maxiter
+

The maximum number of iterations (default:10).

+
+
+

Compability with the LA package +Two procedures are provided for compatibility with Hume's LA package:

+
+
::math::linearalgebra::to_LA mv
+

Transforms a vector or matrix into the format used by the original LA +package.

+
+
list mv
+

Matrix or vector

+
+
::math::linearalgebra::from_LA mv
+

Transforms a vector or matrix from the format used by the original LA +package into the format used by the present implementation.

+
+
list mv
+

Matrix or vector as used by the LA package

+
+
+
+

STORAGE

+

While most procedures assume that the matrices are given in full form, +the procedures solveGaussBand and solveTriangularBand +assume that the matrices are stored as band matrices. This +common type of "sparse" matrices is related to ordinary matrices as +follows:

+
    +

  • "A" is a full-size matrix with N rows and M columns.

    • +

  • "B" is a band matrix, with m upper and lower diagonals and n rows.

    • +

  • "B" can be stored in an ordinary matrix of (2m+1) columns (one for +each off-diagonal and the main diagonal) and n rows.

    • +

  • Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element +k,j of "A" where k = M+i-1 and M is at least (!) n, the number of rows +in "B".

    • +

  • To set element (i,j) of matrix "B" use:

    +
    +    setelem B $j [expr {$N+$i-1}] $value
+
    +
    • +
+

(There is no convenience procedure for this yet)

+
+

REMARKS ON THE IMPLEMENTATION

+

There is a difference between the original LA package by Hume and the +current implementation. Whereas the LA package uses a linear list, the +current package uses lists of lists to represent matrices. It turns out +that with this representation, the algorithms are faster and easier to +implement.

+

The LA package was used as a model and in fact the implementation of, +for instance, the SVD algorithm was taken from that package. The set of +procedures was expanded using ideas from the well-known BLAS library and +some algorithms were updated from the second edition of J.C. Nash's +book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that +inspired the LA package.

+

Two procedures are provided to make the transition between the two +implementations easier: to_LA and from_LA. They are +described above.

+
+

TODO

+

Odds and ends: the following algorithms have not been implemented yet:

+
    +

  • determineQR

    • +

  • certainlyPositive, diagonallyDominant

    • +
+
+

NAMING CONFLICT

+

If you load this package in a Tk-enabled shell like wish, then the +command

+
namespace import ::math::linearalgebra
+

results in an error +message about "scale". This is due to the fact that Tk defines all +its commands in the global namespace. The solution is to import +the linear algebra commands in a namespace that is not the global one:

+
+package require math::linearalgebra
+namespace eval compute {
+    namespace import ::math::linearalgebra::*
+    ... use the linear algebra version of scale ...
+}
+
+

To use Tk's scale command in that same namespace you can rename it:

+
+namespace eval compute {
+    rename ::scale scaleTk
+    scaleTk .scale ...
+}
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: linearalgebra of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/machineparameters.html Index: embedded/www/tcllib/files/modules/math/machineparameters.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/machineparameters.html @@ -0,0 +1,283 @@ + + +tclrep/machineparameters - tclrep + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tclrep/machineparameters(n) 1.0 tcllib "tclrep"

+

Name

+

tclrep/machineparameters - Compute double precision machine parameters.

+
+ + +

Description

+

The math::machineparameters package +is the Tcl equivalent of the DLAMCH LAPACK function. +In floating point systems, a floating point number is represented +by

+
+x = +/- d1 d2 ... dt basis^e
+
+

where digits satisfy

+
+0 <= di <= basis - 1, i = 1, t
+
+

with the convention :

+
    +

  • t is the size of the mantissa

    • +

  • basis is the basis (the "radix")

    • +
+

The compute method computes all machine parameters. + Then, the get method can be used to get each + parameter. + The print method prints a report on standard output.

+
+

EXAMPLE

+

In the following example, one compute the parameters of a desktop +under Linux with the following Tcl 8.4.19 properties :

+
+% parray tcl_platform
+tcl_platform(byteOrder) = littleEndian
+tcl_platform(machine)   = i686
+tcl_platform(os)        = Linux
+tcl_platform(osVersion) = 2.6.24-19-generic
+tcl_platform(platform)  = unix
+tcl_platform(tip,268)   = 1
+tcl_platform(tip,280)   = 1
+tcl_platform(user)      = <username>
+tcl_platform(wordSize)  = 4
+
+

The following example creates a machineparameters object, + computes the properties and displays it.

+
+     set pp [machineparameters create %AUTO%]
+     $pp compute
+     $pp print
+     $pp destroy
+
+

This prints out :

+
+     Machine parameters
+     Epsilon : 1.11022302463e-16
+     Beta : 2
+     Rounding : proper
+     Mantissa : 53
+     Maximum exponent : 1024
+     Minimum exponent : -1021
+     Overflow threshold : 8.98846567431e+307
+     Underflow threshold : 2.22507385851e-308
+
+

That compares well with the results produced by Lapack 3.1.1 :

+
+     Epsilon                      =   1.11022302462515654E-016
+     Safe minimum                 =   2.22507385850720138E-308
+     Base                         =    2.0000000000000000
+     Precision                    =   2.22044604925031308E-016
+     Number of digits in mantissa =    53.000000000000000
+     Rounding mode                =   1.00000000000000000
+     Minimum exponent             =   -1021.0000000000000
+     Underflow threshold          =   2.22507385850720138E-308
+     Largest exponent             =    1024.0000000000000
+     Overflow threshold           =   1.79769313486231571E+308
+     Reciprocal of safe minimum   =   4.49423283715578977E+307
+
+

The following example creates a machineparameters object, + computes the properties and gets the epsilon for + the machine.

+
+     set pp [machineparameters create %AUTO%]
+     $pp compute
+     set eps [$pp get -epsilon]
+     $pp destroy
+
+
+

REFERENCES

+
    +

  • "Algorithms to Reveal Properties of Floating-Point Arithmetic", Michael A. Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue 11 (November 1972), Pages: 949 - 951

    • +

  • "More on Algorithms that Reveal Properties of Floating, Point Arithmetic Units", W. Morven Gentleman, University of Waterloo, Scott B. Marovich, Purdue University, Communications of the ACM, Volume 17 , Issue 5 (May 1974), Pages: 276 - 277

    • +
+
+

CLASS API

+
+
machineparameters create objectname ?options...?
+

The command creates a new machineparameters object and returns the fully +qualified name of the object command as its result.

+
+
-verbose verbose
+

Set this option to 1 to enable verbose logging. +This option is mainly for debug purposes. +The default value of verbose is 0.

+
+
+
+

OBJECT API

+
+
objectname configure ?options...?
+

The command configure the options of the object objectname. The options +are the same as the static method create.

+
objectname cget opt
+

Returns the value of the option which name is opt. The options +are the same as the method create and configure.

+
objectname destroy
+

Destroys the object objectname.

+
objectname compute
+

Computes the machine parameters.

+
objectname get key
+

Returns the value corresponding with given key. +The following is the list of available keys.

+
    +

  • -epsilon : smallest value so that 1+epsilon>1 is false

    • +

  • -rounding : The rounding mode used on the machine. +The rounding occurs when more than t digits would be required to +represent the number. +Two modes can be determined with the current system : +"chop" means than only t digits are kept, no matter the value of the number +"proper" means that another rounding mode is used, be it "round to nearest", +"round up", "round down".

    • +

  • -basis : the basis of the floating-point representation. +The basis is usually 2, i.e. binary representation (for example IEEE 754 machines), +but some machines (like HP calculators for example) uses 10, or 16, etc...

    • +

  • -mantissa : the number of bits in the mantissa

    • +

  • -exponentmax : the largest positive exponent before overflow occurs

    • +

  • -exponentmin : the largest negative exponent before (gradual) underflow occurs

    • +

  • -vmax : largest positive value before overflow occurs

    • +

  • -vmin : largest negative value before (gradual) underflow occurs

    • +
+
objectname tostring
+

Return a report for machine parameters.

+
objectname print
+

Print machine parameters on standard output.

+
+
+ +
ADDED embedded/www/tcllib/files/modules/math/math.html Index: embedded/www/tcllib/files/modules/math/math.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/math.html @@ -0,0 +1,222 @@ + +math - Tcl Math Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math(n) 1.2.5 tcllib "Tcl Math Library"

+

Name

+

math - Tcl Math Library

+
+ + +

Description

+

The math package provides utility math functions.

+

Besides a set of basic commands, available via the package math, +there are more specialised packages:

+ +
+

BASIC COMMANDS

+
+
::math::cov value value ?value ...?
+

Return the coefficient of variation expressed as percent of two or +more numeric values.

+
::math::integrate list of xy value pairs
+

Return the area under a "curve" defined by a set of x,y pairs and the +error bound as a list.

+
::math::fibonacci n
+

Return the n'th Fibonacci number.

+
::math::max value ?value ...?
+

Return the maximum of one or more numeric values.

+
::math::mean value ?value ...?
+

Return the mean, or "average" of one or more numeric values.

+
::math::min value ?value ...?
+

Return the minimum of one or more numeric values.

+
::math::product value ?value ...?
+

Return the product of one or more numeric values.

+
::math::random ?value1? ?value2?
+

Return a random number. If no arguments are given, the number is a +floating point value between 0 and 1. If one argument is given, the +number is an integer value between 0 and value1. If two +arguments are given, the number is an integer value between +value1 and value2.

+
::math::sigma value value ?value ...?
+

Return the population standard deviation of two or more numeric +values.

+
::math::stats value value ?value ...?
+

Return the mean, standard deviation, and coefficient of variation (as +percent) as a list.

+
::math::sum value ?value ...?
+

Return the sum of one or more numeric values.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/math_geometry.html Index: embedded/www/tcllib/files/modules/math/math_geometry.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/math_geometry.html @@ -0,0 +1,488 @@ + + +math::geometry - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::geometry(n) 1.1.2 tcllib "Tcl Math Library"

+

Name

+

math::geometry - Geometrical computations

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.3?
    • +
  • package require math::geometry ?1.1.2?
    • +
+ +
+
+

Description

+

The math::geometry package is a collection of functions for +computations and manipulations on two-dimensional geometrical objects, +such as points, lines and polygons.

+

The geometrical objects are implemented as plain lists of coordinates. +For instance a line is defined by a list of four numbers, the x- and +y-coordinate of a first point and the x- and y-coordinates of a second +point on the line.

+

The various types of object are recognised by the number of coordinate +pairs and the context in which they are used: a list of four elements +can be regarded as an infinite line, a finite line segment but also +as a polyline of one segment and a point set of two points.

+

Currently the following types of objects are distinguished:

+
    +

  • point - a list of two coordinates representing the x- and +y-coordinates respectively.

    • +

  • line - a list of four coordinates, interpreted as the x- and +y-coordinates of two distinct points on the line.

    • +

  • line segment - a list of four coordinates, interpreted as the +x- and y-coordinates of the first and the last points on the line +segment.

    • +

  • polyline - a list of an even number of coordinates, +interpreted as the x- and y-coordinates of an ordered set of points.

    • +

  • polygon - like a polyline, but the implicit assumption is that +the polyline is closed (if the first and last points do not coincide, +the missing segment is automatically added).

    • +

  • point set - again a list of an even number of coordinates, but +the points are regarded without any ordering.

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::geometry::+ point1 point2
+

Compute the sum of the two vectors given as points and return it. +The result is a vector as well.

+
::math::geometry::- point1 point2
+

Compute the difference (point1 - point2) of the two vectors +given as points and return it. The result is a vector as well.

+
::math::geometry::p x y
+

Construct a point from its coordinates and return it as the +result of the command.

+
::math::geometry::distance point1 point2
+

Compute the distance between the two points and return it as the +result of the command. This is in essence the same as

+
+    math::geometry::length [math::geomtry::- point1 point2]
+
+
+
::math::geometry::length point
+

Compute the length of the vector and return it as the +result of the command.

+
::math::geometry::s* factor point
+

Scale the vector by the factor and return it as the +result of the command. This is a vector as well.

+
::math::geometry::direction angle
+

Given the angle in degrees this command computes and returns +the unit vector pointing into this direction. The vector for +angle == 0 points to the right (up), and for angle == 90 up (north).

+
::math::geometry::h length
+

Returns a horizontal vector on the X-axis of the specified length. +Positive lengths point to the right (east).

+
::math::geometry::v length
+

Returns a vertical vector on the Y-axis of the specified length. +Positive lengths point down (south).

+
::math::geometry::between point1 point2 s
+

Compute the point which is at relative distance s between the two +points and return it as the result of the command. A relative distance of +0 returns point1, the distance 1 returns point2. +Distances < 0 or > 1 extrapolate along the line between the two point.

+
::math::geometry::octant point
+

Compute the octant of the circle the point is in and return it as the result +of the command. The possible results are

+
    +

  1. east

    2. +

  2. northeast

    3. +

  3. north

    4. +

  4. northwest

    5. +

  5. west

    6. +

  6. southwest

    7. +

  7. south

    8. +

  8. southeast

    9. +
+

Each octant is the arc of the circle +/- 22.5 degrees from the cardinal direction +the octant is named for.

+
::math::geometry::rect nw se
+

Construct a rectangle from its northwest and southeast corners and return +it as the result of the command.

+
::math::geometry::nwse rect
+

Extract the northwest and southeast corners of the rectangle and return +them as the result of the command (a 2-element list containing the +points, in the named order).

+
::math::geometry::angle line
+

Calculate the angle from the positive x-axis to a given line +(in two dimensions only).

+
+
list line
+

Coordinates of the line

+
+
::math::geometry::calculateDistanceToLine P line
+

Calculate the distance of point P to the (infinite) line and return the +result

+
+
list P
+

List of two numbers, the coordinates of the point

+
list line
+

List of four numbers, the coordinates of two points +on the line

+
+
::math::geometry::calculateDistanceToLineSegment P linesegment
+

Calculate the distance of point P to the (finite) line segment and +return the result.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list linesegment
+

List of four numbers, the coordinates of the +first and last points of the line segment

+
+
::math::geometry::calculateDistanceToPolyline P polyline
+

Calculate the distance of point P to the polyline and +return the result.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list polyline
+

List of numbers, the coordinates of the +vertices of the polyline

+
+
::math::geometry::findClosestPointOnLine P line
+

Return the point on a line which is closest to a given point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list line
+

List of four numbers, the coordinates of two points +on the line

+
+
::math::geometry::findClosestPointOnLineSegment P linesegment
+

Return the point on a line segment which is closest to a given +point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list linesegment
+

List of four numbers, the first and last +points on the line segment

+
+
::math::geometry::findClosestPointOnPolyline P polyline
+

Return the point on a polyline which is closest to a given +point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list polyline
+

List of numbers, the vertices of the polyline

+
+
::math::geometry::lengthOfPolyline polyline
+

Return the length of the polyline (note: it not regarded as a +polygon)

+
+
list polyline
+

List of numbers, the vertices of the polyline

+
+
::math::geometry::movePointInDirection P direction dist
+

Move a point over a given distance in a given direction and return the +new coordinates (in two dimensions only).

+
+
list P
+

Coordinates of the point to be moved

+
double direction
+

Direction (in degrees; 0 is to the right, 90 +upwards)

+
list dist
+

Distance over which to move the point

+
+
::math::geometry::lineSegmentsIntersect linesegment1 linesegment2
+

Check if two line segments intersect or coincide. Returns 1 if that is +the case, 0 otherwise (in two dimensions only).

+
+
list linesegment1
+

First line segment

+
list linesegment2
+

Second line segment

+
+
::math::geometry::findLineSegmentIntersection linesegment1 linesegment2
+

Find the intersection point of two line segments. Return the coordinates +or the keywords "coincident" or "none" if the line segments coincide or +have no points in common (in two dimensions only).

+
+
list linesegment1
+

First line segment

+
list linesegment2
+

Second line segment

+
+
::math::geometry::findLineIntersection line1 line2
+

Find the intersection point of two (infinite) lines. Return the coordinates +or the keywords "coincident" or "none" if the lines coincide or +have no points in common (in two dimensions only).

+
+
list line1
+

First line

+
list line2
+

Second line

+
+

See section References for details on the algorithm and math behind it.

+
::math::geometry::polylinesIntersect polyline1 polyline2
+

Check if two polylines intersect or not (in two dimensions only).

+
+
list polyline1
+

First polyline

+
list polyline2
+

Second polyline

+
+
::math::geometry::polylinesBoundingIntersect polyline1 polyline2 granularity
+

Check whether two polylines intersect, but reduce +the correctness of the result to the given granularity. +Use this for faster, but weaker, intersection checking.

+

How it works:

+

Each polyline is split into a number of smaller polylines, +consisting of granularity points each. If a pair of those smaller +lines' bounding boxes intersect, then this procedure returns 1, +otherwise it returns 0.

+
+
list polyline1
+

First polyline

+
list polyline2
+

Second polyline

+
int granularity
+

Number of points in each part (<=1 means check +every edge)

+
+
::math::geometry::intervalsOverlap y1 y2 y3 y4 strict
+

Check if two intervals overlap.

+
+
double y1,y2
+

Begin and end of first interval

+
double y3,y4
+

Begin and end of second interval

+
logical strict
+

Check for strict or non-strict overlap

+
+
::math::geometry::rectanglesOverlap P1 P2 Q1 Q2 strict
+

Check if two rectangles overlap.

+
+
list P1
+

upper-left corner of the first rectangle

+
list P2
+

lower-right corner of the first rectangle

+
list Q1
+

upper-left corner of the second rectangle

+
list Q2
+

lower-right corner of the second rectangle

+
list strict
+

choosing strict or non-strict interpretation

+
+
::math::geometry::bbox polyline
+

Calculate the bounding box of a polyline. Returns a list of four +coordinates: the upper-left and the lower-right corner of the box.

+
+
list polyline
+

The polyline to be examined

+
+
::math::geometry::pointInsidePolygon P polyline
+

Determine if a point is completely inside a polygon. If the point +touches the polygon, then the point is not completely inside the +polygon.

+
+
list P
+

Coordinates of the point

+
list polyline
+

The polyline to be examined

+
+
::math::geometry::rectangleInsidePolygon P1 P2 polyline
+

Determine if a rectangle is completely inside a polygon. If polygon +touches the rectangle, then the rectangle is not complete inside the +polygon.

+
+
list P1
+

Upper-left corner of the rectangle

+
list P2
+

Lower-right corner of the rectangle

+
list polygon
+

The polygon in question

+
+
::math::geometry::areaPolygon polygon
+

Calculate the area of a polygon.

+
+
list polygon
+

The polygon in question

+
+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: geometry of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/numtheory.html Index: embedded/www/tcllib/files/modules/math/numtheory.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/numtheory.html @@ -0,0 +1,175 @@ + +math::numtheory - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::numtheory(n) 1.0 tcllib "Tcl Math Library"

+

Name

+

math::numtheory - Number Theory

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.5?
    • +
  • package require math::numtheory ?1.0?
    • +
+ +
+
+

Description

+

This package is for collecting various number-theoretic operations, +though at the moment it only provides that of testing whether an +integer is a prime.

+
+
math::numtheory::isprime N ?option value ...?
+

The isprime command tests whether the integer N is a + prime, returning a boolean true value for prime N and a + boolean false value for non-prime N. The formal definition of + 'prime' used is the conventional, that the number being tested is + greater than 1 and only has trivial divisors.

+

To be precise, the return value is one of 0 (if N is + definitely not a prime), 1 (if N is definitely a + prime), and on (if N is probably prime); the latter + two are both boolean true values. The case that an integer may be + classified as "probably prime" arises because the Miller-Rabin + algorithm used in the test implementation is basically probabilistic, + and may if we are unlucky fail to detect that a number is in fact + composite. Options may be used to select the risk of such + "false positives" in the test. 1 is returned for "small" + N (which currently means N < 118670087467), where it is + known that no false positives are possible.

+

The only option currently defined is:

+
+ +
-randommr repetitions
+

which controls how many times the Miller-Rabin test should be + repeated with randomly chosen bases. Each repetition reduces the + probability of a false positive by a factor at least 4. The + default for repetitions is 4.

+
+

Unknown options are silently ignored.

+
+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/optimize.html Index: embedded/www/tcllib/files/modules/math/optimize.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/optimize.html @@ -0,0 +1,392 @@ + + +math::optimize - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::optimize(n) 1.0 tcllib "Tcl Math Library"

+

Name

+

math::optimize - Optimisation routines

+
+ + +

Description

+

This package implements several optimisation algorithms:

+
    +

  • Minimize or maximize a function over a given interval

    • +

  • Solve a linear program (maximize a linear function subject to linear +constraints)

    • +

  • Minimize a function of several variables given an initial guess for the +location of the minimum.

    • +
+

The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, the +algorithms have been used in a straightforward manner.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::math::optimize::minimum begin end func maxerr
+

Minimize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the minimum. No guarantee is made that the global +minimum is found.

+

The procedure returns the "x" value for which the function is minimal.

+

This procedure has been deprecated - use min_bound_1d instead

+

begin - Start of the interval

+

end - End of the interval

+

func - Name of the function to be minimized (a procedure taking +one argument).

+

maxerr - Maximum relative error (defaults to 1.0e-4)

+
::math::optimize::maximum begin end func maxerr
+

Maximize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the maximum. No guarantee is made that the global +maximum is found.

+

The procedure returns the "x" value for which the function is maximal.

+

This procedure has been deprecated - use max_bound_1d instead

+

begin - Start of the interval

+

end - End of the interval

+

func - Name of the function to be maximized (a procedure taking +one argument).

+

maxerr - Maximum relative error (defaults to 1.0e-4)

+
::math::optimize::min_bound_1d func begin end ?-relerror reltol? ?-abserror abstol? ?-maxiter maxiter? ?-trace traceflag?
+

Miminizes a function of one variable in the given interval. The procedure +uses Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a global minimum is found. The function to evaluate, func, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument.

+

x1 and x2 are the two bounds of +the interval in which the minimum is to be found. They need not be in +increasing order.

+

reltol, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. abstol, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of abstol to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale.

+

maxiter may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than maxiter times, it returns an error to the caller.

+

traceFlag is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace).

+
::math::optimize::min_unbound_1d func begin end ?-relerror reltol? ?-abserror abstol? ?-maxiter maxiter? ?-trace traceflag?
+

Miminizes a function of one variable over the entire real number line. +The procedure uses parabolic extrapolation combined with golden-section +dilatation to search for a region where a minimum exists, followed by +Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a global minimum is found. The function to evaluate, func, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument.

+

x1 and x2 are two initial guesses at where the minimum +may lie. x1 is the starting point for the minimization, and +the difference between x2 and x1 is used as a hint at the +characteristic length scale of the problem.

+

reltol, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. abstol, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of abstol to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale.

+

maxiter may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than maxiter times, it returns an error to the caller.

+

traceFlag is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace).

+
::math::optimize::solveLinearProgram objective constraints
+

Solve a linear program in standard form using a straightforward +implementation of the Simplex algorithm. (In the explanation below: The +linear program has N constraints and M variables).

+

The procedure returns a list of M values, the values for which the +objective function is maximal or a single keyword if the linear program +is not feasible or unbounded (either "unfeasible" or "unbounded")

+

objective - The M coefficients of the objective function

+

constraints - Matrix of coefficients plus maximum values that +implement the linear constraints. It is expected to be a list of N lists +of M+1 numbers each, M coefficients and the maximum value.

+
::math::optimize::linearProgramMaximum objective result
+

Convenience function to return the maximum for the solution found by the +solveLinearProgram procedure.

+

objective - The M coefficients of the objective function

+

result - The result as returned by solveLinearProgram

+
::math::optimize::nelderMead objective xVector ?-scale xScaleVector? ?-ftol epsilon? ?-maxiter count? ??-trace? flag?
+

Minimizes, in unconstrained fashion, a function of several variable over all +of space. The function to evaluate, objective, must be a single Tcl +command. To it will be appended as many elements as appear in the initial guess at +the location of the minimum, passed in as a Tcl list, xVector.

+

xScaleVector is an initial guess at the problem scale; the first +function evaluations will be made by varying the co-ordinates in xVector +by the amounts in xScaleVector. If xScaleVector is not supplied, +the co-ordinates will be varied by a factor of 1.0001 (if the co-ordinate +is non-zero) or by a constant 0.0001 (if the co-ordinate is zero).

+

epsilon is the desired relative error in the value of the function +evaluated at the minimum. The default is 1.0e-7, which usually gives three +significant digits of accuracy in the values of the x's.

+

pp +count is a limit on the number of trips through the main loop of +the optimizer. The number of function evaluations may be several times +this number. If the optimizer fails to find a minimum to within ftol +in maxiter iterations, it returns its current best guess and an +error status. Default is to allow 500 iterations.

+

flag is a flag that, if true, causes a line to be written to the +standard output for each evaluation of the objective function, giving +the arguments presented to the function and the value returned. Default is +false.

+

The nelderMead procedure returns a list of alternating keywords and +values suitable for use with array set. The meaning of the keywords is:

+

x is the approximate location of the minimum.

+

y is the value of the function at x.

+

yvec is a vector of the best N+1 function values achieved, where +N is the dimension of x

+

vertices is a list of vectors giving the function arguments +corresponding to the values in yvec.

+

nIter is the number of iterations required to achieve convergence or +fail.

+

status is 'ok' if the operation succeeded, or 'too-many-iterations' +if the maximum iteration count was exceeded.

+

nelderMead minimizes the given function using the downhill +simplex method of Nelder and Mead. This method is quite slow - much +faster methods for minimization are known - but has the advantage of being +extremely robust in the face of problems where the minimum lies in +a valley of complex topology.

+

nelderMead can occasionally find itself "stuck" at a point where +it can make no further progress; it is recommended that the caller +run it at least a second time, passing as the initial guess the +result found by the previous call. The second run is usually very +fast.

+

nelderMead can be used in some cases for constrained optimization. +To do this, add a large value to the objective function if the parameters +are outside the feasible region. To work effectively in this mode, +nelderMead requires that the initial guess be feasible and +usually requires that the feasible region be convex.

+
+
+

NOTES

+

Several of the above procedures take the names of procedures as +arguments. To avoid problems with the visibility of these +procedures, the fully-qualified name of these procedures is determined +inside the optimize routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance:

+
+    namespace eval ::mySpace {
+       namespace export calcfunc
+       proc calcfunc { x } { return $x }
+    }
+    #
+    # Use a fully-qualified name
+    #
+    namespace eval ::myCalc {
+       puts [min_bound_1d ::myCalc::calcfunc $begin $end]
+    }
+    #
+    # Import the name
+    #
+    namespace eval ::myCalc {
+       namespace import ::mySpace::calcfunc
+       puts [min_bound_1d calcfunc $begin $end]
+    }
+
+

The simple procedures minimum and maximum have been +deprecated: the alternatives are much more flexible, robust and +require less function evaluations.

+
+

EXAMPLES

+

Let us take a few simple examples:

+

Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10):

+
+proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} }
+puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]"
+
+

The maximum allowed error determines the number of steps taken (with +each step in the iteration the interval is reduced with a factor 1/2). +Hence, a maximum error of 0.0001 is achieved in approximately 14 steps.

+

An example of a linear program is:

+

Optimise the expression 3x+2y, where:

+
+   x >= 0 and y >= 0 (implicit constraints, part of the
+                     definition of linear programs)
+   x + y   <= 1      (constraints specific to the problem)
+   2x + 5y <= 10
+
+

This problem can be solved as follows:

+
+   set solution [::math::optimize::solveLinearProgram  { 3.0   2.0 }  { { 1.0   1.0   1.0 }
+        { 2.0   5.0  10.0 } } ]
+
+

Note, that a constraint like:

+
+   x + y >= 1
+
+

can be turned into standard form using:

+
+   -x  -y <= -1
+
+

The theory of linear programming is the subject of many a text book and +the Simplex algorithm that is implemented here is the best-known +method to solve this type of problems, but it is not the only one.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: optimize of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/polynomials.html Index: embedded/www/tcllib/files/modules/math/polynomials.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/polynomials.html @@ -0,0 +1,300 @@ + + +math::polynomials - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::polynomials(n) 1.0.1 tcllib "Tcl Math Library"

+

Name

+

math::polynomials - Polynomial functions

+
+ + +

Description

+

This package deals with polynomial functions of one variable:

+
    +

  • the basic arithmetic operations are extended to polynomials

    • +

  • computing the derivatives and primitives of these functions

    • +

  • evaluation through a general procedure or via specific procedures)

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::polynomials::polynomial coeffs
+

Return an (encoded) list that defines the polynomial. A polynomial

+
+   f(x) = a + b.x + c.x**2 + d.x**3
+
+

can be defined via:

+
+   set f [::math::polynomials::polynomial [list $a $b $c $d]
+
+
+
list coeffs
+

Coefficients of the polynomial (in ascending +order)

+
+
::math::polynomials::polynCmd coeffs
+

Create a new procedure that evaluates the polynomial. The name of the +polynomial is automatically generated. Useful if you need to evualuate +the polynomial many times, as the procedure consists of a single +[expr] command.

+
+
list coeffs
+

Coefficients of the polynomial (in ascending +order) or the polynomial definition returned by the polynomial +command.

+
+
::math::polynomials::evalPolyn polynomial x
+

Evaluate the polynomial at x.

+
+
list polynomial
+

The polynomial's definition (as returned by +the polynomial command). +order)

+
float x
+

The coordinate at which to evaluate the polynomial

+
+
::math::polynomials::addPolyn polyn1 polyn2
+

Return a new polynomial which is the sum of the two others.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::subPolyn polyn1 polyn2
+

Return a new polynomial which is the difference of the two others.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::multPolyn polyn1 polyn2
+

Return a new polynomial which is the product of the two others. If one +of the arguments is a scalar value, the other polynomial is simply +scaled.

+
+
list polyn1
+

The first polynomial operand or a scalar

+
list polyn2
+

The second polynomial operand or a scalar

+
+
::math::polynomials::divPolyn polyn1 polyn2
+

Divide the first polynomial by the second polynomial and return the +result. The remainder is dropped

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::remainderPolyn polyn1 polyn2
+

Divide the first polynomial by the second polynomial and return the +remainder.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::derivPolyn polyn
+

Differentiate the polynomial and return the result.

+
+
list polyn
+

The polynomial to be differentiated

+
+
::math::polynomials::primitivePolyn polyn
+

Integrate the polynomial and return the result. The integration +constant is set to zero.

+
+
list polyn
+

The polynomial to be integrated

+
+
::math::polynomials::degreePolyn polyn
+

Return the degree of the polynomial.

+
+
list polyn
+

The polynomial to be examined

+
+
::math::polynomials::coeffPolyn polyn index
+

Return the coefficient of the term of the index'th degree of the +polynomial.

+
+
list polyn
+

The polynomial to be examined

+
int index
+

The degree of the term

+
+
::math::polynomials::allCoeffsPolyn polyn
+

Return the coefficients of the polynomial (in ascending order).

+
+
list polyn
+

The polynomial in question

+
+
+
+

REMARKS ON THE IMPLEMENTATION

+

The implementation for evaluating the polynomials at some point uses +Horn's rule, which guarantees numerical stability and a minimum of +arithmetic operations. +To recognise that a polynomial definition is indeed a correct +definition, it consists of a list of two elements: the keyword +"POLYNOMIAL" and the list of coefficients in descending order. The +latter makes it easier to implement Horner's rule.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: polynomials of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/qcomplex.html Index: embedded/www/tcllib/files/modules/math/qcomplex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/qcomplex.html @@ -0,0 +1,337 @@ + + +math::complexnumbers - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::complexnumbers(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::complexnumbers - Straightforward complex number package

+
+ + +

Description

+

The mathematical module complexnumbers provides a straightforward +implementation of complex numbers in pure Tcl. The philosophy is that +the user knows he or she is dealing with complex numbers in an abstract +way and wants as high a performance as can be had within the limitations +of an interpreted language.

+

Therefore the procedures defined in this package assume that the +arguments are valid (representations of) "complex numbers", that is, +lists of two numbers defining the real and imaginary part of a +complex number (though this is a mere detail: rely on the +complex command to construct a valid number.)

+

Most procedures implement the basic arithmetic operations or elementary +functions whereas several others convert to and from different +representations:

+
+    set z [complex 0 1]
+    puts "z = [tostring $z]"
+    puts "z**2 = [* $z $z]
+
+

would result in:

+
+    z = i
+    z**2 = -1
+
+
+

AVAILABLE PROCEDURES

+

The package implements all or most basic operations and elementary +functions.

+

The arithmetic operations are:

+
+
::math::complexnumbers::+ z1 z2
+

Add the two arguments and return the resulting complex number

+
+
complex z1 (in)
+

First argument in the summation

+
complex z2 (in)
+

Second argument in the summation

+
+
::math::complexnumbers::- z1 z2
+

Subtract the second argument from the first and return the +resulting complex number. If there is only one argument, the +opposite of z1 is returned (i.e. -z1)

+
+
complex z1 (in)
+

First argument in the subtraction

+
complex z2 (in)
+

Second argument in the subtraction (optional)

+
+
::math::complexnumbers::* z1 z2
+

Multiply the two arguments and return the resulting complex number

+
+
complex z1 (in)
+

First argument in the multiplication

+
complex z2 (in)
+

Second argument in the multiplication

+
+
::math::complexnumbers::/ z1 z2
+

Divide the first argument by the second and return the resulting complex +number

+
+
complex z1 (in)
+

First argument (numerator) in the division

+
complex z2 (in)
+

Second argument (denominator) in the division

+
+
::math::complexnumbers::conj z1
+

Return the conjugate of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
+

Conversion/inquiry procedures:

+
+
::math::complexnumbers::real z1
+

Return the real part of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::imag z1
+

Return the imaginary part of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::mod z1
+

Return the modulus of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::arg z1
+

Return the argument ("angle" in radians) of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::complex real imag
+

Construct the complex number "real + imag*i" and return it

+
+
float real (in)
+

The real part of the new complex number

+
float imag (in)
+

The imaginary part of the new complex number

+
+
::math::complexnumbers::tostring z1
+

Convert the complex number to the form "real + imag*i" and return the +string

+
+
float complex (in)
+

The complex number to be converted

+
+
+

Elementary functions:

+
+
::math::complexnumbers::exp z1
+

Calculate the exponential for the given complex argument and return the +result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::sin z1
+

Calculate the sine function for the given complex argument and return +the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::cos z1
+

Calculate the cosine function for the given complex argument and return +the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::tan z1
+

Calculate the tangent function for the given complex argument and +return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::log z1
+

Calculate the (principle value of the) logarithm for the given complex +argument and return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::sqrt z1
+

Calculate the (principle value of the) square root for the given complex +argument and return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::pow z1 z2
+

Calculate "z1 to the power of z2" and return the result

+
+
complex z1 (in)
+

The complex number to be raised to a power

+
complex z2 (in)
+

The complex power to be used

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: complexnumbers of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/rational_funcs.html Index: embedded/www/tcllib/files/modules/math/rational_funcs.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/rational_funcs.html @@ -0,0 +1,278 @@ + + +math::rationalfunctions - Math + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::rationalfunctions(n) 1.0.1 tcllib "Math"

+

Name

+

math::rationalfunctions - Polynomial functions

+
+ + +

Description

+

This package deals with rational functions of one variable:

+
    +

  • the basic arithmetic operations are extended to rational functions

    • +

  • computing the derivatives of these functions

    • +

  • evaluation through a general procedure or via specific procedures)

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::rationalfunctions::rationalFunction num den
+

Return an (encoded) list that defines the rational function. A +rational function

+
+             1 + x^3
+   f(x) = ------------
+          1 + 2x + x^2
+
+

can be defined via:

+
+   set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1]  [list 1 2 1]]
+
+
+
list num
+

Coefficients of the numerator of the rational +function (in ascending order)

+
list den
+

Coefficients of the denominator of the rational +function (in ascending order)

+
+
::math::rationalfunctions::ratioCmd num den
+

Create a new procedure that evaluates the rational function. The name of the +function is automatically generated. Useful if you need to evaluate +the function many times, as the procedure consists of a single +[expr] command.

+
+
list num
+

Coefficients of the numerator of the rational +function (in ascending order)

+
list den
+

Coefficients of the denominator of the rational +function (in ascending order)

+
+
::math::rationalfunctions::evalRatio rational x
+

Evaluate the rational function at x.

+
+
list rational
+

The rational function's definition (as returned +by the rationalFunction command). +order)

+
float x
+

The coordinate at which to evaluate the function

+
+
::math::rationalfunctions::addRatio ratio1 ratio2
+

Return a new rational function which is the sum of the two others.

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::subRatio ratio1 ratio2
+

Return a new rational function which is the difference of the two +others.

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::multRatio ratio1 ratio2
+

Return a new rational function which is the product of the two others. +If one of the arguments is a scalar value, the other rational function is +simply scaled.

+
+
list ratio1
+

The first rational function operand or a scalar

+
list ratio2
+

The second rational function operand or a scalar

+
+
::math::rationalfunctions::divRatio ratio1 ratio2
+

Divide the first rational function by the second rational function and +return the result. The remainder is dropped

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::derivPolyn ratio
+

Differentiate the rational function and return the result.

+
+
list ratio
+

The rational function to be differentiated

+
+
::math::rationalfunctions::coeffsNumerator ratio
+

Return the coefficients of the numerator of the rational function.

+
+
list ratio
+

The rational function to be examined

+
+
::math::rationalfunctions::coeffsDenominator ratio
+

Return the coefficients of the denominator of the rational +function.

+
+
list ratio
+

The rational function to be examined

+
+
+
+

REMARKS ON THE IMPLEMENTATION

+

The implementation of the rational functions relies on the +math::polynomials package. For further remarks see the documentation on +that package.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: rationalfunctions of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/roman.html Index: embedded/www/tcllib/files/modules/math/roman.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/roman.html @@ -0,0 +1,184 @@ + + +math::roman - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::roman() 1.0 tcllib "Tcl Math Library"

+

Name

+

math::roman - Tools for creating and manipulating roman numerals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require math::roman ?1.0?
    • +
+ +
+
+

Description

+

::math::roman is a pure-Tcl library for converting between integers + and roman numerals. It also provides utility functions for sorting and performing + arithmetic on roman numerals.

+

This code was originally harvested from the Tcler's wiki at + http://wiki.tcl.tk/1823 and as such is free for any use for + any purpose. Many thanks to the ingeneous folk who devised + these clever routines and generously contributed them to the + Tcl community.

+

While written and tested under Tcl 8.3, I expect this library + will work under all 8.x versions of Tcl.

+
+

COMMANDS

+
+ +
::math::roman::toroman i
+

Convert an integer to roman numerals. The result is always in + upper case. The value zero is converted to an empty string.

+
::math::roman::tointeger r
+

Convert a roman numeral into an integer.

+
::math::roman::sort list
+

Sort a list of roman numerals from smallest to largest.

+
::math::roman::expr args
+

Evaluate an expression where the operands are all roman numerals.

+
+

Of these commands both toroman and tointeger are exported +for easier use. The other two are not, as they could interfer or be +confused with existing Tcl commands.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: roman of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/romberg.html Index: embedded/www/tcllib/files/modules/math/romberg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/romberg.html @@ -0,0 +1,400 @@ + +math::calculus::romberg - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::calculus::romberg(n) 0.6 tcllib "Tcl Math Library"

+

Name

+

math::calculus::romberg - Romberg integration

+
+ + +

Description

+

The romberg procedures in the math::calculus package +perform numerical integration of a function of one variable. They +are intended to be of "production quality" in that they are robust, +precise, and reasonably efficient in terms of the number of function +evaluations.

+
+

PROCEDURES

+

The following procedures are available for Romberg integration:

+
+
::math::calculus::romberg f a b ?-option value...?
+

Integrates an analytic function over a given interval.

+
::math::calculus::romberg_infinity f a b ?-option value...?
+

Integrates an analytic function over a half-infinite interval.

+
::math::calculus::romberg_sqrtSingLower f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +lower limit.

+
::math::calculus::romberg_sqrtSingUpper f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +upper limit.

+
::math::calculus::romberg_powerLawLower gamma f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +lower limit.

+
::math::calculus::romberg_powerLawUpper gamma f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +upper limit.

+
::math::calculus::romberg_expLower f a b ?-option value...?
+

Integrates an exponentially growing function; the lower limit of the +region of integration may be arbitrarily large and negative.

+
::math::calculus::romberg_expUpper f a b ?-option value...?
+

Integrates an exponentially decaying function; the upper limit of the +region of integration may be arbitrarily large.

+
+
+

PARAMETERS

+
+
f
+

Function to integrate. Must be expressed as a single Tcl command, +to which will be appended a single argument, specifically, the +abscissa at which the function is to be evaluated. The first word +of the command will be processed with namespace which in the +caller's scope prior to any evaluation. Given this processing, the +command may local to the calling namespace rather than needing to be +global.

+
a
+

Lower limit of the region of integration.

+
b
+

Upper limit of the region of integration. For the +romberg_sqrtSingLower, romberg_sqrtSingUpper, +romberg_powerLawLower, romberg_powerLawUpper, +romberg_expLower, and romberg_expUpper procedures, +the lower limit must be strictly less than the upper. For +the other procedures, the limits may appear in either order.

+
gamma
+

Power to use for a power law singularity; see section +IMPROPER INTEGRALS for details.

+
+
+

OPTIONS

+
+
-abserror epsilon
+

Requests that the integration machinery proceed at most until +the estimated absolute error of the integral is less than +epsilon. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section IMPROPER INTEGRALS for details. Default +is 1.0e-08.

+
-relerror epsilon
+

Requests that the integration machinery proceed at most until +the estimated relative error of the integral is less than +epsilon. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section IMPROPER INTEGRALS for details. Default is +1.0e-06.

+
-maxiter m
+

Requests that integration terminate after at most n triplings of +the number of evaluations performed. In other words, given n +for -maxiter, the integration machinery will make at most +3**n evaluations of the function. Default is 14, corresponding +to a limit approximately 4.8 million evaluations. (Well-behaved +functions will seldom require more than a few hundred evaluations.)

+
-degree d
+

Requests that an extrapolating polynomial of degree d be used +in Romberg integration; see section DESCRIPTION for +details. Default is 4. Can be at most m-1.

+
+
+

DESCRIPTION

+

The romberg procedure performs Romberg integration using +the modified midpoint rule. Romberg integration is an iterative +process. At the first step, the function is evaluated at the +midpoint of the region of integration, and the value is multiplied by +the width of the interval for the coarsest possible estimate. +At the second step, the interval is divided into three parts, +and the function is evaluated at the midpoint of each part; the +sum of the values is multiplied by three. At the third step, +nine parts are used, at the fourth twenty-seven, and so on, +tripling the number of subdivisions at each step.

+

Once the interval has been divided at least d times, +a polynomial is fitted to the integrals estimated in the last +d+1 divisions. The integrals are considered to be a +function of the square of the width of the subintervals +(any good numerical analysis text will discuss this process +under "Romberg integration"). The polynomial is extrapolated +to a step size of zero, computing a value for the integral and +an estimate of the error.

+

This process will be well-behaved only if the function is analytic +over the region of integration; there may be removable singularities +at either end of the region provided that the limit of the function +(and of all its derivatives) exists as the ends are approached. +Thus, romberg may be used to integrate a function like +f(x)=sin(x)/x over an interval beginning or ending at zero.

+

Note that romberg will either fail to converge or else return +incorrect error estimates if the function, or any of its derivatives, +has a singularity anywhere in the region of integration (except for +the case mentioned above). Care must be used, therefore, in +integrating a function like 1/(1-x**2) to avoid the places +where the derivative is singular.

+
+

IMPROPER INTEGRALS

+

Romberg integration is also useful for integrating functions over +half-infinite intervals or functions that have singularities. +The trick is to make a change of variable to eliminate the +singularity, and to put the singularity at one end or the other +of the region of integration. The math::calculus package +supplies a number of romberg procedures to deal with the +commoner cases.

+
+
romberg_infinity
+

Integrates a function over a half-infinite interval; either +a or b may be infinite. a and b must be +of the same sign; if you need to integrate across the axis, +say, from a negative value to positive infinity, +use romberg to integrate from the negative +value to a small positive value, and then romberg_infinity +to integrate from the positive value to positive infinity. The +romberg_infinity procedure works by making the change of +variable u=1/x, so that the integral from a to b of f(x) is +evaluated as the integral from 1/a to 1/b of f(1/u)/u**2.

+
romberg_powerLawLower and romberg_powerLawUpper
+

Integrate a function that has an integrable power law singularity +at either the lower or upper bound of the region of integration +(or has a derivative with a power law singularity there). +These procedures take a first parameter, gamma, which gives +the power law. The function or its first derivative are presumed to diverge as +(x-a)**(-gamma) or (b-x)**(-gamma). gamma +must be greater than zero and less than 1.

+

These procedures are useful not only in integrating functions +that go to infinity at one end of the region of integration, but +also functions whose derivatives do not exist at the end of +the region. For instance, integrating f(x)=pow(x,0.25) with the +origin as one end of the region will result in the romberg +procedure greatly underestimating the error in the integral. +The problem can be fixed by observing that the first derivative +of f(x), f'(x)=x**(-3/4)/4, goes to infinity at the origin. Integrating +using romberg_powerLawLower with gamma set to 0.75 +gives much more orderly convergence.

+

These procedures operate by making the change of variable +u=(x-a)**(1-gamma) (romberg_powerLawLower) or +u=(b-x)**(1-gamma) (romberg_powerLawUpper).

+

To summarize the meaning of gamma:

+
    +

  • If f(x) ~ x**(-a) (0 < a < 1), use gamma = a

    • +

  • If f'(x) ~ x**(-b) (0 < b < 1), use gamma = b

    • +
+
romberg_sqrtSingLower and romberg_sqrtSingUpper
+

These procedures behave identically to romberg_powerLawLower and +romberg_powerLawUpper for the common case of gamma=0.5; +that is, they integrate a function with an inverse square root +singularity at one end of the interval. They have a simpler +implementation involving square roots rather than arbitrary powers.

+
romberg_expLower and romberg_expUpper
+

These procedures are for integrating a function that grows or +decreases exponentially over a half-infinite interval. +romberg_expLower handles exponentially growing functions, and +allows the lower limit of integration to be an arbitrarily large +negative number. romberg_expUpper handles exponentially +decaying functions and allows the upper limit of integration to +be an arbitrary large positive number. The functions make the +change of variable u=exp(-x) and u=exp(x) respectively.

+
+
+

OTHER CHANGES OF VARIABLE

+

If you need an improper integral other than the ones listed here, +a change of variable can be written in very few lines of Tcl. +Because the Tcl coding that does it is somewhat arcane, +we offer a worked example here.

+

Let's say that the function that we want to integrate is +f(x)=exp(x)/sqrt(1-x*x) (not a very natural +function, but a good example), and we want to integrate +it over the interval (-1,1). The denominator falls to zero +at both ends of the interval. We wish to make a change of variable +from x to u +so that dx/sqrt(1-x**2) maps to du. Choosing x=sin(u), we can +find that dx=cos(u)*du, and sqrt(1-x**2)=cos(u). The integral +from a to b of f(x) is the integral from asin(a) to asin(b) +of f(sin(u))*cos(u).

+

We can make a function g that accepts an arbitrary function +f and the parameter u, and computes this new integrand.

+
+proc g { f u } {
+    set x [expr { sin($u) }]
+    set cmd $f; lappend cmd $x; set y [eval $cmd]
+    return [expr { $y / cos($u) }]
+}
+
+

Now integrating f from a to b is the same +as integrating g from asin(a) to asin(b). +It's a little tricky to get f consistently evaluated in +the caller's scope; the following procedure does it.

+
+proc romberg_sine { f a b args } {
+    set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]]
+    set f [list g $f]
+    return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]]
+}
+
+

This romberg_sine procedure will do any function with +sqrt(1-x*x) in the denominator. Our sample function is +f(x)=exp(x)/sqrt(1-x*x):

+
+proc f { x } {
+    expr { exp($x) / sqrt( 1. - $x*$x ) }
+}
+
+

Integrating it is a matter of applying romberg_sine +as we would any of the other romberg procedures:

+
+foreach { value error } [romberg_sine f -1.0 1.0] break
+puts [format "integral is %.6g +/- %.6g" $value $error]
+integral is 3.97746 +/- 2.3557e-010
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/special.html Index: embedded/www/tcllib/files/modules/math/special.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/special.html @@ -0,0 +1,502 @@ + + +math::special - Tcl Math Library + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::special(n) 0.2 tcllib "Tcl Math Library"

+

Name

+

math::special - Special mathematical functions

+
+ + +

Description

+

This package implements several so-called special functions, like +the Gamma function, the Bessel functions and such.

+

Each function is implemented by a procedure that bears its name (well, +in close approximation):

+
    +

  • J0 for the zeroth-order Bessel function of the first kind

    • +

  • J1 for the first-order Bessel function of the first kind

    • +

  • Jn for the nth-order Bessel function of the first kind

    • +

  • J1/2 for the half-order Bessel function of the first kind

    • +

  • J-1/2 for the minus-half-order Bessel function of the first kind

    • +

  • I_n for the modified Bessel function of the first kind of order n

    • +

  • Gamma for the Gamma function, erf and erfc for the error function and +the complementary error function

    • +

  • fresnel_C and fresnel_S for the Fresnel integrals

    • +

  • elliptic_K and elliptic_E (complete elliptic integrals)

    • +

  • exponent_Ei and other functions related to the so-called exponential +integrals

    • +

  • legendre, hermite: some of the classical orthogonal polynomials.

    • +
+
+

OVERVIEW

+

In the following table several characteristics of the functions in this +package are summarized: the domain for the argument, the values for the +parameters and error bounds.

+
+Family       | Function    | Domain x    | Parameter   | Error bound
+-------------+-------------+-------------+-------------+--------------
+Bessel       | J0, J1,     | all of R    | n = integer |   < 1.0e-8
+             | Jn          |             |             |  (|x|<20, n<20)
+Bessel       | J1/2, J-1/2,|  x > 0      | n = integer |   exact
+Bessel       | I_n         | all of R    | n = integer |   < 1.0e-6
+             |             |             |             |
+Elliptic     | cn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+functions    | dn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+             | sn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+Elliptic     | K           | 0 <= x < 1  |     --      |   < 1.0e-6
+integrals    | E           | 0 <= x < 1  |     --      |   < 1.0e-6
+             |             |             |             |
+Error        | erf         |             |     --      |
+functions    | erfc        |             |             |
+             | ierfc_n     |             |             |
+             |             |             |             |
+Exponential  | Ei          |  x != 0     |     --      |   < 1.0e-10 (relative)
+integrals    | En          |  x >  0     |     --      |   as Ei
+             | li          |  x > 0      |     --      |   as Ei
+             | Chi         |  x > 0      |     --      |   < 1.0e-8
+             | Shi         |  x > 0      |     --      |   < 1.0e-8
+             | Ci          |  x > 0      |     --      |   < 2.0e-4
+             | Si          |  x > 0      |     --      |   < 2.0e-4
+             |             |             |             |
+Fresnel      | C           |  all of R   |     --      |   < 2.0e-3
+integrals    | S           |  all of R   |     --      |   < 2.0e-3
+             |             |             |             |
+general      | Beta        | (see Gamma) |     --      |   < 1.0e-9
+             | Gamma       |  x != 0,-1, |     --      |   < 1.0e-9
+             |             |  -2, ...    |             |
+             | sinc        |  all of R   |     --      |   exact
+             |             |             |             |
+orthogonal   | Legendre    |  all of R   | n = 0,1,... |   exact
+polynomials  | Chebyshev   |  all of R   | n = 0,1,... |   exact
+             | Laguerre    |  all of R   | n = 0,1,... |   exact
+             |             |             | alpha el. R |
+             | Hermite     |  all of R   | n = 0,1,... |   exact
+
+

Note: Some of the error bounds are estimated, as no +"formal" bounds were available with the implemented approximation +method, others hold for the auxiliary functions used for estimating +the primary functions.

+

The following well-known functions are currently missing from the package:

+
    +

  • Bessel functions of the second kind (Y_n, K_n)

    • +

  • Bessel functions of arbitrary order (and hence the Airy functions)

    • +

  • Chebyshev polynomials of the second kind (U_n)

    • +

  • The digamma function (psi)

    • +

  • The incomplete gamma and beta functions

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::special::Beta x y
+

Compute the Beta function for arguments "x" and "y"

+
+
float x
+

First argument for the Beta function

+
float y
+

Second argument for the Beta function

+
+
::math::special::Gamma x y
+

Compute the Gamma function for argument "x"

+
+
float x
+

Argument for the Gamma function

+
+
::math::special::erf x
+

Compute the error function for argument "x"

+
+
float x
+

Argument for the error function

+
+
::math::special::erfc x
+

Compute the complementary error function for argument "x"

+
+
float x
+

Argument for the complementary error function

+
+
::math::special::J0 x
+

Compute the zeroth-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::J1 x
+

Compute the first-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::Jn n x
+

Compute the nth-order Bessel function of the first kind for the +argument "x"

+
+
integer n
+

Order of the Bessel function

+
float x
+

Argument for the Bessel function

+
+
::math::special::J1/2 x
+

Compute the half-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::J-1/2 x
+

Compute the minus-half-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::I_n x
+

Compute the modified Bessel function of the first kind of order n for +the argument "x"

+
+
int x
+

Positive integer order of the function

+
float x
+

Argument for the function

+
+
::math::special::cn u k
+

Compute the elliptic function cn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::dn u k
+

Compute the elliptic function dn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::sn u k
+

Compute the elliptic function sn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::elliptic_K k
+

Compute the complete elliptic integral of the first kind +for the argument "k"

+
+
float k
+

Argument for the function

+
+
::math::special::elliptic_E k
+

Compute the complete elliptic integral of the second kind +for the argument "k"

+
+
float k
+

Argument for the function

+
+
::math::special::exponential_Ei x
+

Compute the exponential integral of the second kind +for the argument "x"

+
+
float x
+

Argument for the function (x != 0)

+
+
::math::special::exponential_En n x
+

Compute the exponential integral of the first kind +for the argument "x" and order n

+
+
int n
+

Order of the integral (n >= 0)

+
float x
+

Argument for the function (x >= 0)

+
+
::math::special::exponential_li x
+

Compute the logarithmic integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Ci x
+

Compute the cosine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Si x
+

Compute the sine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Chi x
+

Compute the hyperbolic cosine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Shi x
+

Compute the hyperbolic sine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::fresnel_C x
+

Compute the Fresnel cosine integral for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::fresnel_S x
+

Compute the Fresnel sine integral for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::sinc x
+

Compute the sinc function for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::legendre n
+

Return the Legendre polynomial of degree n +(see THE ORTHOGONAL POLYNOMIALS)

+
+
int n
+

Degree of the polynomial

+
+
::math::special::chebyshev n
+

Return the Chebyshev polynomial of degree n (of the first kind)

+
+
int n
+

Degree of the polynomial

+
+
::math::special::laguerre alpha n
+

Return the Laguerre polynomial of degree n with parameter alpha

+
+
float alpha
+

Parameter of the Laguerre polynomial

+
int n
+

Degree of the polynomial

+
+
::math::special::hermite n
+

Return the Hermite polynomial of degree n

+
+
int n
+

Degree of the polynomial

+
+
+
+

THE ORTHOGONAL POLYNOMIALS

+

For dealing with the classical families of orthogonal polynomials, the +package relies on the math::polynomials package. To evaluate the +polynomial at some coordinate, use the evalPolyn command:

+
+   set leg2 [::math::special::legendre 2]
+   puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]"
+
+

The return value from the legendre and other commands is actually +the definition of the corresponding polynomial as used in that package.

+
+

REMARKS ON THE IMPLEMENTATION

+

It should be noted, that the actual implementation of J0 and J1 depends +on straightforward Gaussian quadrature formulas. The (absolute) accuracy +of the results is of the order 1.0e-4 or better. The main reason to +implement them like that was that it was fast to do (the formulas are +simple) and the computations are fast too.

+

The implementation of J1/2 does not suffer from this: this function can +be expressed exactly in terms of elementary functions.

+

The functions J0 and J1 are the ones you will encounter most frequently +in practice.

+

The computation of I_n is based on Miller's algorithm for computing the +minimal function from recurrence relations.

+

The computation of the Gamma and Beta functions relies on the +combinatorics package, whereas that of the error functions relies on the +statistics package.

+

The computation of the complete elliptic integrals uses the AGM +algorithm.

+

Much information about these functions can be found in:

+

Abramowitz and Stegun: Handbook of Mathematical Functions +(Dover, ISBN 486-61272-4)

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: special of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/statistics.html Index: embedded/www/tcllib/files/modules/math/statistics.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/statistics.html @@ -0,0 +1,1263 @@ + +math::statistics - Tcl Math Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::statistics(n) 0.8 tcllib "Tcl Math Library"

+

Name

+

math::statistics - Basic statistical functions and procedures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require math::statistics 0.8
    • +
+ +
+
+

Description

+

The math::statistics package contains functions and procedures for +basic statistical data analysis, such as:

+
    +

  • Descriptive statistical parameters (mean, minimum, maximum, standard +deviation)

    • +

  • Estimates of the distribution in the form of histograms and quantiles

    • +

  • Basic testing of hypotheses

    • +

  • Probability and cumulative density functions

    • +
+

It is meant to help in developing data analysis applications or doing +ad hoc data analysis, it is not in itself a full application, nor is it +intended to rival with full (non-)commercial statistical packages.

+

The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. +The package contains a fairly large number of public procedures. They +can be distinguished in three sets: general procedures, procedures +that deal with specific statistical distributions, list procedures to +select or transform data and simple plotting procedures (these require +Tk). +Note: The data that need to be analyzed are always contained in a +simple list. Missing values are represented as empty list elements.

+
+

GENERAL PROCEDURES

+

The general statistical procedures are:

+
+
::math::statistics::mean data
+

Determine the mean value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::min data
+

Determine the minimum value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::max data
+

Determine the maximum value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::number data
+

Determine the number of non-missing data in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::stdev data
+

Determine the sample standard deviation of the data in the +given list

+
+
list data
+

- List of data

+
+
::math::statistics::var data
+

Determine the sample variance of the data in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::pstdev data
+

Determine the population standard deviation of the data +in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::pvar data
+

Determine the population variance of the data in the +given list

+
+
list data
+

- List of data

+
+
::math::statistics::median data
+

Determine the median of the data in the given list +(Note that this requires sorting the data, which may be a +costly operation)

+
+
list data
+

- List of data

+
+
::math::statistics::basic-stats data
+

Determine a list of all the descriptive parameters: mean, minimum, +maximum, number of data, sample standard deviation, sample variance, +population standard deviation and population variance.

+

(This routine is called whenever either or all of the basic statistical +parameters are required. Hence all calculations are done and the +relevant values are returned.)

+
+
list data
+

- List of data

+
+
::math::statistics::histogram limits values
+

Determine histogram information for the given list of data. Returns a +list consisting of the number of values that fall into each interval. +(The first interval consists of all values lower than the first limit, +the last interval consists of all values greater than the last limit. +There is one more interval than there are limits.)

+
+
list limits
+

- List of upper limits (in ascending order) for the +intervals of the histogram.

+
list values
+

- List of data

+
+
::math::statistics::corr data1 data2
+

Determine the correlation coefficient between two sets of data.

+
+
list data1
+

- First list of data

+
list data2
+

- Second list of data

+
+
::math::statistics::interval-mean-stdev data confidence
+

Return the interval containing the mean value and one +containing the standard deviation with a certain +level of confidence (assuming a normal distribution)

+
+
list data
+

- List of raw data values (small sample)

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance)

+
+
::math::statistics::t-test-mean data est_mean est_stdev confidence
+

Test whether the mean value of a sample is in accordance with the +estimated normal distribution with a certain level of confidence. +Returns 1 if the test succeeds or 0 if the mean is unlikely to fit +the given distribution.

+
+
list data
+

- List of raw data values (small sample)

+
float est_mean
+

- Estimated mean of the distribution

+
float est_stdev
+

- Estimated stdev of the distribution

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance)

+
+
::math::statistics::test-normal data confidence
+

Test whether the given data follow a normal distribution +with a certain level of confidence. +Returns 1 if the data are normally distributed within the level of +confidence, returns 0 if not. The underlying test is the Lilliefors +test.

+
+
list data
+

- List of raw data values

+
float confidence
+

- Confidence level (one of 0.80, 0.90, 0.95 or 0.99)

+
+
::math::statistics::lillieforsFit data
+

Returns the goodness of fit to a normal distribution according to +Lilliefors. The higher the number, the more likely the data are indeed +normally distributed. The test requires at least five data +points.

+
+
list data
+

- List of raw data values

+
+
::math::statistics::quantiles data confidence
+

Return the quantiles for a given set of data

+
+
list data
+

- List of raw data values

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance)

+
+
::math::statistics::quantiles limits counts confidence
+

Return the quantiles based on histogram information (alternative to the +call with two arguments)

+
+
list limits
+

- List of upper limits from histogram

+
list counts
+

- List of counts for for each interval in histogram

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance)

+
+
::math::statistics::autocorr data
+

Return the autocorrelation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data)

+

The correlation is determined in such a way that the first value is +always 1 and all others are equal to or smaller than 1. The number of +values involved will diminish as the "time" (the index in the list of +returned values) increases

+
+
list data
+

- Raw data for which the autocorrelation must be determined

+
+
::math::statistics::crosscorr data1 data2
+

Return the cross-correlation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data)

+

The correlation is determined in such a way that the values can never +exceed 1 in magnitude. The number of values involved will diminish +as the "time" (the index in the list of returned values) increases.

+
+
list data1
+

- First list of data

+
list data2
+

- Second list of data

+
+
::math::statistics::mean-histogram-limits mean stdev number
+

Determine reasonable limits based on mean and standard deviation +for a histogram +Convenience function - the result is suitable for the histogram function.

+
+
float mean
+

- Mean of the data

+
float stdev
+

- Standard deviation

+
int number
+

- Number of limits to generate (defaults to 8)

+
+
::math::statistics::minmax-histogram-limits min max number
+

Determine reasonable limits based on a minimum and maximum for a histogram

+

Convenience function - the result is suitable for the histogram function.

+
+
float min
+

- Expected minimum

+
float max
+

- Expected maximum

+
int number
+

- Number of limits to generate (defaults to 8)

+
+
::math::statistics::linear-model xdata ydata intercept
+

Determine the coefficients for a linear regression between +two series of data (the model: Y = A + B*X). Returns a list of +parameters describing the fit

+
+
list xdata
+

- List of independent data

+
list ydata
+

- List of dependent data to be fitted

+
boolean intercept
+

- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0)

+

The result consists of the following list:

+
    +

  • (Estimate of) Intercept A

    • +

  • (Estimate of) Slope B

    • +

  • Standard deviation of Y relative to fit

    • +

  • Correlation coefficient R2

    • +

  • Number of degrees of freedom df

    • +

  • Standard error of the intercept A

    • +

  • Significance level of A

    • +

  • Standard error of the slope B

    • +

  • Significance level of B

    • +
+
+
::math::statistics::linear-residuals xdata ydata intercept
+

Determine the difference between actual data and predicted from +the linear model.

+

Returns a list of the differences between the actual data and the +predicted values.

+
+
list xdata
+

- List of independent data

+
list ydata
+

- List of dependent data to be fitted

+
boolean intercept
+

- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0)

+
+
::math::statistics::test-2x2 n11 n21 n12 n22
+

Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter).

+

Returns the "chi-square" value, which can be used to the determine the +significance.

+
+
int n11
+

- Number of outcomes with the first value from the first sample.

+
int n21
+

- Number of outcomes with the first value from the second sample.

+
int n12
+

- Number of outcomes with the second value from the first sample.

+
int n22
+

- Number of outcomes with the second value from the second sample.

+
+
::math::statistics::print-2x2 n11 n21 n12 n22
+

Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter).

+

Returns a short report, useful in an interactive session.

+
+
int n11
+

- Number of outcomes with the first value from the first sample.

+
int n21
+

- Number of outcomes with the first value from the second sample.

+
int n12
+

- Number of outcomes with the second value from the first sample.

+
int n22
+

- Number of outcomes with the second value from the second sample.

+
+
::math::statistics::control-xbar data ?nsamples?
+

Determine the control limits for an xbar chart. The number of data +in each subsample defaults to 4. At least 20 subsamples are required.

+

Returns the mean, the lower limit, the upper limit and the number of +data per subsample.

+
+
list data
+

- List of observed data

+
int nsamples
+

- Number of data per subsample

+
+
::math::statistics::control-Rchart data ?nsamples?
+

Determine the control limits for an R chart. The number of data +in each subsample (nsamples) defaults to 4. At least 20 subsamples are required.

+

Returns the mean range, the lower limit, the upper limit and the number +of data per subsample.

+
+
list data
+

- List of observed data

+
int nsamples
+

- Number of data per subsample

+
+
::math::statistics::test-xbar control data
+

Determine if the data exceed the control limits for the xbar chart.

+

Returns a list of subsamples (their indices) that indeed violate the +limits.

+
+
list control
+

- Control limits as returned by the "control-xbar" procedure

+
list data
+

- List of observed data

+
+
::math::statistics::test-Rchart control data
+

Determine if the data exceed the control limits for the R chart.

+

Returns a list of subsamples (their indices) that indeed violate the +limits.

+
+
list control
+

- Control limits as returned by the "control-Rchart" procedure

+
list data
+

- List of observed data

+
+
+
+

MULTIVARIATE LINEAR REGRESSION

+

Besides the linear regression with a single independent variable, the +statistics package provides two procedures for doing ordinary +least squares (OLS) and weighted least squares (WLS) linear regression +with several variables. They were written by Eric Kemp-Benedict.

+

In addition to these two, it provides a procedure (tstat) +for calculating the value of the t-statistic for the specified number of +degrees of freedom that is required to demonstrate a given level of +significance.

+

Note: These procedures depend on the math::linearalgebra package.

+

Description of the procedures

+
+
::math::statistics::tstat dof ?alpha?
+

Returns the value of the t-distribution t* satisfying

+
+    P(t*)  =  1 - alpha/2
+    P(-t*) =  alpha/2
+
+

for the number of degrees of freedom dof.

+

Given a sample of normally-distributed data x, with an +estimate xbar for the mean and sbar for the standard deviation, +the alpha confidence interval for the estimate of the mean can +be calculated as

+
+      ( xbar - t* sbar , xbar + t* sbar)
+
+

The return values from this procedure can be compared to +an estimated t-statistic to determine whether the estimated +value of a parameter is significantly different from zero at +the given confidence level.

+
+
int dof
+

Number of degrees of freedom

+
float alpha
+

Confidence level of the t-distribution. Defaults to 0.05.

+
+
::math::statistics::mv-wls wt1 weights_and_values
+

Carries out a weighted least squares linear regression for +the data points provided, with weights assigned to each point.

+

The linear model is of the form

+
+    y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error
+
+

and each point satisfies

+
+    yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i
+
+

The procedure returns a list with the following elements:

+
    +

  • The r-squared statistic

    • +

  • The adjusted r-squared statistic

    • +

  • A list containing the estimated coefficients b1, ... bN, b0 +(The constant b0 comes last in the list.)

    • +

  • A list containing the standard errors of the coefficients

    • +

  • A list containing the 95% confidence bounds of the coefficients, +with each set of bounds returned as a list with two values

    • +
+

Arguments:

+
+
list weights_and_values
+

A list consisting of: the weight for the first observation, the data +for the first observation (as a sublist), the weight for the second +observation (as a sublist) and so on. The sublists of data are organised +as lists of the value of the dependent variable y and the independent +variables x1, x2 to xN.

+
+
::math::statistics::mv-ols values
+

Carries out an ordinary least squares linear regression for +the data points provided.

+

This procedure simply calls ::mvlinreg::wls with the weights +set to 1.0, and returns the same information.

+
+

Example of the use:

+
+# Store the value of the unicode value for the "+/-" character
+set pm "\u00B1"
+# Provide some data
+set data {{  -.67  14.18  60.03 -7.5  }
+          { 36.97  15.52  34.24 14.61 }
+          {-29.57  21.85  83.36 -7.   }
+          {-16.9   11.79  51.67 -6.56 }
+          { 14.09  16.24  36.97 -12.84}
+          { 31.52  20.93  45.99 -25.4 }
+          { 24.05  20.69  50.27  17.27}
+          { 22.23  16.91  45.07  -4.3 }
+          { 40.79  20.49  38.92  -.73 }
+          {-10.35  17.24  58.77  18.78}}
+# Call the ols routine
+set results [::math::statistics::mv-ols $data]
+# Pretty-print the results
+puts "R-squared: [lindex $results 0]"
+puts "Adj R-squared: [lindex $results 1]"
+puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
+foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
+    set lb [lindex $bounds 0]
+    set ub [lindex $bounds 1]
+    puts "   $val $pm $se -- \[$lb to $ub\]"
+}
+
+
+

STATISTICAL DISTRIBUTIONS

+

In the literature a large number of probability distributions can be +found. The statistics package supports:

+
    +

  • The normal or Gaussian distribution

    • +

  • The uniform distribution - equal probability for all data within a given +interval

    • +

  • The exponential distribution - useful as a model for certain +extreme-value distributions.

    • +

  • The gamma distribution - based on the incomplete Gamma integral

    • +

  • The chi-square distribution

    • +

  • The student's T distribution

    • +

  • The Poisson distribution

    • +

  • PM - binomial,F.

    • +
+

In principle for each distribution one has procedures for:

+
    +

  • The probability density (pdf-*)

    • +

  • The cumulative density (cdf-*)

    • +

  • Quantiles for the given distribution (quantiles-*)

    • +

  • Histograms for the given distribution (histogram-*)

    • +

  • List of random values with the given distribution (random-*)

    • +
+

The following procedures have been implemented:

+
+
::math::statistics::pdf-normal mean stdev value
+

Return the probability of a given value for a normal distribution with +given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-exponential mean value
+

Return the probability of a given value for an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-uniform xmin xmax value
+

Return the probability of a given value for a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmin
+

- Maximum value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-gamma alpha beta value
+

Return the probability of a given value for a Gamma +distribution with given shape and rate parameters

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-poisson mu k
+

Return the probability of a given number of occurrences in the same +interval (k) for a Poisson distribution with given mean (mu)

+
+
float mu
+

- Mean number of occurrences

+
int k
+

- Number of occurences

+
+
::math::statistics::pdf-chisquare df value
+

Return the probability of a given value for a chi square +distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-student-t df value
+

Return the probability of a given value for a Student's t +distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-beta a b value
+

Return the probability of a given value for a Beta +distribution with given shape parameters

+
+
float a
+

- First shape parameter

+
float b
+

- First shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-normal mean stdev value
+

Return the cumulative probability of a given value for a normal +distribution with given mean and standard deviation, that is the +probability for values up to the given one.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-exponential mean value
+

Return the cumulative probability of a given value for an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-uniform xmin xmax value
+

Return the cumulative probability of a given value for a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmin
+

- Maximum value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-students-t degrees value
+

Return the cumulative probability of a given value for a Student's t +distribution with given number of degrees.

+
+
int degrees
+

- Number of degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-gamma alpha beta value
+

Return the cumulative probability of a given value for a Gamma +distribution with given shape and rate parameters

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
float value
+

- Value for which the cumulative probability is required

+
+
::math::statistics::cdf-poisson mu k
+

Return the cumulative probability of a given number of occurrences in +the same interval (k) for a Poisson distribution with given mean (mu)

+
+
float mu
+

- Mean number of occurrences

+
int k
+

- Number of occurences

+
+
::math::statistics::cdf-beta a b value
+

Return the cumulative probability of a given value for a Beta +distribution with given shape parameters

+
+
float a
+

- First shape parameter

+
float b
+

- First shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::random-normal mean stdev number
+

Return a list of "number" random values satisfying a normal +distribution with given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-exponential mean number
+

Return a list of "number" random values satisfying an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-uniform xmin xmax number
+

Return a list of "number" random values satisfying a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmax
+

- Maximum value of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-gamma alpha beta number
+

Return a list of "number" random values satisfying +a Gamma distribution with given shape and rate parameters

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-chisquare df number
+

Return a list of "number" random values satisfying +a chi square distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-student-t df number
+

Return a list of "number" random values satisfying +a Student's t distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-beta a b number
+

Return a list of "number" random values satisfying +a Beta distribution with given shape parameters

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::histogram-uniform xmin xmax limits number
+

Return the expected histogram for a uniform distribution.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmax
+

- Maximum value of the distribution

+
list limits
+

- Upper limits for the buckets in the histogram

+
int number
+

- Total number of "observations" in the histogram

+
+
::math::statistics::incompleteGamma x p ?tol?
+

Evaluate the incomplete Gamma integral

+
+                    1       / x               p-1
+      P(p,x) =  --------   |   dt exp(-t) * t
+                Gamma(p)  / 0
+
+
+
float x
+

- Value of x (limit of the integral)

+
float p
+

- Value of p in the integrand

+
float tol
+

- Required tolerance (default: 1.0e-9)

+
+
::math::statistics::incompleteBeta a b x ?tol?
+

Evaluate the incomplete Beta integral

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
float x
+

- Value of x (limit of the integral)

+
float tol
+

- Required tolerance (default: 1.0e-9)

+
+
+

TO DO: more function descriptions to be added

+
+

DATA MANIPULATION

+

The data manipulation procedures act on lists or lists of lists:

+
+
::math::statistics::filter varname data expression
+

Return a list consisting of the data for which the logical +expression is true (this command works analogously to the command foreach).

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of data

+
string expression
+

- Logical expression using the variable name

+
+
::math::statistics::map varname data expression
+

Return a list consisting of the data that are transformed via the +expression.

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of data

+
string expression
+

- Expression to be used to transform (map) the data

+
+
::math::statistics::samplescount varname list expression
+

Return a list consisting of the counts of all data in the +sublists of the "list" argument for which the expression is true.

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of sublists, each containing the data

+
string expression
+

- Logical expression to test the data (defaults to +"true").

+
+
::math::statistics::subdivide
+

Routine PM - not implemented yet

+
::math::statistics::test-Kruskal-Wallis confidence args
+

Check if the population medians of two or more groups are equal with a +given confidence level, using the Kruskal-Wallis test.

+
+
float confidence
+

- Confidence level to be used (0-1)

+
list args
+

- Two or more lists of data

+
+
::math::statistics::analyse-Kruskal-Wallis args
+

Compute the statistical parameters for the Kruskal-Wallis test. +Returns the Kruskal-Wallis statistic and the probability that that +value would occur assuming the medians of the populations are +equal.

+
+
list args
+

- Two or more lists of data

+
+
::math::statistics::group-rank args
+

Rank the groups of data with respect to the complete set. +Returns a list consisting of the group ID, the value and the rank +(possibly a rational number, in case of ties) for each data item.

+
+
list args
+

- Two or more lists of data

+
+
::math::statistics::test-Wilcoxon sample_a sample_b
+

Compute the Wilcoxon test statistic to determine if two samples have the +same median or not. (The statistic can be regarded as standard normal, if the +sample sizes are both larger than 10. Returns the value of this statistic.

+
+
list sample_a
+

- List of data comprising the first sample

+
list sample_b
+

- List of data comprising the second sample

+
+
::math::statistics::spearman-rank sample_a sample_b
+

Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient. The two samples should have the same number of data.

+
+
list sample_a
+

- First list of data

+
list sample_b
+

- Second list of data

+
+
::math::statistics::spearman-rank-extended sample_a sample_b
+

Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient as well as additional data. The two samples should have the same number of data. +The procedure returns the correlation coefficient, the number of data pairs used and the +z-score, an approximately standard normal statistic, indicating the significance of the correlation.

+
+
list sample_a
+

- First list of data

+
list sample_b
+

- Second list of data

+
+
+
+

PLOT PROCEDURES

+

The following simple plotting procedures are available:

+
+
::math::statistics::plot-scale canvas xmin xmax ymin ymax
+

Set the scale for a plot in the given canvas. All plot routines expect +this function to be called first. There is no automatic scaling +provided.

+
+
widget canvas
+

- Canvas widget to use

+
float xmin
+

- Minimum x value

+
float xmax
+

- Maximum x value

+
float ymin
+

- Minimum y value

+
float ymax
+

- Maximum y value

+
+
::math::statistics::plot-xydata canvas xdata ydata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The tag can be used to manipulate the +appearance.

+
+
widget canvas
+

- Canvas widget to use

+
float xdata
+

- Series of independent data

+
float ydata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-xyline canvas xdata ydata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a line through the data points. The tag can be used to +manipulate the appearance.

+
+
widget canvas
+

- Canvas widget to use

+
list xdata
+

- Series of independent data

+
list ydata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-tdata canvas tdata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The horizontal coordinate is equal to the +index. The tag can be used to manipulate the appearance. +This type of presentation is suitable for autocorrelation functions for +instance or for inspecting the time-dependent behaviour.

+
+
widget canvas
+

- Canvas widget to use

+
list tdata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-tline canvas tdata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a line. See plot-tdata for an explanation.

+
+
widget canvas
+

- Canvas widget to use

+
list tdata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-histogram canvas counts limits tag
+

Create a simple histogram in the given canvas

+
+
widget canvas
+

- Canvas widget to use

+
list counts
+

- Series of bucket counts

+
list limits
+

- Series of upper limits for the buckets

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
+
+

THINGS TO DO

+

The following procedures are yet to be implemented:

+
    +

  • F-test-stdev

    • +

  • interval-mean-stdev

    • +

  • histogram-normal

    • +

  • histogram-exponential

    • +

  • test-histogram

    • +

  • test-corr

    • +

  • quantiles-*

    • +

  • fourier-coeffs

    • +

  • fourier-residuals

    • +

  • onepar-function-fit

    • +

  • onepar-function-residuals

    • +

  • plot-linear-model

    • +

  • subdivide

    • +
+
+

EXAMPLES

+

The code below is a small example of how you can examine a set of +data:

+
+# Simple example:
+# - Generate data (as a cheap way of getting some)
+# - Perform statistical analysis to describe the data
+#
+package require math::statistics
+#
+# Two auxiliary procs
+#
+proc pause {time} {
+   set wait 0
+   after [expr {$time*1000}] {set ::wait 1}
+   vwait wait
+}
+proc print-histogram {counts limits} {
+   foreach count $counts limit $limits {
+      if { $limit != {} } {
+         puts [format "<%12.4g\t%d" $limit $count]
+         set prev_limit $limit
+      } else {
+         puts [format ">%12.4g\t%d" $prev_limit $count]
+      }
+   }
+}
+#
+# Our source of arbitrary data
+#
+proc generateData { data1 data2 } {
+   upvar 1 $data1 _data1
+   upvar 1 $data2 _data2
+   set d1 0.0
+   set d2 0.0
+   for { set i 0 } { $i < 100 } { incr i } {
+      set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}]
+      set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}]
+      lappend _data1 $d1
+      lappend _data2 $d2
+   }
+   return {}
+}
+#
+# The analysis session
+#
+package require Tk
+console show
+canvas .plot1
+canvas .plot2
+pack   .plot1 .plot2 -fill both -side top
+generateData data1 data2
+puts "Basic statistics:"
+set b1 [::math::statistics::basic-stats $data1]
+set b2 [::math::statistics::basic-stats $data2]
+foreach label {mean min max number stdev var} v1 $b1 v2 $b2 {
+   puts "$label\t$v1\t$v2"
+}
+puts "Plot the data as function of \"time\" and against each other"
+::math::statistics::plot-scale .plot1  0 100  0 20
+::math::statistics::plot-scale .plot2  0 20   0 20
+::math::statistics::plot-tline .plot1 $data1
+::math::statistics::plot-tline .plot1 $data2
+::math::statistics::plot-xydata .plot2 $data1 $data2
+puts "Correlation coefficient:"
+puts [::math::statistics::corr $data1 $data2]
+pause 2
+puts "Plot histograms"
+.plot2 delete all
+::math::statistics::plot-scale .plot2  0 20 0 100
+set limits         [::math::statistics::minmax-histogram-limits 7 16]
+set histogram_data [::math::statistics::histogram $limits $data1]
+::math::statistics::plot-histogram .plot2 $histogram_data $limits
+puts "First series:"
+print-histogram $histogram_data $limits
+pause 2
+set limits         [::math::statistics::minmax-histogram-limits 0 15 10]
+set histogram_data [::math::statistics::histogram $limits $data2]
+::math::statistics::plot-histogram .plot2 $histogram_data $limits d2
+.plot2 itemconfigure d2 -fill red
+puts "Second series:"
+print-histogram $histogram_data $limits
+puts "Autocorrelation function:"
+set  autoc [::math::statistics::autocorr $data1]
+puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
+puts "Cross-correlation function:"
+set  crossc [::math::statistics::crosscorr $data1 $data2]
+puts [::math::statistics::map $crossc {[format "%.2f" $x]}]
+::math::statistics::plot-scale .plot1  0 100 -1  4
+::math::statistics::plot-tline .plot1  $autoc "autoc"
+::math::statistics::plot-tline .plot1  $crossc "crossc"
+.plot1 itemconfigure autoc  -fill green
+.plot1 itemconfigure crossc -fill yellow
+puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9"
+puts "First:  [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]"
+puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]"
+
+

If you run this example, then the following should be clear:

+
    +

  • There is a strong correlation between two time series, as displayed by +the raw data and especially by the correlation functions.

    • +

  • Both time series show a significant periodic component

    • +

  • The histograms are not very useful in identifying the nature of the time +series - they do not show the periodic nature.

    • +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: statistics of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/symdiff.html Index: embedded/www/tcllib/files/modules/math/symdiff.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/math/symdiff.html @@ -0,0 +1,211 @@ + +math::calculus::symdiff - Symbolic differentiation for Tcl + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

math::calculus::symdiff(n) 1.0 tcllib "Symbolic differentiation for Tcl"

+

Name

+

math::calculus::symdiff - Symbolic differentiation for Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require grammar::aycock 1.0
    • +
  • package require math::calculus::symdiff 1.0
    • +
+ +
+
+

Description

+

The math::calculus::symdiff package provides a symbolic differentiation +facility for Tcl math expressions. It is useful for providing derivatives +to packages that either require the Jacobian of a set of functions or else +are more efficient or stable when the Jacobian is provided.

+
+

Procedures

+

The math::calculus::symdiff package exports the two procedures:

+
+
math::calculus::symdiff::symdiff expression variable
+

Differentiates the given expression with respect to the specified +variable. (See Expressions below for a discussion of the +subset of Tcl math expressions that are acceptable to +math::calculus::symdiff.) +The result is a Tcl expression that evaluates the derivative. Returns an +error if expression is not a well-formed expression or is not +differentiable.

+
math::calculus::jacobian variableDict
+

Computes the Jacobian of a system of equations. +The system is given by the dictionary variableDict, whose keys +are the names of variables in the system, and whose values are Tcl expressions +giving the values of those variables. (See Expressions below +for a discussion of the subset of Tcl math expressions that are acceptable +to math::calculus::symdiff. The result is a list of lists: +the i'th element of the j'th sublist is the partial derivative of +the i'th variable with respect to the j'th variable. Returns an error if +any of the expressions cannot be differentiated, or if variableDict +is not a well-formed dictionary.

+
+
+

Expressions

+

The math::calculus::symdiff package accepts only a small subset of the expressions +that are acceptable to Tcl commands such as expr or if. +Specifically, the only constructs accepted are:

+
    +

  • Floating-point constants such as 5 or 3.14159e+00.

    • +

  • References to Tcl variable using $-substitution. The variable names +must consist of alphanumerics and underscores: the ${...} notation +is not accepted.

    • +

  • Parentheses.

    • +

  • The +, -, *, /. and ** +operators.

    • +

  • Calls to the functions acos, asin, atan, +atan2, cos, cosh, exp, hypot, log, +log10, pow, sin, sinh. sqrt, tan, +and tanh.

    • +
+

Command substitution, backslash substitution, and argument expansion are +not accepted.

+
+

Examples

+
+math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x
+==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
+math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
+                         y {$c * $x + $d * $y}}
+==> {{$a} {$b}} {{$c} {$d}}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/md4/md4.html Index: embedded/www/tcllib/files/modules/md4/md4.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/md4/md4.html @@ -0,0 +1,264 @@ + +md4 - MD4 Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

md4(n) 1.0.5 tcllib "MD4 Message-Digest Algorithm"

+

Name

+

md4 - MD4 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the MD4 message-digest +algorithm as described in RFC 1320 (1) and (2). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD4 algorithm is faster but potentially weaker than +the related MD5 algorithm (3).

+

If you have critcl and have built the tcllibc package +then the implementation of the hashing function will be performed by compiled +code. Alternatively if cryptkit is available this will be +used. If no accelerator package can be found then the pure-tcl +implementation is used. The programming interface remains the same in +all cases.

+
+

COMMANDS

+
+
::md4::md4 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the MD4 digest of the data given in string. This is returned +as a binary string by default. Giving the -hex option will +return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the md4 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::md4::hmac ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the MD4 +digest algorithm. HMACs are described in RFC 2104 (4) and provide an MD4 +digest that includes a key. All options other than -key are as +for the ::md4::md4 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the MD4 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD4 hash operates on a token (equivalent to the +bucket). You call MD4Init to obtain a token and then call +MD4Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +MD4Final. An equivalent set of functions gives you a keyed digest (HMAC).

+
+
::md4::MD4Init
+

Begins a new MD4 hash. Returns a token ID that must be used for the +remaining functions.

+
::md4::MD4Update token data
+

Add data to the hash identified by token. Calling +MD4Update $token "abcd" is equivalent to calling +MD4Update $token "ab" followed by +MD4Update $token "cb". See EXAMPLES.

+
::md4::MD4Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD4 +digest value.

+
::md4::HMACInit key
+

This is equivalent to the ::md4::MD4Init command except that +it requires the key that will be included in the HMAC.

+
::md4::HMACUpdate token data
+
+
::md4::HMACFinal token
+

These commands are identical to the MD4 equivalent commands.

+
+
+

EXAMPLES

+
+% md4::md4 -hex "Tcl does MD4"
+858da9b31f57648a032230447bd15f25
+
+
+% md4::hmac -hex -key Sekret "Tcl does MD4"
+c324088e5752872689caedf2a0464758
+
+
+% set tok [md4::MD4Init]
+::md4::1
+% md4::MD4Update $tok "Tcl "
+% md4::MD4Update $tok "does "
+% md4::MD4Update $tok "MD4"
+% md4::Hex [md4::MD4Final $tok]
+858da9b31f57648a032230447bd15f25
+
+
+

REFERENCES

+
    +

  1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    2. +

  2. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    3. +

  3. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    4. +

  4. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    5. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md4 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/md5/md5.html Index: embedded/www/tcllib/files/modules/md5/md5.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/md5/md5.html @@ -0,0 +1,270 @@ + +md5 - MD5 Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

md5(n) 2.0.7 tcllib "MD5 Message-Digest Algorithm"

+

Name

+

md5 - MD5 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the MD5 message-digest +algorithm as described in RFC 1321 (1). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD5 algorithm is related to the MD4 algorithm (2) +but has been strengthened against certain types of potential +attack. MD5 should be used in preference to MD4 for new applications.

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Alternatively if you have either +cryptkit or Trf then either of these can be used to +accelerate the digest computation. If no suitable compiled package is +available then the pure-Tcl implementation wil be used. The +programming interface remains the same in all cases.

+

Note the previous version of this package always returned a +hex encoded string. This has been changed to simplify the programming +interface and to make this version more compatible with other +implementations. To obtain the previous usage, either explicitly +specify package version 1 or use the -hex option to the +md5 command.

+
+

COMMANDS

+
+
::md5::md5 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the MD5 digest of the data given in string. This is returned +as a binary string by default. Giving the -hex option will +return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the md5 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::md5::hmac ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the MD5 +digest algorithm. HMACs are described in RFC 2104 (3) and provide an MD5 +digest that includes a key. All options other than -key are as +for the ::md5::md5 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the MD5 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD5 hash operates on a token (equivalent to the +bucket). You call MD5Init to obtain a token and then call +MD5Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +MD5Final. An equivalent set of functions gives you a keyed digest +(HMAC).

+
+
::md5::MD5Init
+

Begins a new MD5 hash. Returns a token ID that must be used for the +remaining functions.

+
::md5::MD5Update token data
+

Add data to the hash identified by token. Calling +MD5Update $token "abcd" is equivalent to calling +MD5Update $token "ab" followed by +MD5Update $token "cb". See EXAMPLES.

+
::md5::MD5Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD5 +digest value.

+
::md5::HMACInit key
+

This is equivalent to the ::md5::MD5Init command except that +it requires the key that will be included in the HMAC.

+
::md5::HMACUpdate token data
+
+
::md5::HMACFinal token
+

These commands are identical to the MD5 equivalent commands.

+
+
+

EXAMPLES

+
+% md5::md5 -hex "Tcl does MD5"
+8AAC1EE01E20BB347104FABB90310433
+
+
+% md5::hmac -hex -key Sekret "Tcl does MD5"
+35BBA244FD56D3EDF5F3C47474DACB5D
+
+
+% set tok [md5::MD5Init]
+::md5::1
+% md5::MD5Update $tok "Tcl "
+% md5::MD5Update $tok "does "
+% md5::MD5Update $tok "MD5"
+% md5::Hex [md5::MD5Final $tok]
+8AAC1EE01E20BB347104FABB90310433
+
+
+

REFERENCES

+
    +

  1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md5 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/md5crypt/md5crypt.html Index: embedded/www/tcllib/files/modules/md5crypt/md5crypt.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/md5crypt/md5crypt.html @@ -0,0 +1,208 @@ + +md5crypt - MD5-based password encryption + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

md5crypt(n) 1.1.0 tcllib "MD5-based password encryption"

+

Name

+

md5crypt - MD5-based password encryption

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require md5 2.0
    • +
  • package require md5crypt ?1.1.0?
    • +
+ +
+
+

Description

+

This package provides an implementation of the MD5-crypt password +encryption algorithm as pioneered by FreeBSD and currently in use as a +replacement for the unix crypt(3) function in many modern +systems. An implementation of the closely related Apache MD5-crypt is +also available. +The output of these commands are compatible with the BSD and OpenSSL +implementation of md5crypt and the Apache 2 htpasswd program.

+
+

COMMANDS

+
+
::md5crypt::md5crypt password salt
+

Generate a BSD compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT).

+
::md5crypt::aprcrypt password salt
+

Generate an Apache compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT).

+
::md5crypt::salt ?length?
+

Generate a random salt string suitable for use with the md5crypt and +aprcrypt commands.

+
+
+

SALT

+

The salt passed to either of the encryption schemes implemented here +is checked to see if it begins with the encryption scheme magic string +(either "$1$" for MD5-crypt or "$apr1$" for Apache crypt). If so, this +is removed. The remaining characters up to the next $ and up to a +maximum of 8 characters are then used as the salt. The salt text +should probably be restricted the set of ASCII alphanumeric characters +plus "./" (dot and forward-slash) - this is to preserve maximum +compatability with the unix password file format.

+

If a password is being generated rather than checked from a password +file then the salt command may be used to generate a random salt.

+
+

EXAMPLES

+
+% md5crypt::md5crypt password 01234567
+$1$01234567$b5lh2mHyD2PdJjFfALlEz1
+
+
+% md5crypt::aprcrypt password 01234567
+$apr1$01234567$IXBaQywhAhc0d75ZbaSDp/
+
+
+% md5crypt::md5crypt password [md5crypt::salt]
+$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md5crypt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/mime/mime.html Index: embedded/www/tcllib/files/modules/mime/mime.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/mime/mime.html @@ -0,0 +1,371 @@ + + +mime - Mime + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

mime(n) 1.5.6 tcllib "Mime"

+

Name

+

mime - Manipulation of MIME body parts

+
+ + +

Description

+

The mime library package provides the commands to create and +manipulate MIME body parts.

+
+
::mime::initialize ?-canonical type/subtype ?-param {key value}...? ?-encoding value? ?-header {key value}...?? (-file name | -string value | -parts {token1 ... tokenN})
+

This command creates a MIME part and returns a token representing it.

+
    +

  • If the -canonical option is present, then the body is in +canonical (raw) form and is found by consulting either the +-file, -string, or -parts option.

    +

    In addition, both the -param and -header options may +occur zero or more times to specify Content-Type parameters +(e.g., charset) and header keyword/values (e.g., +Content-Disposition), respectively.

    +

    Also, -encoding, if present, specifies the +Content-Transfer-Encoding when copying the body.

    • +

  • If the -canonical option is not present, then the MIME part +contained in either the -file or the -string option +is parsed, dynamically generating subordinates as appropriate.

    • +
+
::mime::finalize token ?-subordinates all | dynamic | none?
+

This command destroys the MIME part represented by token. It +returns an empty string.

+

If the -subordinates option is present, it specifies which +subordinates should also be destroyed. The default value is +dynamic, destroying all subordinates which were created by +::mime::initialize together with the containing body part.

+
::mime::getproperty token ?property | -names?
+

This command returns a string or a list of strings containing the +properties of a MIME part. If the command is invoked with the name of +a specific property, then the corresponding value is returned; +instead, if -names is specified, a list of all properties is +returned; otherwise, a serialized array of properties and values is +returned.

+

The possible properties are:

+
+
content
+

The type/subtype describing the content

+
encoding
+

The "Content-Transfer-Encoding"

+
params
+

A list of "Content-Type" parameters

+
parts
+

A list of tokens for the part's subordinates. This property is +present only if the MIME part has subordinates.

+
size
+

The approximate size of the content (unencoded)

+
+
::mime::getheader token ?key | -names?
+

This command returns the header of a MIME part, as a list of strings.

+

A header consists of zero or more key/value pairs. Each value is a +list containing one or more strings.

+

If this command is invoked with the name of a specific key, then +a list containing the corresponding value(s) is returned; instead, if +-names is specified, a list of all keys is returned; otherwise, a +serialized array of keys and values is returned. Note that when a key +is specified (e.g., "Subject"), the list returned usually contains +exactly one string; however, some keys (e.g., "Received") often occur +more than once in the header, accordingly the list returned usually +contains more than one string.

+
::mime::setheader token key value ?-mode write | append | delete?
+

This command writes, appends to, or deletes the value associated +with a key in the header. It returns a list of strings +containing the previous value associated with the key.

+

The value for -mode is one of:

+
+
write
+

The key/value is either created or overwritten (the default).

+
append
+

A new value is appended for the key (creating it as necessary).

+
delete
+

All values associated with the key are removed (the value +parameter is ignored).

+
+
::mime::getbody token ?-decode? ?-command callback ?-blocksize octets??
+

This command returns a string containing the body of the leaf MIME +part represented by token in canonical form.

+

If the -command option is present, then it is repeatedly +invoked with a fragment of the body as this:

+
+  uplevel #0 $callback [list "data" $fragment]
+
+

(The -blocksize option, if present, specifies the maximum +size of each fragment passed to the callback.)

+

When the end of the body is reached, the callback is invoked as:

+
+    uplevel #0 $callback "end"
+
+

Alternatively, if an error occurs, the callback is invoked as:

+
+    uplevel #0 $callback [list "error" reason]
+
+

Regardless, the return value of the final invocation of the callback +is propagated upwards by ::mime::getbody.

+

If the -command option is absent, then the return value of +::mime::getbody is a string containing the MIME part's entire +body.

+

If the option -decode is absent the return value computed +above is returned as is. This means that it will be in the charset +specified for the token and not the usual utf-8. +If the option -decode is present however the command will use +the charset information associated with the token to convert the +string from its encoding into utf-8 before returning it.

+
::mime::copymessage token channel
+

This command copies the MIME represented by token part to the +specified channel. The command operates synchronously, and uses +fileevent to allow asynchronous operations to proceed +independently. It returns an empty string.

+
::mime::buildmessage token
+

This command returns the MIME part represented by token as a +string. It is similar to ::mime::copymessage, only it returns +the data as a return string instead of writing to a channel.

+
::mime::parseaddress string
+

This command takes a string containing one or more 822-style address +specifications and returns a list of serialized arrays, one element +for each address specified in the argument. If the string contains +more than one address they will be separated by commas.

+

Each serialized array contains the properties below. Note that one or +more of these properties may be empty.

+
+
address
+

local@domain

+
comment
+

822-style comment

+
domain
+

the domain part (rhs)

+
error
+

non-empty on a parse error

+
group
+

this address begins a group

+
friendly
+

user-friendly rendering

+
local
+

the local part (lhs)

+
memberP
+

this address belongs to a group

+
phrase
+

the phrase part

+
proper
+

822-style address specification

+
route
+

822-style route specification (obsolete)

+
+
::mime::parsedatetime (string | -now) property
+

This command takes a string containing an 822-style date-time +specification and returns the specified property as a serialized +array.

+

The list of properties and their ranges are:

+
+
hour
+

0 .. 23

+
lmonth
+

January, February, ..., December

+
lweekday
+

Sunday, Monday, ... Saturday

+
mday
+

1 .. 31

+
min
+

0 .. 59

+
mon
+

1 .. 12

+
month
+

Jan, Feb, ..., Dec

+
proper
+

822-style date-time specification

+
rclock
+

elapsed seconds between then and now

+
sec
+

0 .. 59

+
wday
+

0 .. 6 (Sun .. Mon)

+
weekday
+

Sun, Mon, ..., Sat

+
yday
+

1 .. 366

+
year
+

1900 ...

+
zone
+

-720 .. 720 (minutes east of GMT)

+
+
::mime::mapencoding encoding_name
+

This commansd maps tcl encodings onto the proper names for their MIME +charset type. This is only done for encodings whose charset types +were known. The remaining encodings return "" for now.

+
::mime::reversemapencoding charset_type
+

This command maps MIME charset types onto tcl encoding names. Those +that are unknown return "".

+
+
+

KNOWN BUGS

+
+
SourceForge Tcllib Bug #447037
+

This problem affects only people which are using Tcl and Mime on a +64-bit system. The currently recommended fix for this problem is to +upgrade to Tcl version 8.4. This version has extended 64 bit support +and the bug does not appear anymore.

+

The problem could have been generally solved by requiring the use of +Tcl 8.4 for this package. We decided against this solution as it would +force a large number of unaffected users to upgrade their Tcl +interpreter for no reason.

+

See http://sourceforge.net/tracker/?func=detail&aid=447037&group_id=12883&atid=112883 +for additional information.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category mime of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/mime/smtp.html Index: embedded/www/tcllib/files/modules/mime/smtp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/mime/smtp.html @@ -0,0 +1,275 @@ + + +smtp - smtp client + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

smtp(n) 1.4.5 tcllib "smtp client"

+

Name

+

smtp - Client-side tcl implementation of the smtp protocol

+
+ +

Synopsis

+
+
    +
  • package require Tcl
    • +
  • package require mime ?1.5.4?
    • +
  • package require smtp ?1.4.5?
    • +
+ +
+
+

Description

+

The smtp library package provides the client side of the +Simple Mail Transfer Protocol (SMTP) (1) (2).

+
+
::smtp::sendmessage token option...
+

This command sends the MIME part (see package mime) +represented by token to an SMTP server. options is a list +of options and their associated values. The recognized options are:

+
+
-servers
+

A list of SMTP servers. The default is localhost.

+
-ports
+

A list of SMTP ports. The default is 25.

+
-client
+

The name to use as our hostname when connecting to the server. By +default this is either localhost if one of the servers is localhost, +or is set to the string returned by info hostname.

+
-queue
+

Indicates that the SMTP server should be asked to queue the message +for later processing. A boolean value.

+
-atleastone
+

Indicates that the SMTP server must find at least one recipient +acceptable for the message to be sent. A boolean value.

+
-originator
+

A string containing an 822-style address specification. If present the +header isn't examined for an originator address.

+
-recipients
+

A string containing one or more 822-style address specifications. If +present the header isn't examined for recipient addresses). If the +string contains more than one address they will be separated by +commas.

+
-header
+

A list containing two elements, an smtp header and its associated +value (the -header option may occur zero or more times).

+
-usetls
+

This package supports the RFC 3207 TLS extension (3) by default provided the +tls package is available. You can turn this off with this boolean option.

+
-tlspolicy
+

This option lets you specify a command to be called if an error occurs +during TLS setup. The command is called with the SMTP code and diagnostic +message appended. The command should return 'secure' or 'insecure' where +insecure will cause the package to continue on the unencrypted channel. +Returning 'secure' will cause the socket to be closed and the next server +in the -servers list to be tried.

+
-username
+
+
-password
+

If your SMTP server requires authentication (RFC 2554 (4)) before +accepting mail you can use -username and -password +to provide your authentication details to the server. Currently this +package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication +methods. The most secure method will be tried first and each method +tried in turn until we are either authorized or we run out of +methods. Note that if the server permits a TLS connection, then the +authorization will occur after we begin using the secure channel.

+

Please also read the section on Authentication, it details +the necessary prequisites, i.e. packages needed to support these +options and authentication.

+
+

If the -originator option is not present, the originator +address is taken from From (or Resent-From); +similarly, if the -recipients option is not present, +recipient addresses are taken from To, cc, and +Bcc (or Resent-To, and so on). Note that the header +key/values supplied by the -header option (not those present +in the MIME part) are consulted. Regardless, header key/values are +added to the outgoing message as necessary to ensure that a valid +822-style message is sent.

+

The command returns a list indicating which recipients were +unacceptable to the SMTP server. Each element of the list is another +list, containing the address, an SMTP error code, and a textual +diagnostic. Depending on the -atleastone option and the +intended recipients, a non-empty list may still indicate that the +message was accepted by the server.

+
+
+

Authentication

+

Beware. SMTP authentication uses SASL. I.e. if the user +has to authenticate a connection, i.e. use the options -user +and -password (see above) it is necessary to have the +sasl package available so that smtp can load it.

+

This is a soft dependency because not everybody requires authentication, +and sasl depends on a lot of the cryptographic (secure) hashes, +i.e. all of md5, otp, md4, sha1, +and ripemd160.

+
+

EXAMPLE

+
+proc send_simple_message {recipient email_server subject body} {
+    package require smtp
+    package require mime
+    set token [mime::initialize -canonical text/plain \\
+	-string $body]
+    mime::setheader $token Subject $subject
+    smtp::sendmessage $token \\
+	-recipients $recipient -servers $email_server
+    mime::finalize $token
+}
+send_simple_message someone@somewhere.com localhost \\
+    "This is the subject." "This is the message."
+
+
+

REFERENCES

+
    +

  1. Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982. + (http://www.rfc-editor.org/rfc/rfc821.txt)

    2. +

  2. J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001. + (http://www.rfc-editor.org/rfc/rfc2821.txt)

    3. +

  3. P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport + Layer Security", RFC 3207, February 2002. + (http://www.rfc-editor.org/rfc/rfc3207.txt)

    4. +

  4. J. Myers, "SMTP Service Extension for Authentication", + RFC 2554, March 1999. + (http://www.rfc-editor.org/rfc/rfc2554.txt)

    5. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category smtp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/multiplexer/multiplexer.html Index: embedded/www/tcllib/files/modules/multiplexer/multiplexer.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/multiplexer/multiplexer.html @@ -0,0 +1,232 @@ + + +multiplexer - One-to-many communication with sockets. + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

multiplexer(n) 0.2 tcllib "One-to-many communication with sockets."

+

Name

+

multiplexer - One-to-many communication with sockets.

+
+ + +

Description

+

The multiplexer package provides a generic system for one-to-many +communication utilizing sockets. For example, think of a chat system +where one user sends a message which is then broadcast to all the +other connected users.

+

It is possible to have different multiplexers running concurrently.

+
+
::multiplexer::create
+

The create command creates a new multiplexer 'instance'. For +example:

+
set mp [::multiplexer::create]
+

This instance can then be manipulated like so:

+
${mp}::Init 35100
+
+
${multiplexer_instance}::Init port
+

This starts the multiplexer listening on the specified port.

+
${multiplexer_instance}::Config key value
+

Use Config to configure the multiplexer instance. Configuration +options currently include:

+
+
sendtoorigin
+

A boolean flag. If true, the sender will receive a copy of the +sent message. Defaults to false.

+
debuglevel
+

Sets the debug level to use for the multiplexer instance, according to +those specified by the logger package (debug, info, notice, +warn, error, critical).

+
+
${multiplexer_instance}::AddFilter cmdprefix
+

Command to add a filter for data that passes through the multiplexer +instance. +The registered cmdprefix is called when data arrives at a +multiplexer instance. If there is more than one filter command +registered at the instance they will be called in the order of +registristation, and each filter will get the result of the preceding +filter as its argument. The first filter gets the incoming data as its +argument. The result returned by the last filter is the data which +will be broadcast to all clients of the multiplexer instance. +The command prefix is called as

+
+
cmdprefix data chan clientaddress clientport
+

Takes the incoming data, modifies it, and returns that as its +result. The last three arguments contain information about the client +which sent the data to filter: The channel connecting us to the +client, its ip-address, and its ip-port.

+
+
${multiplexer_instance}::AddAccessFilter cmdprefix
+

Command to add an access filter. +The registered cmdprefix is called when a new client socket +tries to connect to the multixer instance. If there is more than one +access filter command registered at the instance they will be called +in the order of registristation. If any of the called commands returns +-1 the access to the multiplexer instance is denied and the +client channel is closed immediately. Any other result grants the +client access to the multiplexer instance. +The command prefix is called as

+
+
cmdprefix chan clientaddress clientport
+

The arguments contain information about the client which tries to +connected to the instance: The channel connecting us to the client, +its ip-address, and its ip-port.

+
+
${multiplexer_instance}::AddExitFilter cmdprefix
+

Adds filter to be run when client socket generates an EOF condition. +The registered cmdprefix is called when a client socket of the +multixer signals EOF. If there is more than one exit filter command +registered at the instance they will be called in the order of +registristation. Errors thrown by an exit filter are ignored, but +logged. Any result returned by an exit filter is ignored. +The command prefix is called as

+
+
cmdprefix chan clientaddress clientport
+

The arguments contain information about the client which signaled the +EOF: The channel connecting us to the client, its ip-address, and its +ip-port.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category multiplexer of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/namespacex/namespacex.html Index: embedded/www/tcllib/files/modules/namespacex/namespacex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/namespacex/namespacex.html @@ -0,0 +1,191 @@ + + +namespacex - Namespace utility commands + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

namespacex(n) 0.1 tcllib "Namespace utility commands"

+

Name

+

namespacex - Namespace utility commands

+
+ + +

Description

+

This package provides a number of utility commands for working with +namespaces.

+
+

API

+
+
::namespacex hook add ?namespace? cmdprefix
+
+
::namespacex hook proc ?namespace? arguments body
+
+
::namespacex hook on ?namespace? guardcmdprefix actioncmdprefix
+
+
::namespacex hook next arg...
+
+
::namespacex info allchildren namespace
+

This command returns a list containing the names of all child +namespaces in the specified namespace and its children. The +names are all fully qualified.

+
::namespacex info allvars namespace
+

This command returns a list containing the names of all variables in +the specified namespace and its children. The names are all +relative to namespace, and not fully qualified.

+
::namespacex info vars namespace ?pattern?
+

This command returns a list containing the names of all variables in +the specified namespace.

+
::namespacex state get namespace
+

This command returns a dictionary holding the names and values of all +variables in the specified namespace and its child namespaces.

+

Note that the names are all relative to namespace, +and not fully qualified.

+
::namespacex state set namespace dict
+

This command takes a dictionary holding the names and values for a set +of variables and replaces the current state of the specified +namespace and its child namespaces with this state. +The result of the command is the empty string.

+
::namespacex state drop namespace
+

This command unsets all variables in the specified namespace and +its child namespaces. +The result of the command is the empty string.

+
+
+ + +
ADDED embedded/www/tcllib/files/modules/ncgi/ncgi.html Index: embedded/www/tcllib/files/modules/ncgi/ncgi.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ncgi/ncgi.html @@ -0,0 +1,374 @@ + +ncgi - CGI Support + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ncgi(n) 1.4.1 tcllib "CGI Support"

+

Name

+

ncgi - Procedures to manipulate CGI values.

+
+ + +

Description

+

The ncgi package provides commands that manipulate CGI +values. These are values that come from Web forms and are processed +either by CGI scripts or web pages with embedded Tcl code. Use the +ncgi package to query these values, set and get cookies, and +encode and decode www-url-encoded values.

+

In the simplest case, a CGI script first calls ::ncgi::parse and +then calls ::ncgi::value to get different form values. If a CGI +value is repeated, you should use ::ncgi::valueList to get back +the complete list of values.

+

An alternative to ::ncgi::parse is ::ncgi::input, which +has semantics similar to Don Libes' cgi_input procedure. +::ncgi::input restricts repeated CGI values to have names that +end with "List". In this case, ::ncgi::value will return the +complete list of values, and ::ncgi::input will raise errors if +it find repeated form elements without the right name.

+

The ::ncgi::reset procedure can be used in test suites and Web +servers to initialize the source of the CGI values. Otherwise the +values are read in from the CGI environment.

+

The complete set of procedures is described below.

+
+
::ncgi::cookie cookie
+

Return a list of values for cookie, if any. It is possible that +more than one cookie with the same name can be present, so this +procedure returns a list.

+
::ncgi::decode str
+

Decode strings in www-url-encoding, which represents special +characters with a %xx sequence, where xx is the character code in hex.

+
::ncgi::empty name
+

Returns 1 if the CGI variable name is not present or has the +empty string as its value.

+
::ncgi::exists name
+

The return value is a boolean. It returns 0 if the CGI +variable name is not present, and 1 otherwise.

+
::ncgi::encode string
+

Encode string into www-url-encoded format.

+
::ncgi::header ?type? args
+

Output the CGI header to standard output. This emits a Content-Type: +header and additional headers based on args, which is a list of +header names and header values. The type defaults to +"text/html".

+
::ncgi::import cginame ?tclname?
+

This creates a variable in the current scope with the value of the CGI +variable cginame. The name of the variable is tclname, or +cginame if tclname is empty (default).

+
::ncgi::importAll args
+

This imports several CGI variables as Tcl variables. If args is +empty, then every CGI value is imported. Otherwise each CGI variable +listed in args is imported.

+
::ncgi::importFile cmd cginame ?filename?
+

This provides information about an uploaded file from a form input +field of type file with name cginame. cmd can be +one of -server -client, -type or +-data.

+
+
-client cginame
+

returns the filename as sent by the client.

+
-type cginame
+

returns the mime type of the uploaded file.

+
-data cginame
+

returns the contents of the file.

+
-server cginame filename
+

writes the file contents to a local temporary file (or filename +if supplied) and returns the name of the file. The caller is +responsible for deleting this file after use.

+
+
::ncgi::input ?fakeinput? ?fakecookie?
+

This reads and decodes the CGI values from the environment. It +restricts repeated form values to have a trailing "List" in their +name. The CGI values are obtained later with the ::ncgi::value +procedure.

+
::ncgi::multipart type query
+

This procedure parses a multipart/form-data query. This is used +by ::ncgi::nvlist and not normally called directly. It returns +an alternating list of names and structured values. Each structure +value is in turn a list of two elements. The first element is +meta-data from the multipart/form-data structure. The second element +is the form value. If you use ::ncgi::value you just get the +form value. If you use ::ncgi::valueList you get the structured +value with meta data and the value.

+

The type is the whole Content-Type, including the parameters +like boundary. This returns a list of names and values that +describe the multipart data. The values are a nested list structure +that has some descriptive information first, and the actual form value +second. The descriptive information is list of header names and +values that describe the content.

+
::ncgi::nvlist
+

This returns all the query data as a name, value list. In the case of +multipart/form-data, the values are structured as described in +::ncgi::multipart.

+
::ncgi::names
+

This returns all names found in the query data, as a list. +::ncgi::multipart.

+
::ncgi::parse
+

This reads and decodes the CGI values from the environment. The CGI +values are obtained later with the ::ncgi::value procedure. IF +a CGI value is repeated, then you should use ::ncgi::valueList +to get the complete list of values.

+
::ncgi::parseMimeValue value
+

This decodes the Content-Type and other MIME headers that have the +form of "primary value; param=val; p2=v2" It returns a list, where the +first element is the primary value, and the second element is a list +of parameter names and values.

+
::ncgi::query
+

This returns the raw query data.

+
::ncgi::redirect url
+

Generate a response that causes a 302 redirect by the Web server. The +url is the new URL that is the target of the redirect. The URL +will be qualified with the current server and current directory, if +necessary, to convert it into a full URL.

+
::ncgi::reset query type
+

Set the query data and Content-Type for the current CGI session. This +is used by the test suite and by Web servers to initialize the ncgi +module so it does not try to read standard input or use environment +variables to get its data. If neither query or type are +specified, then the ncgi module will look in the standard +CGI environment for its data.

+
::ncgi::setCookie args
+

Set a cookie value that will be returned as part of the reply. This +must be done before ::ncgi::header or ::ncgi::redirect is +called in order for the cookie to be returned properly. The +args are a set of flags and values:

+
+
-name name
+
+
-value value
+
+
-expires date
+
+
-path path restriction
+
+
-domain domain restriction
+
+
+
::ncgi::setDefaultValue key defvalue
+

Set a CGI value if it does not already exists. This affects future +calls to ::ncgi::value (but not future calls to +::ncgi::nvlist). If the CGI value already is present, then this +procedure has no side effects.

+
::ncgi::setDefaultValueList key defvaluelist
+

Like ::ncgi::setDefaultValue except that the value already has +list structure to represent multiple checkboxes or a multi-selection.

+
::ncgi::setValue key value
+

Set a CGI value, overriding whatever was present in the CGI +environment already. This affects future calls to ::ncgi::value +(but not future calls to ::ncgi::nvlist).

+
::ncgi::setValueList key valuelist
+

Like ::ncgi::setValue except that the value already has list +structure to represent multiple checkboxes or a multi-selection.

+
::ncgi::type
+

Returns the Content-Type of the current CGI values.

+
::ncgi::urlStub ?url?
+

Returns the current URL, but without the protocol, server, and port. +If url is specified, then it defines the URL for the current +session. That value will be returned by future calls to +::ncgi::urlStub

+
::ncgi::value key ?default?
+

Return the CGI value identified by key. If the CGI value is not +present, then the default value is returned instead. This value +defaults to the empty string.

+

If the form value key is repeated, then there are two cases: if +::ncgi::parse was called, then ::ncgi::value only returns +the first value associated with key. If ::ncgi::input was +called, then ::ncgi::value returns a Tcl list value and +key must end in "List" (e.g., "skuList"). In the case of +multipart/form-data, this procedure just returns the value of the form +element. If you want the meta-data associated with each form value, +then use ::ncgi::valueList.

+
::ncgi::valueList key ?default?
+

Like ::ncgi::value, but this always returns a list of values +(even if there is only one value). In the case of +multipart/form-data, this procedure returns a list of two elements. +The first element is meta-data in the form of a parameter, value list. +The second element is the form value.

+
+
+

EXAMPLES

+

Uploading a file

+
+HTML:
+<html>
+<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
+Path: <input type="file" name="filedata"><br>
+Name: <input type="text" name="filedesc"><br>
+<input type="submit">
+</form>
+</html>
+TCL: upload.cgi
+#!/usr/local/bin/tclsh
+::ncgi::parse
+set filedata [::ncgi::value filedata]
+set filedesc [::ncgi::value filedesc]
+puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
+set filename /www/images/$filedesc
+set fh [open $filename w]
+puts -nonewline $fh $filedata
+close $fh
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ncgi of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/nmea/nmea.html Index: embedded/www/tcllib/files/modules/nmea/nmea.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nmea/nmea.html @@ -0,0 +1,234 @@ + +nmea - NMEA protocol implementation + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nmea(n) 1.0.0 tcllib "NMEA protocol implementation"

+

Name

+

nmea - Process NMEA data

+
+ + +

Description

+

This package provides a standard interface for writing software which recieves +NMEA standard input data. It allows for reading data from COM ports, files, +or programmatic input. It also supports the checksumming and logging of incoming data. +After parsing, input is dispatched to user defined handler commands for processing. +To define a handler, see the event command. There are no GPS specific functions +in this package. NMEA data consists of a sentence type, followed by a list of data.

+
+

COMMANDS

+
+
::nmea::input sentence
+

Processes and dispatches the supplied sentence. If sentence contains no commas it is treated as a Tcl list, otherwise it must be standard comma delimited NMEA data, with an optional checksum and leading $.

+
+nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39}
+nmea::input [list GPGSA A 3 04 05  09 12 "" "" 24 "" "" ""  2.5 1.3 2.1]
+
+
+
::nmea::open_port port ?speed?
+

Open the specified COM port and read NMEA sentences when available. Port speed is set to +4800bps by default or to speed.

+
::nmea::close_port
+

Close the com port connection if one is open.

+
::nmea::configure_port settings
+

Changes the current port settings. settings has the same format as fconfigure -mode.

+
::nmea::open_file file ?rate?
+

Open file file and read NMEA sentences, one per line, at the rate specified by ?rate? in milliseconds. +The file format may omit the leading $ and/or the checksum. If rate is <= 0 (the default) then lines +will only be processed when a call to do_line is made.

+
::nmea::close_file
+

Close the open file if one exists.

+
::nmea::do_line
+

If there is a currently open file, this command will read and process a single line from it. +Returns the number of lines read.

+
::nmea::rate
+

Sets the rate at which lines are processed from the open file, in milliseconds. The rate remains +consistant across files, there does not need to be a file currently open to use this command. +Set to 0 to disable automatic line processing.

+
::nmea::log ?file?
+

Starts or stops input logging. If a file name is specified then all NMEA data recieved on +the open port will be logged to the ?file? in append mode. If file is an empty string then +any logging will be stopped. If no file is specified then returns a boolean value indicating +if logging is currently enabled. Data written to the port by write, + data read from files, or input made using input, is not logged.

+
::nmea::checksum data
+

Returns the checksum of the supplied data.

+
::nmea::write sentence data
+

If there is a currently open port, this command will write the specified sentence and data to the port +in proper NMEA checksummed format.

+
::nmea::event setence ?command?
+

Registers a handler proc for a given NMEA sentence. There may be at most one handler per +sentence, any existing handler is replaced. +If no command is specified, returns the name of the current handler for the given setence +or an empty string if none exists. In addition to the incoming sentences there are 2 builtin types, +EOF and DEFAULT. The handler for the DEFAULT setence is invoked if there is not a specific handler +for that sentence. The EOF handler is invoked when End Of File is reached on the open file or port.

+

The handler procedures, with the exception of the builtin types,must take exactly one argument, +which is a list of the data values. +The DEFAULT handler should have two arguments, the sentence type and the data values. +The EOF handler has no arguments.

+
+nmea::event gpgsa parse_sat_detail
+nmea::event default handle_unknown
+proc parse_sat_detail {data} {
+    puts [lindex $data 1]
+}
+proc handle_unknown {name data} {
+    puts "unknown data type $name"
+}
+
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nmea of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_auto.html Index: embedded/www/tcllib/files/modules/nns/nns_auto.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_auto.html @@ -0,0 +1,224 @@ + +nameserv::auto - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nameserv::auto(n) 0.3 tcllib "Name service facility"

+

Name

+

nameserv::auto - Name service facility, Client Extension

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require nameserv::auto ?0.3?
    • +
  • package require nameserv
    • +
+
+
+

Description

+

Please read the document Name service facility, introduction +first.

+

This package provides the exact same API as is provided by +package nameserv, i.e the regular name service client. It +differs from the former by taking measures to ensure that longer-lived +data, i.e. bound names, continuous and unfulfilled async searches, +survive the loss of the connection to the name server as much as is +possible.

+

This means that the bound names and continuous and unfulfilled async +searches are remembered client-side and automatically re-entered into +the server when the connection comes back after its loss. For bound +names there is one important limitation to such restoration: It is +possible that a name of this client was bound by a different client +while the connection was gone. Such names are fully lost, and the best +the package can and will do is to inform the user of this.

+
+

API

+

The user-visible API is mainly identical the API of nameserv +and is therefore not described here. Please read the documentation of +nameserv.

+

The differences are explained in the sections OPTIONS and +EVENTS.

+
+

OPTIONS

+

This package supports all the option of package nameserv, +and one more. The additional option allows the user to specifies the +time interval between attempts to restore a lost connection.

+
+
-delay milliseconds
+

The value of this option is an integer value > 0 which specifies the +interval to wait between attempts to restore a lost connection, in +milliseconds. The default value is 1000, i.e. one second.

+
+
+

EVENTS

+

This package generates all of the events of package nameserv, +and two more. Both events are generated for the tag nameserv.

+
+
lost-name
+

This event is generated when a bound name is truly lost, i.e. could +not be restored after the temporary loss of the connection to the name +server. It indicates that a different client took ownership of the +name while this client was out of contact.

+

The detail information of the event will be a Tcl dictionary +containing two keys, name, and data. Their values hold +all the information about the lost name.

+
re-connection
+

This event is generated when the connection to the server is +restored. The remembered data has been restored when the event is +posted.

+

The event has no detail information.

+
+
+

DESIGN

+

The package is implemented on top of the regular nameservice client, +i.e. package nameserv. It detects the loss of the +connection by listening for lost-connection events, on the tag +nameserv.

+

It reacts to such events by starting a periodic timer and trying to +reconnect to the server whenver this timer triggers. On success the +timer is canceled, a re-connection event generated, and the +package proceeds to re-enter the remembered bound names and continous +searches.

+

Another loss of the connection, be it during or after re-entering the +remembered information simply restarts the timer and subsequent +reconnection attempts.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_client.html Index: embedded/www/tcllib/files/modules/nns/nns_client.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_client.html @@ -0,0 +1,399 @@ + +nameserv - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nameserv(n) 0.4.2 tcllib "Name service facility"

+

Name

+

nameserv - Name service facility, Client

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

This package provides a client for the name service facility +implemented by the package nameserv::server.

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+
+

API

+

The package exports eight commands, as specified below:

+
+
::nameserv::bind name data
+

The caller of this command registers the given name as its name +in the configured name service, and additionally associates a piece of +data with it. The service does nothing with this information +beyond storing it and delivering it as part of search results. The +meaning is entirely up to the applications using the name service.

+

A generally useful choice would for example be an identifier for a +communication endpoint managed by the package comm. Anybody +retrieving the name becomes immediately able to talk to this endpoint, +i.e. the registering application.

+

Of further importance is that a caller can register itself under more +than one name, and each name can have its own piece of data.

+

Note that the name service, and thwerefore this command, will throw an +error if the chosen name is already registered.

+
::nameserv::release
+

Invoking this command releases all names (and their data) registered +by all previous calls to ::nameserv::bind of this client. Note +that the name service will run this command implicitly when it loses +the connection to this client.

+
::nameserv::search ?-async|-continuous? ?pattern?
+

This command searches the name service for all registered names +matching the specified glob-pattern. If not specified the +pattern defaults to *, matching everything. The result of the +command is a dictionary mapping the matching names to the data +associated with them at bind-time.

+

If either option -async or -continuous were +specified the result of this command changes and becomes the Tcl +command of an object holding the actual result. +These two options are supported if and only if the service the client +is connected to supports the protocol feature +Search/Continuous.

+

For -async the result object is asynchronously filled with +the entries matching the pattern at the time of the search and then +not modified any more. +The option -continuous extends this behaviour by additionally +continuously monitoring the service for the addition and removal of +entries which match the pattern, and updating the object's contents +appropriately.

+

Note that the caller is responsible for configuring the object +with a callback for proper notification when the current result (or +further changes) arrive.

+

For more information about this object see section +ASYNCHRONOUS AND CONTINUOUS SEARCHES.

+
::nameserv::protocol
+

This command returns the highest version of the name service protocol +supported by the package.

+
::nameserv::server_protocol
+

This command returns the highest version of the name service protocol +supported by the name service the client is currently connected to.

+
::nameserv::server_features
+

This command returns a list containing the names of the features of +the name service protocol which are supported by the name service the +client is currently connected to.

+
::nameserv::cget -option
+

This command returns the currently configured value for the specified +-option. The list of supported options and their meaning can +be found in section OPTIONS.

+
::nameserv::configure
+

In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section OPTIONS.

+
::nameserv::configure -option
+

In this form the command is an alias for +"::nameserv::cget -option]". +The list of supported options and their meaning can be found in +section OPTIONS.

+
::nameserv::configure -option value...
+

In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section OPTIONS.

+

This form can be used only as long as the client has not contacted the +name service yet. After contact has been made reconfiguration is not +possible anymore. This means that this form of the command is for the +initalization of the client before it use. +The command forcing a contact with the name service are

+
+
bind
+
+
release
+
+
search
+
+
server_protocol
+
+
server_features
+
+
+
+
+

CONNECTION HANDLING

+

The client automatically connects to the service when one of the +commands below is run for the first time, or whenever one of the +commands is run after the connection was lost, when it was lost.

+
+
bind
+
+
release
+
+
search
+
+
server_protocol
+
+
server_features
+
+
+

Since version 0.2 of the client it will generate an event when the +connection is lost, allowing higher layers to perform additional +actions. This is done via the support package uevent. This +and all other name service related packages hereby reserve the +uevent-tag nameserv. All their events will be posted to that +tag.

+
+

EVENTS

+

This package generates only one event, lost-connection. The +detail information provided to that event is a Tcl dictionary. The +only key contained in the dictionnary is reason, and its value +will be a string describing why the connection was lost. +This string is supplied by the underlying communication package, +i.e. comm.

+
+

OPTIONS

+

The options supported by the client are for the specification of which +name service to contact, i.e. of the location of the name service. +They are:

+
+
-host name|ipaddress
+

This option specifies the host name service to contact is running on, +either by name, or by ipaddress. The initial default is +localhost, i.e. it is expected to contact a name service +running on the same host as the application using this package.

+
-port number
+

This option specifies the port the name service to contact is +listening on. It has to be a positive integer number (> 0) not greater +than 65536 (unsigned short). The initial default is the number +returned by the command ::nameserv::common::port, as provided by +the package ::nameserv::common.

+
+
+

ASYNCHRONOUS AND CONTINUOUS SEARCHES

+

Asynchronous and continuous searches are invoked by using either +option -async or -continuous as argument to the +command ::nameserv::search.

+

Note that these two options are supported if and only if the +service the client is connected to supports the protocol feature +Search/Continuous. The service provided by the package +::nameserv::server does this since version 0.3.

+

For such searches the result of the search command is the Tcl command +of an object holding the actual result. The API provided by these +objects is:

+
+
Options:
+
+
-command command_prefix
+

This option has to be set if a user of the result object wishes to get +asynchronous notifications when the search result or changes to it +arrive.

+

Note that while it is possible to poll for the arrival of the +initial search result via the method filled, and for +subsequent changes by comparing the output of method getall +against a saved copy, this is not the recommended behaviour. Setting +the -command callback and processing the notifications as +they arrive is much more efficient.

+

The command_prefix is called with two arguments, the type of +change, and the data of the change. The type is either add or +remove, indicating new data, or deleted data, respectively. +The data of the change is always a dictionary listing the +added/removed names and their associated data.

+

The first change reported for a search is always the set of matching +entries at the time of the search.

+
+
Methods:
+
+
$result destroy
+

Destroys the object and cancels any continuous monitoring of the +service the object may have had active.

+
$result filled
+

The result is a boolean value indicating whether the search result has +already arrived (True), or not (False).

+
$result get name
+

Returns the data associated with the given name at +bind-time.

+
$result names
+

Returns a list containing all names known to the object at the time of +the invokation.

+
$result size
+

Returns an integer value specifying the size of the result at the time +of the invokation.

+
$result getall ?pattern?
+

Returns a dictionary containing the search result at the time of the +invokation, mapping the matching names to the data associated with +them at bind-time.

+
+
+
+

HISTORY

+
+
0.3.1
+

Fixed SF Bug 1954771.

+
0.3
+

Extended the client with the ability to perform asynchronous and +continuous searches.

+
0.2
+

Extended the client with the ability to generate events when it loses +its connection to the name service. Based on package uevent.

+
0.1
+

Initial implementation of the client.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_common.html Index: embedded/www/tcllib/files/modules/nns/nns_common.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_common.html @@ -0,0 +1,175 @@ + +nameserv::common - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nameserv::common(n) 0.1 tcllib "Name service facility"

+

Name

+

nameserv::common - Name service facility, shared definitions

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8
    • +
  • package require nameserv::common ?0.1?
    • +
+ +
+
+

Description

+

Please read Name service facility, introduction first.

+

This package is internal and of no interest to users. It provides the +commands of the name service facility which are shared by the client +and server implemented by the packages nameserv::server and +nameserv (the client).

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+
+

API

+

The package exports a single command, as specified below:

+
+
::nameserv::common::port
+

The result returned by the command is the id of the default TCP/IP +port a nameservice server will listen on, and a name service client +will try to connect to.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

nameserv::client(n), nameserv::server(n)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_intro.html Index: embedded/www/tcllib/files/modules/nns/nns_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_intro.html @@ -0,0 +1,213 @@ + + +nns_intro - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nns_intro(n) 1.0 tcllib "Name service facility"

+

Name

+

nns_intro - Name service facility, introduction

+
+ +

Description

+

nns (short for nano nameservice) is a facility built +for the package comm, adding a simple name service to it. +It is also built on top of comm, using it for the exchange +of messages between the client and server parts.

+

This name service facility has nothing to do with the Internet's +Domain Name System, otherwise known as DNS. If the +reader is looking for a package dealing with that please see either of +the packages dns and resolv, both found in Tcllib +too.

+

Tcllib provides 2 applications and 4 packages which are working +together and provide access to the facility at different levels.

+
+

Applications

+

The application nnsd provides a simple name server which can +be run by anybody anywhere on their system, as they see fit. +It is also an example on the use of the server-side package +nameserv::server.

+

Complementing this server is the nns client application. +A possible, but no very sensible use would be to enter name/port +bindings into a server from a shell script. Not sensible, as shell +scripts normally do not provide a comm-based service.

+

The only case for this to make some sense would be in a shell script +wrapped around a Tcl script FOO which is using comm, to register the +listening port used by FOO. +However even there it would much more sensible to extend FOO to use +the nameservice directly. And in regard on how to that nns +can be used as both example and template. +Beyond that it may also be useful to perform nameservice queries from +shell scripts.

+

The third application, nnslog is a stripped down form of the +nns client application. It is reduced to perform a continuous +search for all changes and logs all received events to stdout.

+

Both clients use the nameserv::auto package to automatically +hande the loss and restoration of the connection to the server.

+
+

Packages

+

The two main packages implementing the service are nameserv +and nameserv::server, i.e. client and server. The latter has +not much of an API, just enough to start, stop, and configure it. See +the application nnsd on how to use it.

+

The basic client, in package nameserv, provides the main API +to manipulate and query the service. An example of its use is the +application nns.

+

The second client package, nameserv::auto is API compatible +to the basic client, but provides the additional functionality that it +will automatically restore data like bound names when the connection +to the name service was lost and then reestablished. I.e. it +automatically detects the loss of the server and re-enters the data +when the server comes back.

+

The package nameserv::common is of no interest to users. It +is an internal package containing code and definitions common to the +packages nameserv and nameserv::server.

+

All packages use the uevent package for the reporting of +special circumstances via events, and reserve the uevent-tag +nameserv for their exclusive use. All their events will be +posted to that tag.

+
+

Internals

+

The document Name service facility, client/server protocol +specifies the protocol used by the packages nameserv and +nameserv::server to talk to each other. It is of no interest +to users of either the packages or applications.

+

Developers wishing to modify and/or extend or to just understand the +internals of the nameservice facility however are strongly advised to +read it.

+
+

Bugs, Ideas, Feedback

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +Please also report any ideas for enhancements you may have.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_protocol.html Index: embedded/www/tcllib/files/modules/nns/nns_protocol.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_protocol.html @@ -0,0 +1,267 @@ + +nameserv::protocol - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nameserv::protocol(n) 0.1 tcllib "Name service facility"

+

Name

+

nameserv::protocol - Name service facility, client/server protocol

+
+ + +

Description

+

The packages nameserv::server, nameserv, and +nameserv::common provide a simple unprotected name service +facility for use in small trusted environments.

+

Please read Name service facility, introduction first.

+

This document contains the specification of the network protocol which +is used by client and server to talk to each other, enabling +implementations of the same protocol in other languages.

+
+

Nano Name Service Protocol Version 1

+

This protocol defines the basic set of messages to be supported by a +name service, also called the Core feature.

+

Basic Layer

+

The basic communication between client and server is done using the +remote-execution protocol specified by the Tcl package comm. +The relevant document specifying its on-the-wire protocol can be found +in comm_wire.

+

All the scripts exchanged via this protocol are single commands in +list form and thus can be interpreted as plain messages instead of as +Tcl commands. The commands/messages specified in the next section are +the only commands understood by the server-side. Command and variable +substitutions are not allowed within the messages, i.e. arguments have +to be literal values.

+

The protocol is synchronous. I.e. for each message sent a response is +expected, and has to be generated. All messages are sent by the client. +The server does not sent messages, only responses to messages.

+
+

Message Layer

+
+
Bind name data
+

The client sends this message when it registers itself at the service +with a name and some associated data. The server has to +send an error response if the name is already in use. Otherwise +the response has to be an empty string.

+

The server has to accept multiple names for the same client.

+
Release
+

The client sends this message to unregister all names it is known +under at the service. The response has to be an empty string, always.

+
Search pattern
+

The client sends this message to search the service for names matching +the glob-pattern. The response has to be a dictionary containing +the matching names as keys, and mapping them to the data associated +with it at Bind-time.

+
ProtocolVersion
+

The client sends this message to query the service for the highest +version of the name service protocol it supports. The response has to +be a positive integer number.

+

Servers supporting only Nano Name Service Protocol Version 1 +have to return 1.

+
ProtocolFeatures
+

The client sends this message to query the service for the features of +the name service protocol it supports. The response has to be a +list containing feature names.

+

Servers supporting only Nano Name Service Protocol Version 1 +have to return {Core}.

+
+
+
+

Nano Name Service Protocol Extension: Continuous Search

+

This protocol defines an extended set of messages to be supported by a +name service, also called the Search/Continuous feature. This +feature defines additional messages between client and server, and is +otherwise identical to version 1 of the protocol. See the last section +for the details of our foundation.

+

A service supporting this feature has to put the feature name +Search/Continuous into the list of features returned by the +message ProtocolFeatures.

+

For this extension the protocol is asynchronous. No direct response is +expected for any of the messages in the extension. Furthermore the +server will start sending messages on its own, instead of only +responses to messages, and the client has to be able to handle these +notifications.

+
+
Search/Continuous/Start tag pattern
+

The client sends this message to start searching the service for names +matching the glob-pattern. +In contrast to the regular Search request this one asks the +server to continuously monitor the database for the addition and +removal of matching entries and to notify the client of all such +changes. The particular search is identified by the tag.

+

No direct response is expected, rather the clients expect to be +notified of changes via explicit Search/Continuous/Result +messages generated by the service.

+

It is further expected that the tag information is passed +unchanged to the Search/Continuous/Result messages. This +tagging of the results enables clients to start multiple searches and +distinguish between the different results.

+
Search/Continuous/Stop tag
+

The client sends this message to stop the continuous search identified +by the tag.

+
Search/Continuous/Change tag add|remove response
+

This message is sent by the service to clients with active continuous +searches to transfer found changes. The first such message for a new +continuous search has to contains the current set of matching entries.

+

To ensure this a service has to generate an add-message with +an empty response if there were no matching entries at the time.

+

The response has to be a dictionary containing the matching +names as keys, and mapping them to the data associated with it at +Bind-time. +The argument coming before the response tells the client whether the +names in the response were added or removed from the service.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_server.html Index: embedded/www/tcllib/files/modules/nns/nns_server.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nns/nns_server.html @@ -0,0 +1,250 @@ + +nameserv::server - Name service facility + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nameserv::server(n) 0.3.2 tcllib "Name service facility"

+

Name

+

nameserv::server - Name service facility, Server

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require nameserv::server ?0.3.2?
    • +
  • package require comm
    • +
  • package require interp
    • +
  • package require logger
    • +
+ +
+
+

Description

+

Please read Name service facility, introduction first.

+

This package provides an implementation of the serviver side of the +name service facility queried by the client provided by the package +nameserv. All information required by the server will be +held in memory. There is no persistent state.

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+

This server supports the Core protocol feature, and since +version 0.3 the Search/Continuous feature as well.

+
+

API

+

The package exports five commands, as specified below:

+
+
::nameserv::server::start
+

This command starts the server and causes it to listen on the +configured port. From now on clients are able to connect and make +requests. The result of the command is the empty string.

+

Note that any incoming requests will only be handled if the +application the server is part of does enter an event loop after this +command has been run.

+
::nameserv::server::stop
+

Invoking this command stops the server and releases all information it +had. Existing connections are shut down, and no new connections will +be accepted any longer. The result of the command is the empty string.

+
::nameserv::server::active?
+

This command returns a boolean value indicating the state of the +server. The result will be true if the server is active, +i.e. has been started, and false otherwise.

+
::nameserv::server::cget -option
+

This command returns the currently configured value for the specified +-option. The list of supported options and their meaning can +be found in section OPTIONS.

+
::nameserv::server::configure
+

In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section OPTIONS.

+
::nameserv::server::configure -option
+

In this form the command is an alias for +"::nameserv::server::cget -option]". +The list of supported options and their meaning can be found in +section OPTIONS.

+
::nameserv::server::configure -option value...
+

In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section OPTIONS.

+

This form can be used only if the server is not active, i.e. has not +been started yet, or has been stopped. While the server is active it +cannot be reconfigured.

+
+
+

OPTIONS

+

The options supported by the server are for the specification of the +TCP port to listen on, and whether to accept non-local connections or +not. +They are:

+
+
-localonly bool
+

This option specifies whether to accept only local connections +(-localonly 1) or remote connections as well (-localonly 0). The +default is to accept only local connections.

+
-port number
+

This option specifies the port the name service will listen on after +it has been started. It has to be a positive integer number (> 0) not +greater than 65536 (unsigned short). The initial default is the number +returned by the command ::nameserv::server::common::port, as +provided by the package ::nameserv::server::common.

+
+
+

HISTORY

+
+
0.3
+

Extended the server with the ability to perform asynchronous and +continuous searches.

+
0.2
+

Changed name of -local switch to -localonly.

+
0.1
+

Initial implementation of the server.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

nameserv::client(n), nameserv::common(n)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nntp/nntp.html Index: embedded/www/tcllib/files/modules/nntp/nntp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/nntp/nntp.html @@ -0,0 +1,403 @@ + + +nntp - Tcl NNTP Client Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

nntp(n) 1.5.1 tcllib "Tcl NNTP Client Library"

+

Name

+

nntp - Tcl client for the NNTP protocol

+
+ + +

Description

+

The package nntp provides a simple Tcl-only client library +for the NNTP protocol. It works by opening the standard NNTP socket +on the server, and then providing a Tcl API to access the NNTP +protocol commands. All server errors are returned as Tcl errors +(thrown) which must be caught with the Tcl catch command.

+
+

COMMANDS

+
+
::nntp::nntp ?host? ?port? ?nntpName?
+

The command opens a socket connection to the specified NNTP server and +creates a new nntp object with an associated global Tcl command whose +name is nntpName. This command may be used to access the various +NNTP protocol commands for the new connection. The default port +number is "119" and the default host is "news". These defaults +can be overridden with the environment variables NNTPPORT and +NNTPHOST respectively.

+

Some of the commands supported by this package are not part of the +nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt) and will +not be available (or implemented) on all nntp servers.

+

The access command nntpName has the following general form:

+
+
nntpName method ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+
nntpName article ?msgid?
+

Query the server for article msgid from the current group. The article +is returned as a valid tcl list which contains the headers, followed by +a blank line, and then followed by the body of the article. Each element +in the list is one line of the article.

+
nntpName authinfo ?user? ?pass?
+

Send authentication information (username and password) to the server.

+
nntpName body ?msgid?
+

Query the server for the body of the article msgid from the current +group. The body of the article is returned as a valid tcl list. Each element +in the list is one line of the body of the article.

+
nntpName configure
+
+
nntpName configure option
+
+
nntpName configure option value ...
+
+
nntpName cget option
+

Query and configure options of the nntp connection object. Currently +only one option is supported, -binary. When set articles are +retrieved as binary data instead of text. The only methods affected by +this are article and body.

+

One application of this option would be the download of articles +containing yEnc encoded images. Although encoded the data is still +mostly binary and retrieving it as text will corrupt the information.

+

See package yencode for both encoder and decoder of such data.

+
nntpName date
+

Query the server for the servers current date. The date is returned in the +format YYYYMMDDHHMMSS.

+
nntpName group ?group?
+

Optionally set the current group, and retrieve information about the +currently selected group. Returns the estimated number of articles in +the group followed by the number of the first article in the group, followed +by the last article in the group, followed by the name of the group.

+
nntpName head ?msgid?
+

Query the server for the headers of the article msgid from the current +group. The headers of the article are returned as a valid tcl list. Each element +in the list is one line of the headers of the article.

+
nntpName help
+

Retrieves a list of the commands that are supported by the news server that +is currently attached to.

+
nntpName last
+

Sets the current article pointer to point to the previous message (if there is +one) and returns the msgid of that message.

+
nntpName list
+

Returns a tcl list of valid newsgroups and associated information. Each +newsgroup is returned as an element in the tcl list with the following format:

+
+      group last first p
+
+

where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n').

+

The <first> and <last> fields will always be numeric. They may have +leading zeros. If the <last> field evaluates to less than the +<first> field, there are no articles currently on file in the +newsgroup.

+
nntpName listgroup ?group?
+

Query the server for a list of all the messages (message numbers) in the +group specified by the argument group or by the current group if +the group argument was not passed.

+
nntpName mode_reader
+

Query the server for its nntp 'MODE READER' response string.

+
nntpName newgroups since
+

Query the server for a list of all the new newsgroups created since the time +specified by the argument since. The argument since can be any +time string that is understood by clock scan. The tcl list of newsgroups +is returned in a similar form to the list of groups returned by the +nntpName list command. Each element of the list has the form:

+
+      group last first p
+
+

where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n').

+
nntpName newnews
+

Query the server for a list of new articles posted to the current group in the +last day.

+
nntpName newnews since
+

Query the server for a list of new articles posted to the current group since +the time specified by the argument since. The argument since can +be any time string that is understood by clock scan.

+
nntpName newnews group ?since?
+

Query the server for a list of new articles posted to the group specified by +the argument group since the time specified by the argument since +(or in the past day if no since argument is passed. The argument +since can be any time string that is understood by clock scan.

+
nntpName next
+

Sets the current article pointer to point to the next message (if there is +one) and returns the msgid of that message.

+
nntpName post article
+

Posts an article of the form specified in +RFC 1036 (http://www.rfc-editor.org/rfc/rfc1036.txt, successor +to RFC 850) to the current news group.

+
nntpName slave
+

Identifies a connection as being made from a slave nntp server. This might +be used to indicate that the connection is serving multiple people and should +be given priority. Actual use is entirely implementation dependent and may +vary from server to server.

+
nntpName stat ?msgid?
+

The stat command is similar to the article command except that no +text is returned. When selecting by message number within a group, +the stat command serves to set the current article pointer without +sending text. The returned acknowledgment response will contain the +message-id, which may be of some value. Using the stat command to +select by message-id is valid but of questionable value, since a +selection by message-id does NOT alter the "current article pointer"

+
nntpName quit
+

Gracefully close the connection after sending a NNTP QUIT command down +the socket.

+
nntpName xgtitle ?group_pattern?
+

Returns a tcl list where each element is of the form:

+
+newsgroup description
+
+

If a group_pattern is specified then only newsgroups that match +the pattern will have their name and description returned.

+
nntpName xhdr field ?range?
+

Returns the specified header field value for the current message or for a +list of messages from the current group. field is the title of a +field in the header such as from, subject, date, etc. If range is +not specified or is "" then the current message is queried. The command +returns a list of elements where each element has the form of:

+
+    msgid value
+
+

Where msgid is the number of the message and value is the value set for the +queried field. The range argument can be in any of the following forms:

+
+
""
+

The current message is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
nntpName xover ?range?
+

Returns header information for the current message or for a range of messages +from the current group. The information is returned in a tcl list +where each element is of the form:

+
+    msgid subject from date idstring bodysize headersize xref
+
+

If range is not specified or is "" then the current message is queried. +The range argument can be in any of the following forms:

+
+
""
+

The current message is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
nntpName xpat field range ?pattern_list?
+

Returns the specified header field value for a specified message or for a +list of messages from the current group where the messages match the +pattern(s) given in the pattern_list. field is the title of a +field in the header such as from, subject, date, etc. The information is +returned in a tcl list where each element is of the form:

+
+    msgid value
+
+

Where msgid is the number of the message and value is the value set for the +queried field. The range argument can be in any of the following forms:

+
+
msgid
+

The message specified by msgid is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
+
+

EXAMPLE

+

A bigger example for posting a single article.

+
+    package require nntp 
+    set n [nntp::nntp NNTP_SERVER] 
+    $n post "From: USER@DOMAIN.EXT (USER_FULL) 
+    Path: COMPUTERNAME!USERNAME 
+    Newsgroups: alt.test 
+    Subject: Tcl test post -ignore 
+    Message-ID: <[pid][clock seconds] 
+    @COMPUTERNAME> 
+    Date: [clock format [clock seconds] -format "%a, %d % 
+    b %y %H:%M:%S GMT" -gmt true] 
+    
+    Test message body" 
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nntp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ntp/ntp_time.html Index: embedded/www/tcllib/files/modules/ntp/ntp_time.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ntp/ntp_time.html @@ -0,0 +1,256 @@ + +ntp_time - Network Time Facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ntp_time(n) 1.2.1 tcllib "Network Time Facilities"

+

Name

+

ntp_time - Tcl Time Service Client

+
+ + +

Description

+

This package implements a client for the RFC 868 TIME protocol +(http://www.rfc-editor.org/rfc/rfc868.txt) and also a minimal +client for the RFC 2030 Simple Network Time Protocol +(http://www.rfc-editor.org/rfc/rfc2030.txt). +RFC 868 returns the time in seconds since 1 January 1900 +to either tcp or udp clients. RFC 2030 also gives this time but also +provides a fractional part which is not used in this client.

+
+

COMMANDS

+
+
::time::gettime ?options? timeserver ?port?
+

Get the time from timeserver. You may specify any of the options +listed for the configure command here. This command returns a +token which must then be used with the remaining commands in this +package. Once you have finished, you should use cleanup to +release all resources. The default port is 37.

+
::time::getsntp ?options? timeserver ?port?
+

Get the time from an SNTP server. This accepts exactly the same +arguments as ::time::gettime except that the default port is +123. The result is a token as per ::time::gettime and +should be handled in the same way.

+

Note that it is unlikely that any SNTP server will reply using tcp so +you will require the tcludp or the ceptcl +package. If a suitable package can be loaded then the udp protocol +will be used by default.

+
::time::configure ?options?
+

Called with no arguments this command returns all the current +configuration options and values. Otherwise it should be called with +pairs of option name and value.

+
+
-protocol number
+

Set the default network protocol. This defaults to udp if the tcludp + package is available. Otherwise it will use tcp.

+
-port number
+

Set the default port to use. RFC 868 uses port 37, RFC 2030 uses +port 123.

+
-timeout number
+

Set the default timeout value in milliseconds. The default is 10 seconds.

+
-command number
+

Set a command procedure to be run when a reply is received. The + procedure is called with the time token appended to the argument list.

+
-loglevel number
+

Set the logging level. The default is 'warning'.

+
+
::time::cget name
+

Get the current value for the named configuration option.

+
::time::unixtime token
+

Format the returned time for the unix epoch. RFC 868 time defines + time 0 as 1 Jan 1900, while unix time defines time 0 as 1 Jan + 1970. This command converts the reply to unix time.

+
::time::status token
+

Returns the status flag. For a successfully completed query this will be + ok. May be error or timeout or eof. + See also ::time::error

+
::time::error token
+

Returns the error message provided for requests whose status is error. + If there is no error message then an empty string is returned.

+
::time::reset token ?reason?
+

Reset or cancel the query optionally specfying the reason to record + for the error command.

+
::time::wait token
+

Wait for a query to complete and return the status upon completion.

+
::time::cleanup token
+

Remove all state variables associated with the request.

+
+
+% set tok [::time::gettime ntp2a.mcc.ac.uk]
+% set t [::time::unixtime $tok]
+% ::time::cleanup $tok
+
+
+% set tok [::time::getsntp pool.ntp.org]
+% set t [::time::unixtime $tok]
+% ::time::cleanup $tok
+
+
+proc on_time {token} {
+   if {[time::status $token] eq "ok"} {
+      puts [clock format [time::unixtime $token]]
+   } else {
+      puts [time::error $token]
+   }
+   time::cleanup $token
+}
+time::getsntp -command on_time pool.ntp.org
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ntp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

ntp

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/ooutil/ooutil.html Index: embedded/www/tcllib/files/modules/ooutil/ooutil.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ooutil/ooutil.html @@ -0,0 +1,255 @@ + + +oo::util - Utility commands for TclOO + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

oo::util(n) 1.1 tcllib "Utility commands for TclOO"

+

Name

+

oo::util - Utility commands for TclOO

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require oo::util ?1.1?
    • +
+ +
+
+

Description

+

This package provides a convenience command for the easy specification +of instance methods as callback commands, like timers, file events, Tk +bindings, etc.

+
+

COMMANDS

+
+
mymethod method ?arg...?
+

This command is available within instance methods. It takes a method +name and, possibly, arguments for the method and returns a command +prefix which, when executed, will invoke the named method of the +object we are in, with the provided arguments, and any others supplied +at the time of actual invokation.

+

Note: The command is equivalent to and named after the command +provided by the OO package snit for the same purpose.

+
classmethod name arguments body
+

This command is available within class definitions. It takes a method +name and, possibly, arguments for the method and creates a method on the +class, available to a user of the class and of derived classes.

+

Note: The command is equivalent to the command typemethod +provided by the OO package snit for the same purpose.

+

Example

+
+oo::class create ActiveRecord {
+    classmethod find args { puts "[self] called with arguments: $args" }
+}
+oo::class create Table {
+    superclass ActiveRecord
+}
+puts [Table find foo bar]
+# ======
+# which will write
+# ======
+# ::Table called with arguments: foo bar
+
+
+
classvariable ?arg...?
+

This command is available within instance methods. It takes a series +of variable names and makes them available in the method's scope. The +originating scope for the variables is the class (instance) the object +instance belongs to. In other words, the referenced variables are shared +between all instances of their class.

+

Note: The command is roughly equivalent to the command +typevariable provided by the OO package snit for the +same purpose. The difference is that it cannot be used in the class +definition itself.

+

Example:

+
+% oo::class create Foo {
+    method bar {z} {
+        classvariable x y
+        return [incr x $z],[incr y]
+    }
+}
+::Foo
+% Foo create a
+::a
+% Foo create b
+::b
+% a bar 2
+2,1
+% a bar 3
+5,2
+% b bar 7
+12,3
+% b bar -1
+11,4
+% a bar 0
+11,5
+
+
+
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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/otp/otp.html Index: embedded/www/tcllib/files/modules/otp/otp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/otp/otp.html @@ -0,0 +1,211 @@ + +otp - RFC 2289 A One-Time Password System + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

otp(n) 1.0.0 tcllib "RFC 2289 A One-Time Password System"

+

Name

+

otp - One-Time Passwords

+
+ + +

Description

+

This package is an implementation in Tcl of the One-Time Password +system as described in RFC 2289 (1). This system uses message-digest +algorithms to sequentially hash a passphrase to create single-use +passwords. The resulting data is then provided to the user as either +hexadecimal digits or encoded using a dictionary of 2048 words. This +system is used by OpenBSD for secure login and can be used as a SASL +mechanism for authenticating users.

+

In this implementation we provide support for four algorithms that are +included in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) +and SHA-1 (5).

+
+ +

EXAMPLES

+
+% otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase"
+(binary gibberish)
+% otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase"
+SOON ARAB BURG LIMB FILE WAD
+% otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase"
+e249b58257c80087
+
+
+

REFERENCES

+
    +

  1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998. + http://www.rfc-editor.org/rfc/rfc2289.txt

    2. +

  2. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    3. +

  3. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    4. +

  4. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    5. +

  5. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    6. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category otp of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_intro.html Index: embedded/www/tcllib/files/modules/page/page_intro.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_intro.html @@ -0,0 +1,152 @@ + + +page_intro - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_intro(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_intro - page introduction

+
+ +

Description

+

page (short for parser generator) stands for a set of +related packages which help in the construction of parser generators, +and other utilities doing text processing.

+

They are mainly geared towards supporting the Tcllib application +page, with the package page::pluginmgr in a central +role as the plugin management for the application. The other packages +are performing low-level text processing and utility tasks geared +towards parser generation and mainly accessed by page through +plugins.

+

The packages implementing the plugins are not documented as regular +packages, as they cannot be loaded into a general interpreter, like +tclsh, without extensive preparation of the interpreter. Preparation +which is done for them by the plugin manager.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_pluginmgr.html Index: embedded/www/tcllib/files/modules/page/page_pluginmgr.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_pluginmgr.html @@ -0,0 +1,710 @@ + + +page_pluginmgr - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_pluginmgr(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_pluginmgr - page plugin manager

+
+ +

Synopsis

+
+
    +
  • package require page::pluginmgr ?0.2?
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides the plugin manager central to the page +application. It manages the various reader, writer, configuration, and +transformation plugins which actually process the text (read, +transform, and write).

+

All plugins are loaded into slave interpreters specially prepared for +them. While implemented using packages they need this special +environment and are not usable in a plain interpreter, like +tclsh. Because of that they are only described in general terms in +section PREDEFINED PLUGINS, and not documented as regular +packages. It is expected that they follow the APIs specified in the +sections

+
    +

  1. CONFIG PLUGIN API

    2. +

  2. READER PLUGIN API

    3. +

  3. WRITER PLUGIN API

    4. +

  4. TRANSFORM PLUGIN API

    5. +
+

as per their type.

+
+

API

+
+
::page::pluginmgr::reportvia cmd
+

This command defines the callback command used by +::page::pluginmgr::report (see below) to report input errors and +warnings. The default is to write such reports to the standard error +channel.

+
::page::pluginmgr::report level text ?from ?to??
+

This command is used to report input errors and warnings. By default +such reports are written to the standard error. This can be changed by +setting a user-specific callback command with +::page::pluginmgr::reportvia (see above).

+

The arguments level and text specify both the importance +of the message, and the message itself. For the former see the package +logger for the allowed values.

+

The optional argument from and to can be used by the +caller to indicate the location (or range) in the input where the +reported problem occured. Each is a list containing two elements, the +line and the column in the input, in this order.

+
::page::pluginmgr::log cmd
+

This command defines a log callback command to be used by loaded +plugins for the reporting of internal errors, warnings, and general +information. Specifying the empty string as callback disables logging.

+

Note: The cmd has to be created by the logger package, +or follow the same API as such.

+

The command returns the empty string as its result.

+
::page::pluginmgr::configuration name
+

This command loads the named configuration plugin, retrieves the +options encoded in it, and then immediately unloads it again.

+

If the name is the path to a file, then this files will be tried +to be loaded as a plugin first, and, if that fails, opened and its +contents read as a list of options and their arguments, separated by +spaces, tabs and newlines, possibly quotes with single and double +quotes.

+

See section CONFIG PLUGIN API for the API expected of +configuration plugins.

+

The result of the command is the list of options retrieved.

+
::page::pluginmgr::reader name
+

This command loads the named reader plugin and initializes it. The +result of the command is a list of options the plugin understands.

+

Only a single reader plugin can be loaded. Loading another reader +plugin causes the previously loaded reader plugin to be de-initialized +and unloaded.

+

See section READER PLUGIN API for the API expected of +reader plugins.

+
::page::pluginmgr::rconfigure dict
+

This commands configures the loaded reader plugin. The options and +their values are provided as a Tcl dictionary. The result of the +command is the empty string.

+
::page::pluginmgr::rtimeable
+

This commands checks if the loaded reader plugin is able to collect +timing statistics. The result of the command is a boolean flag. The +result is true if the plugin can be timed, and false +otherwise.

+
::page::pluginmgr::rtime
+

This command activates the collection of timing statistics in the +loaded reader plugin.

+
::page::pluginmgr::rgettime
+

This command retrieves the collected timing statistics of the loaded +reader plugin after it was executed.

+
::page::pluginmgr::rhelp
+

This command retrieves the help string of the loaded reader +plugin. This is expected to be in doctools format.

+
::page::pluginmgr::rlabel
+

This command retrieves the human-readable name of the loaded reader +plugin.

+
::page::pluginmgr::read read eof ?complete?
+

This command invokes the loaded reader plugin to process the input, +and returns the results of the plugin as its own result. The input is +accessible through the callback commands read, and eof. The +optional done can be used to intrecept when the plugin has +completed its processing. All arguments are command prefixes.

+

The plugin will invoke the various callbacks in the following +situations:

+
+
read num
+

is invoked whenever input to process is needed, with the number of +characters/bytes it asks for. The result is expected to be the input +the plugin is in need of.

+
eof
+

is invoked by the plugin to check if the input has reached the of the +stream. The result is expected to be a boolean flag, true when +the input has hit EOF, and false otherwise.

+
done
+

is invoked when the plugin has completed the processing of the input.

+
+
::page::pluginmgr::writer name
+

This command loads the named writer plugin and initializes it. The +result of the command is a list of options the plugin understands.

+

Only a single reader plugin can be loaded. Loading another reader +plugin causes the previously loaded reader plugin to be de-initialized +and unloaded.

+

See section WRITER PLUGIN API for the API expected of +writer plugins.

+
::page::pluginmgr::wconfigure dict
+

This commands configures the loaded writer plugin. The options and +their values are provided as a Tcl dictionary. The result of the +command is the empty string.

+
::page::pluginmgr::wtimeable
+

This commands checks if the loaded writer plugin is able to measure +execution times. The result of the command is a boolean flag. The +result is true if the plugin can be timed, and false +otherwise.

+
::page::pluginmgr::wtime
+

This command activates the collection of timing statistics in the +loaded writer plugin.

+
::page::pluginmgr::wgettime
+

This command retrieves the collected timing statistics of the loaded +writer plugin after it was executed.

+
::page::pluginmgr::whelp
+

This command retrieves the help string of the loaded writer +plugin. This is expected to be in doctools format.

+
::page::pluginmgr::wlabel
+

This command retrieves the human-readable name of the loaded writer +plugin.

+
::page::pluginmgr::write chan data
+

The loaded writer plugin is invoked to generate the output. It is +given the data to generate the outpout from, and the Tcl handle +chan of the channel to write the generated output to. The +command returns th empty string as its result.

+
::page::pluginmgr::transform name
+

This command loads the named transformation plugin and initializes +it. The result of the command is a 2-element list containing the +plugin id and a list of options the plugin understands, in this order.

+

Multiple transformations plugins can be loaded and are identified by +handles.

+

See section TRANSFORM PLUGIN API for the API expected of +transformation plugins.

+
::page::pluginmgr::tconfigure id dict
+

This commands configures the identified transformation plugin. The +options and their values are provided as a Tcl dictionary. The result +of the command is the empty string.

+
::page::pluginmgr::ttimeable id
+

This commands checks if the identified transformation plugin is able +to collect timing statistics. The result of the command is a boolean +flag. The result is true if the plugin can be timed, and +false otherwise.

+
::page::pluginmgr::ttime id
+

This command activates the collection of timing statistics in the +identified transformation plugin.

+
::page::pluginmgr::tgettime id
+

This command retrieves the collected timing statistics of the +identified transformation plugin after it was executed.

+
::page::pluginmgr::thelp id
+

This command retrieves the help string of the identified +transformation plugin. This is expected to be in doctools +format.

+
::page::pluginmgr::tlabel id
+

This command retrieves the human-readable name of the identified +transformation plugin.

+
::page::pluginmgr::transform_do id data
+

The identified transformation plugin is invoked to process the +specified data. The result of the plugin is returned as the +result of the command.

+
+
+

CONFIG PLUGIN API

+

Configuration plugins are expected to provide a single command, +described below.

+
+
page_cdefinition
+

This command of a configuration plugin is called by the plugin manager +to execute it. Its result has to be a list of options and values to +process.

+
+

Configuration plugins do not expect the environment to provide any +special commands.

+

It is expected that a configuration plugin FOO is implemented +by the package page::config::FOO.

+

Configuration plugins are loaded, executed, and unloaded in one step, +they are not kept in memory. The command for doing this is +::page::pluginmgr::configuration.

+
+

READER PLUGIN API

+

Reader plugins are expected to provide the following commands, +described below.

+
+
page_rfeature name
+

This command takes a feature name and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be true if the feature is supported, and +false otherwise.

+

See section FEATURES for the possible features the plugin +manager will ask for.

+
page_rtime
+

This command is invoked to activate the collection of timing +statistics.

+
page_rgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_rlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_rhelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_roptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_rconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_rrun
+

This command is invoked to process the input stream per the current +plugin configuration. The result of the command is the result of the +processing.

+
+

Reader plugins expect the environment to provide the following special +commands.

+
+
page_read num
+

This command is invoked to read num characters/bytes from the +input. Its result has to be read characters/bytes.

+
page_read_done
+

This command is invoked to signal that the plugin has completed the +processing of the input.

+
page_eof
+

This command is invoked to check if the input stream has reached its +end. Its result has to be a boolean flag, true when the input +has reached the end, false otherwise.

+
page_info text ?from ?to??
+

Invoked to report some information to the user. May indicate a +location or range in the input. Each piece of location data, if +provided, is a 2-element list containing line and column numbers.

+
page_warning text ?from ?to??
+

Invoked to report a warning to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_error text ?from ?to??
+

Invoked to report an error to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_log_info text
+

Invoked to report some internal information.

+
page_log_warning text
+

Invoked to report an internal warning.

+
page_log_error text
+

Invoked to report an internal error.

+
+

It is expected that a reader plugin FOO is implemented +by the package page::reader::FOO.

+

Reader plugins are loaded by the command +::page::pluginmgr::reader. At most one reader plugin can be kept +in memory.

+
+

WRITER PLUGIN API

+

Writer plugins are expected to provide the following commands, +described below.

+
+
page_wfeature
+

This command takes a feature name and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be true if the feature is supported, and +false otherwise.

+

See section FEATURES for the possible features the plugin +manager will ask for.

+
page_wtime
+

This command is invoked to activate the collection of timing +statistics.

+
page_wgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_wlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_whelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_woptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_wconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_wrun chan data
+

This command is invoked to process the specified data and write +it to the output stream chan. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string.

+
+

Writer plugins expect the environment to provide the following special +commands.

+
+
page_info text ?from ?to??
+

Invoked to report some information to the user. May indicate a +location or range in the input. Each piece of location data, if +provided, is a 2-element list containing line and column numbers.

+
page_warning text ?from ?to??
+

Invoked to report a warning to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_error text ?from ?to??
+

Invoked to report an error to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_log_info text
+

Invoked to report some internal information.

+
page_log_warning text
+

Invoked to report an internal warning.

+
page_log_error text
+

Invoked to report an internal error.

+
+

It is expected that a writer plugin FOO is implemented +by the package page::writer::FOO.

+

Writer plugins are loaded by the command +::page::pluginmgr::writer. At most one writer plugin can be kept +in memory.

+
+

TRANSFORM PLUGIN API

+

page::transform::* +Transformation plugins are expected to provide the following commands, +described below.

+
+
page_tfeature
+

This command takes a feature name and returns a boolean flag +indicating whether the feature is supported by the plugin, or not. +The result has to be true if the feature is supported, and +false otherwise.

+

See section FEATURES for the possible features the plugin +manager will ask for.

+
page_ttime
+

This command is invoked to activate the collection of timing +statistics.

+
page_tgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_tlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_thelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_toptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_tconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_trun chan data
+

This command is invoked to process the specified data and write +it to the output stream chan. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string.

+
+

Transformation plugins expect the environment to provide the following +special commands.

+
+
page_info text ?from ?to??
+

Invoked to report some information to the user. May indicate a +location or range in the input. Each piece of location data, if +provided, is a 2-element list containing line and column numbers.

+
page_warning text ?from ?to??
+

Invoked to report a warning to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_error text ?from ?to??
+

Invoked to report an error to the user. May indicate a location or +range in the input. Each piece of location data, if provided, is a +2-element list containing line and column numbers.

+
page_log_info text
+

Invoked to report some internal information.

+
page_log_warning text
+

Invoked to report an internal warning.

+
page_log_error text
+

Invoked to report an internal error.

+
+

It is expected that a transformation plugin FOO is implemented +by the package page::transform::FOO.

+

Transformation plugins are loaded by the command +::page::pluginmgr::transform. More than one transformation +plugin can be kept in memory.

+
+

PREDEFINED PLUGINS

+

The following predefined plugins are known, i.e. provided by the page +module.

+
+
Configuration
+
+
peg
+

Returns a set of options to configure the page application +for the processing of a PEG grammar and the generation of ME code. See +the packages grammar_peg, grammar_me and relations +for more details.

+
+
Reader
+
+
hb
+

Expects a so-called half-baked PEG container as input and +returns the equivalent abstract syntax tree. See the writer plugin +hb for the plugin generating this type of input.

+
lemon
+

Expects a grammar specification as understood by Richar Hipp's LEMON +parser generator and returns an abstract syntax tree for it.

+
peg
+

Expects a grammar specification in the form of a parsing expression +grammar (PEG) and returns an abstract syntax tree for it.

+
ser
+

Expect the serialized form of a parsing expression grammar as +generated by the package grammar::peg as input, converts it +into an equivalent abstract syntax tree and returns that.

+
treeser
+

Expects the serialized form of a tree as generated by the package +struct::tree as input and returns it, after validation.

+
+
Writer
+
+
hb
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out in the form of a so-called +half-baked PEG container.

+
identity
+

Takes any input and writes it as is.

+
mecpu
+

Expects symbolic assembler code for the MatchEngine CPU (See the +package grammar::me::cpu and relatives) and writes it out as +Tcl code for a parser.

+
me
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out as Tcl code for the MatchEngine (See the +package grammar::me and relatives) which parses input in +that grammar.

+
null
+

Takes any input and writes nothing. The logical equivalent of +/dev/null.

+
peg
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out in the form of a canonical PEG which can be +read by the reader plugin peg.

+
ser
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out as a serialized PEG container which can be +read by the reader plugin ser.

+
tpc
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out as Tcl code initializing a PEG container as +provided by the package grammar::peg.

+
tree
+

Takes any serialized tree (per package struct::tree) as +input and writes it out in a generic indented format.

+
+
Transformation
+
+
mecpu
+

Takes an abstract syntax tree for a parsing expression grammer as +input, generates symbolic assembler code for the MatchEngine CPU, and +returns that as its result (See the package grammar::me::cpu +and relatives).

+
reachable
+

Takes an abstract syntax tree for a parsing expression grammer as +input, performs a reachability analysis, and returns the modified and +annotated tree.

+
realizable
+

Takes an abstract syntax tree for a parsing expression grammer as +input, performs an analysis of realizability, and returns the modified +and annotated tree.

+
+
+
+

FEATURES

+

The plugin manager currently checks the plugins for only one feature, +timeable. A plugin supporting this feature is assumed to be +able to collect timing statistics on request.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_flow.html Index: embedded/www/tcllib/files/modules/page/page_util_flow.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_util_flow.html @@ -0,0 +1,204 @@ + + +page_util_flow - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_util_flow(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_flow - page dataflow/treewalker utility

+
+ +

Synopsis

+
+
    +
  • package require page::util::flow ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command for easy dataflow based +manipulation of arbitrary data structures, especially abstract syntax +trees.

+
+

API

+
+
::page::util::flow start flowvar nodevar script
+

This command contains the core logic to drive the walking of an +arbitrary data structure which can partitioned into separate +parts. Examples of such structures are trees and graphs.

+

The command makes no assumptions at all about the API of the structure +to be walked, except that that its parts, here called nodes, +are identified by strings. These strings are taken as is, from the +arguments, and the body, and handed back to the body, without +modification.

+

Access to the actual data structure, and all decisions regarding which +nodes to visit in what order are delegated to the body of the loop, +i.e. the script.

+

The body is invoked first for the nodes in the start-set specified via +start), and from then on for the nodes the body has requested to +be visited. The command stops when the set of nodes to visit becomes +empty. Note that a node can be visited more than once. The body has +complete control about this.

+

The body is invoked in the context of the caller. The variable named +by nodevar will be set to the current node, and the variable +named by flowvar will be set to the command of the flow object +through which the body can request the nodes to visit next. The API +provided by this object is described in the next section, +FLOW API.

+

Note that the command makes no promises regarding the order in which +nodes are visited, excpt that the nodes requested to be visited by the +current iteration will be visited afterward, in some order.

+
+
+

FLOW API

+

This section describes the API provided by the flow object made +accessible to the body script of ::page::util::flow.

+
+
flow visit node
+

Invoking this method requests that the node n is visited after +the current iteration.

+
flow visitl nodelist
+

Invoking this method requests that all the nodes found in the list +nodelist are visited after the current iteration.

+
flow visita node...
+

This is the variadic arguments form of the method visitl, see +above.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html Index: embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html @@ -0,0 +1,166 @@ + + +page_util_norm_lemon - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_util_norm_lemon(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_norm_lemon - page AST normalization, LEMON

+
+ +

Synopsis

+
+
    +
  • package require page::util::norm_lemon ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command which takes an AST for a +lemon grammar and normalizes it in various ways. The result +is called a Normalized Lemon Grammar Tree.

+

Note that this package can only be used from within a plugin +managed by the package page::pluginmgr.

+
+

API

+
+
::page::util::norm::lemon tree
+

This command assumes the tree object contains for a lemon +grammar. It normalizes this tree in place. The result is called a +Normalized Lemon Grammar Tree.

+

The exact operations performed are left undocumented for the moment.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_norm_peg.html Index: embedded/www/tcllib/files/modules/page/page_util_norm_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_util_norm_peg.html @@ -0,0 +1,204 @@ + + +page_util_norm_peg - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_util_norm_peg(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_norm_peg - page AST normalization, PEG

+
+ +

Synopsis

+
+
    +
  • package require page::util::norm_peg ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command which takes an AST for a +parsing expression grammar and normalizes it in various ways. The result +is called a Normalized PE Grammar Tree.

+

Note that this package can only be used from within a plugin +managed by the package page::pluginmgr.

+
+

API

+
+
::page::util::norm::peg tree
+

This command assumes the tree object contains for a +parsing expression grammar. It normalizes this tree in place. +The result is called a Normalized PE Grammar Tree.

+

The following operations are performd

+
    +

  1. The data for all terminals is stored in their grandparental +nodes. The terminal nodes and their parents are removed. Type +information is dropped.

    2. +

  2. All nodes which have exactly one child are irrelevant and are +removed, with the exception of the root node. The immediate +child of the root is irrelevant as well, and removed as well.

    3. +

  3. The name of the grammar is moved from the tree node it is stored +in to an attribute of the root node, and the tree node removed.

    +

    The node keeping the start expression separate is removed as +irrelevant and the root node of the start expression tagged with +a marker attribute, and its handle saved in an attribute of the +root node for quick access.

    4. +

  4. Nonterminal hint information is moved from nodes into attributes, +and the now irrelevant nodes are deleted.

    +

    Note: This transformation is dependent on the removal of all +nodes with exactly one child, as it removes the all 'Attribute' +nodes already. Otherwise this transformation would have to put +the information into the grandparental node.

    +

    The default mode given to the nonterminals is value.

    +

    Like with the global metadata definition specific information +is moved out out of nodes into attributes, the now irrelevant +nodes are deleted, and the root nodes of all definitions are +tagged with marker attributes. This provides us with a mapping +from nonterminal names to their defining nodes as well, which +is saved in an attribute of the root node for quick reference.

    +

    At last the range in the input covered by a definition is +computed. The left extent comes from the terminal for the +nonterminal symbol it defines. The right extent comes from +the rightmost child under the definition. While this not an +expression tree yet the location data is sound already.

    5. +

  5. The remaining nodes under all definitions are transformed +into proper expression trees. First character ranges, followed +by unary operations, characters, and nonterminals. At last the +tree is flattened by the removal of superfluous inner nodes.

    +

    The order matters, to shed as much nodes as possible early, and +to avoid unnecessary work later.

    6. +
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_peg.html Index: embedded/www/tcllib/files/modules/page/page_util_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_util_peg.html @@ -0,0 +1,217 @@ + + +page_util_peg - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_util_peg(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_peg - page PEG transformation utilities

+
+ + +

Description

+

This package provides a few common operations to PEG transformations. +They assume a Normalized PE Grammar Tree as input, see the +package page::util::norm::peg, possibly augmented with +attributes coming from transformations not in conflict with the base +definition.

+
+

API

+
+
::page::util::peg::symbolNodeOf tree node
+

Given an arbitrary expression node in the AST tree it +determines the node (itself or an ancestor) containing the name of the +nonterminal symbol the node belongs to, and returns its id. The result +is either the root of the tree (for the start expression), or a +definition node.

+
::page::util::peg::symbolOf tree node
+

As ::page::util::peg::symbolNodeOf, but returns the symbol name +instead of the node.

+
::page::util::peg::updateUndefinedDueRemoval tree
+

The removal of nodes in the AST tree can cause symbols to lose +one or more users.

+
+	A used by B and C,
+	B is reachable,
+	C is not,
+	so A now loses the node in the expression for C calling it,
+	or rather, not calling it anymore.
+
+

This command updates the cross-references and which nonterminals are +now undefined.

+
::page::util::peg::flatten treequery tree
+

This commands flattens nested sequence and choice operators in the AST +tree, re-using the treeql object treequery to +run the query determining which nodes to cut.

+
::page::util::peg::getWarnings tree
+

This command looks at the attributes of the AST tree for +problems with the grammar and issues warnings. They do not prevent us +from writing the grammar, but still represent problems with it the +user should be made aware of.

+

The result of the command is a dictionary mapping nonterminal names to +their associated warnings.

+
::page::util::peg::printWarnings msg
+

The argument of the command is a dictionary mapping nonterminal names +to their associated warnings, as generated by, for example, the +command ::page::util::peg::getWarnings.

+

The warnings contained therein are formatted and then printed via the +log command page_info. This means that this command can be used +only from within a plugin managed by the package +page::pluginmgr.

+
::page::util::peg::peOf tree eroot
+

This command converts the parsing expression starting at the node +eroot in the AST tree into a nested list. The exact syntax +of this list specified by the package grammar::peg.

+
::page::util::peg::printTclExpr pe
+

This command converts the parsing expression contained in the nested +list pe into a Tcl string which can be placed into a Tcl script. +See the package grammar::peg for the exact syntax of +pe.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_quote.html Index: embedded/www/tcllib/files/modules/page/page_util_quote.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/page/page_util_quote.html @@ -0,0 +1,186 @@ + + +page_util_quote - Parser generator tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

page_util_quote(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_quote - page character quoting utilities

+
+ + +

Description

+

This package provides a few utility commands to convert characters +into various forms.

+
+

API

+
+
::page::util::quote::unquote char
+

A character, as stored in an abstract syntax tree by a PEG processor +(See the packages grammar::peg::interpreter, +grammar::me, and their relations), i.e. in some quoted form, +is converted into the equivalent Tcl character. The character is returned +as the result of the command.

+
::page::util::quote::quote'tcl char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser, will +regenerate the character in question and is 7bit ASCII. The string is +returned as the result of this command.

+
::page::util::quote::quote'tclstr char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser and will +generate a human readable representation of the character in question. +The string is returned as the result of this command.

+

The string does not use any unprintable characters. It may use +backslash-quoting. High UTF characters are quoted to avoid problems +with the still prevalent ascii terminals. It is assumed that the +string will be used in a double-quoted environment.

+
::page::util::quote::quote'tclcom char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser when +used within a Tcl comment. The string is returned as the result of +this command.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, will undoubtedly contain bugs and other problems. +Please report such in the category page of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/pki/pki.html Index: embedded/www/tcllib/files/modules/pki/pki.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pki/pki.html @@ -0,0 +1,324 @@ + + +pki - public key encryption + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pki(n) 0.6 tcllib "public key encryption"

+

Name

+

pki - Implementation of the public key cipher

+
+ + + +

COMMANDS

+
+
::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? input key
+

Encrypt a message using PKI (probably RSA). +Requires the caller to specify either -priv to encrypt with +the private key or -pub to encrypt with the public key. The +default option is to pad and return in hex. One of -pub or +-priv must be specified. +The -hex option causes the data to be returned in encoded as +a hexidecimal string, while the -binary option causes the data +to be returned as a binary string. If they are specified multiple +times, the last one specified is used. +The -pad option causes the data to be padded per PKCS#1 prior +to being encrypted. The -nopad inhibits this behaviour. If +they are specified multiple times, the last one specified is used. +The input to encrypt is specified as input. +The key parameter, holding the key to use, is a return value +from either +::pki::pkcs::parse_key, +::pki::x509::parse_cert, or +::pki::rsa::generate.

+

Mapping to OpenSSL's openssl application:

+
    +

  1. "openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"

    2. +

  2. "openssl rsautl -sign" == "::pki::encrypt -binary -priv"

    3. +
+
::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--? input key
+

Decrypt a message using PKI (probably RSA). See ::pki::encrypt for option handling.

+

Mapping to OpenSSL's openssl application:

+
    +

  1. "openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"

    2. +

  2. "openssl rsautl -verify" == "::pki::decrypt -binary -pub"

    3. +
+
::pki::sign input key ?algo?
+

Digitally sign message input using the private key. If algo +is ommited "sha1" is assumed. Possible values for algo include +"md5", "sha1", "sha256", and "raw". Specifyin "raw" for algo will +inhibit the building of an ASN.1 structure to encode which hashing +algorithm was chosen. +The input should be the plain text, hashing will be performed on it. +The key should include the private key.

+
::pki::verify signedmessage plaintext key ?algo?
+

Verify a digital signature using a public key. Returns true or false.

+
::pki::key key ?password? ?encodePem?
+

Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications. For RSA keys this means PKCS#1.

+
::pki::pkcs::parse_key key ?password?
+

Convert a PKCS#1 private key into a usable key, i.e. one which +can be used as argument for +::pki::encrypt, +::pki::decrypt, +::pki::sign, and +::pki::verify.

+
::pki::x509::parse_cert cert
+

Convert an X.509 certificate to a usable (public) key, i.e. one which +can be used as argument for +::pki:encrypt, +::pki::decrypt, and +::pki::verify. +The cert argument can be either PEM or DER encoded.

+
::pki::rsa::generate bitlength ?exponent?
+

Generate a new RSA key pair, the parts of which can be used as +argument for +::pki::encrypt, +::pki::decrypt, +::pki::sign, and +::pki::verify. +The bitlength argument is the length of the public key modulus. +The exponent argument should generally not be specified unless +you really know what you are doing.

+
::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
+

Verify that a trust can be found between the certificate specified in the +cert argument and one of the certificates specified in the list +of certificates in the trustedcerts argument. (Eventually the +chain can be through untrusted certificates listed in the intermediatecerts +argument, but this is currently unimplemented). +The certificates specified in the cert and trustedcerts option +should be parsed (from ::pki::x509::parse_cert).

+
::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-encrypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl dn?
+

Validate that a certificate is valid to be used in some capacity. If +multiple options are specified they must all be met for this procedure +to return "true". +Currently, only the -sign_cert option is functional. +Arguments for the -sign_cert option are dn_to_be_signed +and ca_depth. The dn_to_be_signed is the distinguished from +the subject of a certificate to verify that the certificate specified in +the cert argument can sign. The ca_depth argument is used to +indicate at which depth the verification should be done at. Some +certificates are limited to how far down the chain they can be used to +verify a given certificate.

+
::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
+

Generate a certificate signing request from a key pair specified in +the keylist argument. +The namelist argument is a list of "name" followed by "value" +pairs to encoding as the requested distinguished name in the CSR. +The encodePem option specifies whether or not the result should +be PEM encoded or DER encoded. A "true" value results in the result +being PEM encoded, while any other value 9results in the the result +being DER encoded. DER encoding is the default. +The algo argument specifies the hashing algorithm we should use +to sign this certificate signing request with. The default is "sha1". +Other possible values include "md5" and "sha256".

+
::pki::pkcs::parse_csr csr
+

Parse a Certificate Signing Request. The csr argument can be +either PEM or DER encoded.

+
::pki::x509::create_cert signreqlist cakeylist serial_number notBefore notAfter isCA extensions ?encodePem? ?algo?
+

Sign a signing request (usually from ::pki::pkcs::create_csr or +::pki::pkcs::parse_csr) with a Certificate Authority (CA) certificate. +The signreqlist argument should be the parsed signing request. +The cakeylist argument should be the parsed CA certificate. +The serial_number argument should be a serial number unique to +this certificate from this certificate authority. +The notBefore and notAfter arguments should contain the +time before and after which (respectively) the certificate should +be considered invalid. The time should be encoded as something +clock format will accept (i.e., the results of clock seconds +and clock add). +The isCA argument is a boolean argumen describing whether or not +the signed certificate should be a a CA certificate. If specified as +true the "id-ce-basicConstraints" extension is added with the arguments +of "critical" being true, "allowCA" being true, and caDepth being +-1 (infinite). +The extensions argument is a list of extensions and their parameters +that should be encoded into the created certificate. Currently only one +extension is understood ("id-ce-basicConstraints"). It accepts three +arguments critical allowCA caDepth. The critical +argument to this extension (and any extension) whether or not the +validator should reject the certificate as invalid if it does not +understand the extension (if set to "true") or should ignore the extension +(if set to "false"). The allowCA argument is used to specify +as a boolean value whether or not we can be used a certificate +authority (CA). The caDepth argument indicates how many children +CAs can be children of this CA in a depth-wise fashion. A value of "0" +for the caDepth argument means that this CA cannot sign a CA +certificate and have the result be valid. A value of "-1" indicates +infinite depth.

+
+
+

EXAMPLES

+
+
+
+
+
+

REFERENCES

+
    +
  1. +
+
+

AUTHORS

+

Roy Keene

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rsa of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html Index: embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html @@ -0,0 +1,420 @@ + + +pluginmgr - Plugin management + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pluginmgr(n) 0.3 tcllib "Plugin management"

+

Name

+

pluginmgr - Manage a plugin

+
+ + +

Description

+

This package provides commands and objects for the generic management +of plugins which can be loaded into an application.

+

To avoid the implementation of yet another system to locate Tcl code +the system provides by this package is built on top of the regular +package management system. Each plugin is considered as a package and +a simple invokation of package require is enough to locate and +load it, if it exists. The only time we will need additional paths is +when a plugin manager is part of a wrapped application and has to be +able to search for plugins existing outside of that application. For +this situation the package provides a command to create a general set +of such paths based on names for the plugin manager and/or application +in question.

+

The main contribution of this package is a generic framework which +allows the easy declaration of

+
    +

  1. How to translate a plugin name to the name of the package implementing +it, and vice versa.

    2. +

  2. The list of commands a plugin has to provide as API, and also of more +complex checks as code.

    3. +

  3. The list of commands expected by the plugin from the environment.

    4. +
+

This then allows the easy generation of plugin managers customized to +particular types of plugins for an application.

+

It should be noted that all plugin code is considered untrusted and +will always be executed within a safe interpreter. The interpreter is +enabled enough to allow plugins the loading of all additional packages +they may need.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::pluginmgr objectName ?option value...?
+

This command creates a new plugin manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the mamager object, +specifying the applicable plugins and their API.

+
::pluginmgr::paths objectName name...
+

This utility command adds a set of paths to the specified object, +based on the given names. +It will search for:

+
    +

  1. The environment variable name_PLUGINS. Its contents will +be interpreted as a list of package paths. The entries have to be +separated by either : (unix) or ; (windows).

    +

    The name will be converted to upper-case letters.

    2. +

  2. The registry entry "HKEY_LOCAL_MACHINE\SOFTWARE\name\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by ;. This item is considered +only when on Windows (tm).

    +

    The casing of letters is not changed.

    3. +

  3. The registry entry "HKEY_CURRENT_USER\SOFTWARE\name\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by ;. This item is considered +only when on Windows (tm).

    +

    The casing of letters is not changed.

    4. +

  4. The directory "~/.name/plugin".

    5. +

  5. The directory "~/.name/plugins".

    +

    The casing of letters is not changed.

    6. +
+

and add all the paths found that way to the list of package paths +maintained by the object.

+

If name is namespaced each item in the list will be repeated per +prefix of name, with conversion of :-sequences into the proper +separator (underscore for environment variables, backslash for +registry entries, and / for directories).

+

Examples:

+
+    ::pluginmgr::paths ::obj docidx
+    => env  DOCIDX_PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
+       path ~/.docidx/plugins
+    ::pluginmgr::paths ::obj doctools::idx
+    => env  DOCTOOLS_PLUGINS
+       env  DOCTOOLS_IDX_PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
+       path ~/.doctools/plugin
+       path ~/.doctools/idx/plugin
+
+
+
+
+

OBJECT COMMAND

+

All commands created by the command ::pluginmgr (See section +PACKAGE COMMANDS) have the following general form and may +be used to invoke various operations on their plugin manager object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName clone
+

This method creates a new plugin management object and returns the +associated object command. The generated object is a clone of the +object the method was invoked on. I.e. the new object will have the +same configuration as the current object. With regard to state, if the +current object has a plugin loaded then this plugin and all associated +state is moved to the generated clone and the current object is reset +into the base state (no plugin loaded). In this manner a configured +plugin manager is also a factory for loaded plugins.

+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName do arg...
+

This method interprets its list of arguments as the words of a command +and invokes this command in the execution context of the plugin. +The result of the invoked command is made the result of the method. +The call will fail with an error if no valid plugin has been loaded +into the manager object.

+
objectName interpreter
+

This method returns the handle of the safe interpreter the current +plugin is loaded into. An empty string as return value signals that +the manager currently has no valid plugin loaded.

+
objectName plugin
+

This method returns the name of the plugin currently loaded. An empty +string as return value signals that the manager currently has no valid +plugin loaded.

+
objectName load string
+

This method loads, validates, and initializes a named plugin into the +manager object.

+

The algorithm to locate and load the plugin employed is:

+
    +

  1. If the string contains the path to an existing file then this +file is taken as the implementation of the plugin.

    2. +

  2. Otherwise the plugin name is translated into a package name via the value +of the option -pattern and then loaded through the +regular package management.

    3. +

  3. The load fails.

    4. +
+

The algorithm to validate and initialize the loaded code is:

+
    +

  1. If the option -api is non-empty introspection commands are +used to ascertain that the plugin provides the listed commands.

    2. +

  2. If the option -check is non-empty the specified command +prefix is called.

    3. +

  3. If either of the above fails the candidate plugin is unloaded again

    4. +

  4. Otherwise all the commands specified via the option +-cmds are installed in the plugin.

    5. +
+

A previously loaded plugin is discarded, but only if the new plugin +was found and sucessfully validated and initialized. Note that there +will be no intereference between old and new plugin as both will be +put into separate safe interpreters.

+
objectName unload
+

This method unloads the currently loaded plugin. It returns the empty +string. The call will be silently ignored if no plugin is loaded at +all.

+
objectName list
+

This method uses the contents of the option -pattern to find +all packages which can be plugins under the purview of this manager +object. It translates their names into plugin names and returns a list +containing them.

+
objectName path path
+

This methods adds the specified path to the list of additional +package paths to look at when searching for a plugin. It returns the +empty string. Duplicate paths are ignored, i.e. each path is added +only once. Paths are made absolute, but are not normalized.

+
objectName paths
+

This method returns a list containing all additional paths which have +been added to the plugin manager object since its creation.

+
+
+

OBJECT CONFIGURATION

+

All plugin manager objects understand the following configuration options:

+
+
-pattern string
+

The value of this option is a glob pattern which has to contain +exactly one '*'-operator. All packages whose names match this pattern +are the plugins recognized by the manager object. And vice versa, the +replacement of the '*'-operator with a plugin name will yield the name +of the package implementing that plugin.

+

This option has no default, except if option -name was set. +It has to be set before attempting to load a plugin, either directly, +or through option -name.

+
-api list
+

The value of this option is a list of command names, and any plugin +loaded has to provide these commands. Names which are not fully +qualified are considered to be rooted in the global namespace. +If empty no expectations are made on the plugin. The default value is +the empty list.

+
-check cmdprefix
+

The value of this option is interpreted as a command prefix. +Its purpose is to perform complex checks on a loaded plugin package to +validate it, which go beyond a simple list of provided commands.

+

It is called with the manager object command as the only argument and +has to return a boolean value. A value of true will be +interpreted to mean that the candidate plugin passed the test. +The call will happen if and only if the candidate plugin already +passed the basic API check specified through the option -api.

+

The default value is the empty list, which causes the manager object +to suppress the call and to assume the candidate plugin passes.

+
-cmds dict
+

The value of this option is a dictionary. It specifies the commands +which will be made available to the plugin (as keys), and the trusted +commands in the environment which implement them (as values). +The trusted commands will be executed in the interpreter specified by +the option -cmdip. +The default value is the empty dictionary.

+
-cmdip ipspec
+

The value of this option is the path of the interpreter where the +trusted commands given to the plugin will be executed in. +The default is the empty string, referring to the current interpreter.

+
-setup cmdprefix
+

The value of this option is interpreted as a command prefix.

+

It is called whenever a new safe interpreter for a plugin has been +created, but before a plugin is loaded. It is provided with the +manager object command and the interpreter handle as its only +arguments. Any return value will be ignored.

+

Its purpose is give a user of the plugin management the ability to +define commands, packages, etc. a chosen plugin may need while being +loaded.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pluginmgr of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/png/png.html Index: embedded/www/tcllib/files/modules/png/png.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/png/png.html @@ -0,0 +1,254 @@ + +png - Image manipulation + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

png(n) 0.1.2 tcllib "Image manipulation"

+

Name

+

png - PNG querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query and modify PNG images. PNG +stands for Portable Network Graphics and is specified at +http://www.libpng.org/pub/png/spec/1.2.

+
+

COMMANDS

+
+
::png::validate file
+

Returns a value indicating if file is a valid PNG file. The file +is checked for PNG signature, each chunks checksum is verified, +existence of a data chunk is verified, first chunk is checked for +header, last chunk is checked for ending. Things not checked +for are: validity of values within a chunk, multiple header chunks, +noncontiguous data chunks, end chunk before actual eof. This procedure +can take lots of time.

+

Possible return values:

+
+
OK
+

File is a valid PNG file.

+
SIG
+

no/broken PNG signature.

+
BADLEN
+

corrupt chunk length.

+
EOF
+

premature end of file.

+
NOHDR
+

missing header chunk.

+
CKSUM
+

crc mismatch.

+
NODATA
+

missing data chunk(s).

+
NOEND
+

missing end marker.

+
+
::png::isPNG file
+

Returns a boolean value indicating if the file file starts with +a PNG signature. This is a much faster and less intensive check than +::png::validate as it does not check if the PNG data is valid.

+
::png::imageInfo file
+

Returns a dictionary with keys width, height, +depth, color, compression, filter, and +interlace. The values are the associated properties of the PNG +image in file. +Throws an error if file is not a PNG image, or if the checksum of the +header is invalid. For information on interpreting the values for the +returned properties see +http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html.

+
::png::getTimestamp file
+

Returns the epoch time if a timestamp chunk is found in the PNG image +contained in the file, otherwise returns the empty string. Does +not attempt to verify the checksum of the timestamp chunk. +Throws an error if the file is not a valid PNG image.

+
::png::setTimestamp file time
+

Writes a new timestamp to the file, either replacing the old +timestamp, or adding one just before the data chunks if there was no +previous timestamp. time is the new time in the gmt epoch +format. +Throws an error if file is not a valid PNG image.

+
::png::getComments file
+

Currently supports only uncompressed comments. Does not attempt to +verify the checksums of the comment chunks. Returns a list where each +element is a comment. Each comment is itself a list. The list for a +plain text comment consists of 2 elements: the human readable keyword, +and the text data. A unicode (international) comment consists of 4 +elements: the human readable keyword, the language identifier, the +translated keyword, and the unicode text data. +Throws an error if file is not a valid PNG image.

+
::png::removeComments file
+

Removes all comments from the PNG image in file. Beware - This +uses memory equal to the file size minus comments, to hold the +intermediate result. +Throws an error if file is not a valid PNG image.

+
::png::addComment file keyword text
+

Adds a plain text comment to the PNG image in file, just +before the first data chunk. Will throw an error if no data chunk is +found. keyword has to be less than 80 characters long to conform +to the PNG specification.

+
::png::addComment file keyword lang keyword2 text
+

Adds a unicode (international) comment to the PNG image in file, +just before the first data chunk. Will throw an error if no data chunk +is found. keyword has to be less than 80 characters long to +conform to the PNG specification. keyword2 is the translated +keyword, in the language specified by the language identifier +lang.

+
::png::image file
+

Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor.

+
::png::write file data
+

Takes a list of scanlines in the Tk_GetColor format and writes the represented image +to file.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category png of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3/pop3.html Index: embedded/www/tcllib/files/modules/pop3/pop3.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pop3/pop3.html @@ -0,0 +1,323 @@ + +pop3 - Tcl POP3 Client Library + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pop3(n) 1.9 tcllib "Tcl POP3 Client Library"

+

Name

+

pop3 - Tcl client for POP3 email protocol

+
+ + +

Description

+

The pop3 package provides a simple Tcl-only client library +for the POP3 email protocol as specified in +RFC 1939. +It works by opening the standard POP3 socket on the server, +transmitting the username and password, then providing a Tcl API to +access the POP3 protocol commands. All server errors are returned as +Tcl errors (thrown) which must be caught with the Tcl catch +command.

+
+

API

+
+
::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username password ?port?
+

Open a socket connection to the server specified by host, +transmit the username and password as login information to +the server. The default port number is 110, which can be +overridden using the optional port argument. The return value +is a channel used by all of the other ::pop3 functions.

+

The command recognizes three options

+
+
-msex boolean
+

Setting this option tells the package that the server we are talking +to is an MS Exchange server (which has some oddities we have to work +around). The default is False.

+
-retr-mode retr|list|slow
+

The retrieval mode determines how exactly messages are read from the +server. +The allowed values are retr, list and slow. +The default is retr. See ::pop3::retrieve for more +information.

+
-socketcmd cmdprefix
+

This option allows the user to overide the use of the builtin +socket command with any API-compatible command. The envisioned +main use is the securing of the new connection via SSL, through the +specification of the command tls::socket. This command is +specially recognized as well, changing the default port of the +connection to 995.

+
-stls boolean
+

Setting this option tells the package to secure the connection using +SSL or TLS. It performs STARTTLS as described in IETF RFC 2595, it +first opens a normal, unencrypted connection and then negotiates a +SSLv3 or TLSv1 connection. If the connection cannot be secured, the +connection will be closed and an error will be returned

+
-tls-callback stls-callback-command
+

This option allows the user to overide the tls::callback used during +the -stls SSL/TLS handshake. See the TLS manual for details on how +to implement this callback.

+
+
::pop3::config chan
+

Returns the configuration of the pop3 connection identified by the +channel handle chan as a serialized array.

+
::pop3::status chan
+

Query the server for the status of the mail spool. The status is +returned as a list containing two elements, the first is the number of +email messages on the server and the second is the size (in octets, 8 +bit blocks) of the entire mail spool.

+
::pop3::last chan
+

Query the server for the last email message read from the spool. This +value includes all messages read from all clients connecting to the +login account. This command may not be supported by the email server, +in which case the server may return 0 or an error.

+
::pop3::retrieve chan startIndex ?endIndex?
+

Retrieve a range of messages from the server. If the endIndex +is not specified, only one message will be retrieved. The return +value is a list containing each message as a separate element. See +the startIndex and endIndex descriptions below.

+

The retrieval mode determines how exactly messages are read from the +server. The mode retr assumes that the RETR command delivers +the size of the message as part of the command status and uses this to +read the message efficiently. In mode list RETR does not +deliver the size, but the LIST command does and we use this to +retrieve the message size before the actual retrieval, which can then +be done efficiently. In the last mode, slow, the system is +unable to obtain the size of the message to retrieve in any manner and +falls back to reading the message from the server line by line.

+

It should also be noted that the system checks upon the configured +mode and falls back to the slower modes if the above assumptions are +not true.

+
::pop3::delete chan startIndex ?endIndex?
+

Delete a range of messages from the server. If the endIndex is +not specified, only one message will be deleted. Note, the indices +are not reordered on the server, so if you delete message 1, then the +first message in the queue is message 2 (message index 1 is no longer +valid). See the startIndex and endIndex descriptions +below.

+
+
startIndex
+

The startIndex may be an index of a specific message starting +with the index 1, or it have any of the following values:

+
+
start
+

This is a logical value for the first message in the spool, equivalent +to the value 1.

+
next
+

The message immediately following the last message read, see +::pop3::last.

+
end
+

The most recent message in the spool (the end of the spool). This is +useful to retrieve only the most recent message.

+
+
endIndex
+

The endIndex is an optional parameter and defaults to the value +"-1", which indicates to only retrieve the one message specified by +startIndex. If specified, it may be an index of a specific +message starting with the index "1", or it may have any of the +following values:

+
+
last
+

The message is the last message read by a POP3 client, see +::pop3::last.

+
end
+

The most recent message in the spool (the end of the spool).

+
+
+
::pop3::list chan ?msg?
+

Returns the scan listing of the mailbox. If parameter msg is +given, then the listing only for that message is returned.

+
::pop3::top chan msg n
+

Optional POP3 command, not all servers may support this. +::pop3::top retrieves headers of a message, specified by +parameter msg, and number of n lines from the message +body.

+
::pop3::uidl chan ?msg?
+

Optional POP3 command, not all servers may support this. +::pop3::uidl returns the uid listing of the mailbox. If the +parameter msg is specified, then the listing only for that +message is returned.

+
::pop3::capa chan
+

Optional POP3 command, not all servers may support this. +::pop3::capa returns a list of the capabilities of the server. +TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities. +See IETF RFC 2449.

+
::pop3::close chan
+

Gracefully close the connect after sending a POP3 QUIT command down +the socket.

+
+
+

Secure mail transfer

+

A pop3 connection can be secured with SSL/TLS by requiring the package +TLS and then using either the option -socketcmd or +the option -stls of the command pop3::open. +The first method, option -socketcmd, will force the use +of the tls::socket command when opening the connection. This is +suitable for POP3 servers which expect SSL connections only. These will +generally be listening on port 995.

+
+	package require tls
+	tls::init -cafile /path/to/ca/cert -keyfile ...
+	# Create secured pop3 channel
+	pop3::open -socketcmd tls::socket \\
+		$thehost $theuser $thepassword
+	...
+
+

The second method, option -stls, will connect to the standard POP3 +port and then perform an STARTTLS handshake. This will only work for POP3 +servers which have this capability. The package will confirm that the +server supports STARTTLS and the handshake was performed correctly before +proceeding with authentication.

+
+	package require tls
+	tls::init -cafile /path/to/ca/cert -keyfile ...
+	# Create secured pop3 channel
+	pop3::open -stls 1 \\
+		$thehost $theuser $thepassword
+	...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pop3d/pop3d.html @@ -0,0 +1,334 @@ + + +pop3d - Tcl POP3 Server Package + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pop3d(n) 1.1.0 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d - Tcl POP3 server implementation

+
+ + +

Description

+
+
::pop3d::new ?serverName?
+

This command creates a new server object with an associated global Tcl +command whose name is serverName.

+
+

The command serverName may be used to invoke various operations +on the server. It has the following general form:

+
+
serverName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A pop3 server can be started on any port the caller has permission for +from the operating system. The default port will be 110, which is the +port defined by the standard specified in +RFC 1939 (http://www.rfc-editor.org/rfc/rfc1939.txt). +After creating, configuring and starting a the server object will +listen for and accept connections on that port and handle them +according to the POP3 protocol.

+

Note: The server provided by this module will handle only the +basic protocol by itself. For the higher levels of user authentication +and handling of the actual mailbox contents callbacks will be invoked.

+

The following commands are possible for server objects:

+
+
serverName up
+

After this call the server will listen for connections on its configured port.

+
serverName down
+

After this call the server will stop listening for connections. This +does not affect existing connections.

+
serverName destroy ?mode?
+

Destroys the server object. Currently open connections are handled +depending on the chosen mode. +The provided modes are:

+
+
kill
+

Destroys the server immediately, and forcefully closes all currently +open connections. This is the default mode.

+
defer
+

Stops the server from accepting new connections and will actually +destroy it only after the last of the currently open connections for +the server is closed.

+
+
serverName configure
+

Returns a list containing all options and their current values in a +format suitable for use by the command array set. The options +themselves are described in section Options.

+
serverName configure -option
+

Returns the current value of the specified option. This is an alias +for the method cget. The options themselves are described in +section Options.

+
serverName configure -option value...
+

Sets the specified option to the provided value. The options +themselves are described in section Options.

+
serverName cget -option
+

Returns the current value of the specified option. The options +themselves are described in section Options.

+
serverName conn list
+

Returns a list containing the ids of all connections currently open.

+
serverName conn state id
+

Returns a list suitable for [array set] containing the +state of the connection referenced by id.

+
+
+

Options

+

The following options are available to pop3 server objects.

+
+
-port port
+

Defines the port to listen on for new connections. Default is +110. This option is a bit special. If port is set to "0" the +server, or rather the operating system, will select a free port on its +own. When querying -port the id of this chosen port will be +returned. Changing the port while the server is up will neither change +the returned value, nor will it change on which port the server is +listening on. Only after resetting the server via a call to +down followed by a call to up will the new port take +effect. It is at that time that the value returned when querying +-port will change too.

+
-auth command
+

Defines a command prefix to call whenever the authentication of +a user is required. If no such command is specified the server will +reject all users. The interface which has to be provided by the +command prefix is described in section Authentication.

+
-storage command
+

Defines a command prefix to call whenever the handling of +mailbox contents is required. If no such command is specified the +server will claim that all mailboxes are empty. The interface which +has to be provided by the command prefix is described in section +Mailboxes.

+
-socket command
+

Defines a command prefix to call for opening the listening socket. +This can be used to make the pop3 server listen on a SSL socket +as provided by the tls package, see the command tls::socket.

+
+
+

Authentication

+

Here we describe the interface which has to be provided by the +authentication callback so that pop3 servers following the interface +of this module are able to use it.

+
+
authCmd exists name
+

This method is given a username and has to return a boolean +value telling whether or not the specified user exists.

+
authCmd lookup name
+

This method is given a username and has to return a two-element +list containing the password for this user and a storage reference, in +this order.

+

The storage reference is passed unchanged to the storage callback, see +sections Options and Mailboxes for either the +option defining it and or the interface to provide, respectively.

+
+
+

Mailboxes

+

Here we describe the interface which has to be provided by the storage +callback so that pop3 servers following the interface of this module +are able to use it. The mbox argument is the storage reference +as returned by the lookup method of the authentication +command, see section Authentication.

+
+
storageCmd dele mbox msgList
+

] +Deletes the messages whose numeric ids are contained in the +msgList from the mailbox specified via mbox.

+
storageCmd lock mbox
+

This method locks the specified mailbox for use by a single connection +to the server. This is necessary to prevent havoc if several +connections to the same mailbox are open. The complementary method is +unlock. The command will return true if the lock could be set +successfully or false if not.

+
storageCmd unlock mbox
+

This is the complementary method to lock, it revokes the lock +on the specified mailbox.

+
storageCmd size mbox ?msgId?
+

Determines the size of the message specified through its id in +msgId, in bytes, and returns this number. The command will +return the size of the whole maildrop if no message id was specified.

+
storageCmd stat mbox
+

Determines the number of messages in the specified mailbox and returns +this number.

+
storageCmd get mbox msgId
+

Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package mime. The pop3 server will use the functionality of +the mime token to send the mail to the requestor at the other end of a +pop3 connection.

+
+
+

Secure mail transfer

+

The option -socket (see Options) enables users of +the package to override how the server opens its listening socket. +The envisioned main use is the specification of the tls::socket +command, see package tls, to secure the communication.

+
+	package require tls
+	tls::init \\
+		...
+	pop3d::new S -socket tls::socket
+	...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html @@ -0,0 +1,260 @@ + + +pop3d::dbox - Tcl POP3 Server Package + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pop3d::dbox(n) 1.0.2 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d::dbox - Simple mailbox database for pop3d

+
+ + +

Description

+

The package pop3d::dbox provides simple/basic mailbox +management facilities. Each mailbox object manages a single base +directory whose subdirectories represent the managed mailboxes. Mails +in a mailbox are represented by files in a mailbox directory, where +each of these files contains a single mail, both headers and body, in +RFC 822 (http://www.rfc-editor.org/rfc/rfc822.txt) conformant +format.

+

Any mailbox object following the interface described below can be used +in conjunction with the pop3 server core provided by the package +pop3d. It is especially possible to directly use the objects +created by this package in the storage callback of pop3 servers +following the same interface as servers created by the package +pop3d.

+
+
::pop3d::dbox::new ?dbName?
+

This command creates a new database object with an associated global +Tcl command whose name is dbName.

+
+

The command dbName may be used to invoke various operations on +the database. It has the following general form:

+
+
dbName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for database objects:

+
+
dbName destroy
+

Destroys the mailbox database and all transient data. The directory +associated with the object is not destroyed.

+
dbName base base
+

Defines the base directory containing the mailboxes to manage. If this +method is not called none of the following methods will work.

+
dbName add mbox
+

Adds a mailbox of name mbox to the database. The name must be a +valid path component.

+
dbName remove mbox
+

Removes the mailbox specified through mbox, and the mails +contained therein, from the database. This method will fail if the +specified mailbox is locked.

+
dbName move old new
+

Changes the name of the mailbox old to new.

+
dbName list
+

Returns a list containing the names of all mailboxes in the directory +associated with the database.

+
dbName exists mbox
+

Returns true if the mailbox with name mbox exists in the +database, or false if not.

+
dbName locked mbox
+

Checks if the mailbox specified through mbox is currently locked.

+
dbName lock mbox
+

This method locks the specified mailbox for use by a single connection +to the server. This is necessary to prevent havoc if several +connections to the same mailbox are open. The complementary method is +unlock. The command will return true if the lock could be set +successfully or false if not.

+
dbName unlock mbox
+

This is the complementary method to lock, it revokes the lock +on the specified mailbox.

+
dbName stat mbox
+

Determines the number of messages in the specified mailbox and returns +this number. This method fails if the mailbox mbox is not +locked.

+
dbName size mbox ?msgId?
+

Determines the size of the message specified through its id in +msgId, in bytes, and returns this number. The command will +return the size of the whole maildrop if no message id was specified. +If specified the msgId has to be in the range "1 ... [dbName stat]" +or this call will fail. If stat was not called before this +call, size will assume that there are zero messages in the +mailbox.

+
dbName dele mbox msgList
+

Deletes the messages whose numeric ids are contained in the +msgList from the mailbox specified via mbox. +The msgList must not be empty or this call will fail. +The numeric ids in msgList have to be in the range "1 ... +[dbName stat]" or this +call will fail. If stat was not called +before this call, dele will assume +that there are zero messages in the mailbox.

+
storageCmd get mbox msgId
+

Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package mime. The token is read-only. In other +words, the caller is allowed to do anything with the token except to +modify it. +The msgId has to be in the range "1 ... +[dbName stat]" or this +call will fail. If stat was not called +before this call, get will assume +that there are zero messages in the mailbox.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html @@ -0,0 +1,219 @@ + + +pop3d::udb - Tcl POP3 Server Package + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pop3d::udb(n) 1.0.1 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d::udb - Simple user database for pop3d

+
+ + +

Description

+

The package pop3d::udb provides simple in memory databases +which can be used in conjunction with the pop3 server core provided by +the package pop3d. The databases will use the names of users +as keys and associates passwords and storage references with them.

+

Objects created by this package can be directly used in the +authentication callback of pop3 servers following the same interface +as servers created by the package pop3d.

+
+
::pop3d::udb::new ?dbName?
+

This command creates a new database object with an associated global +Tcl command whose name is dbName.

+
+

The command dbName may be used to invoke various operations on +the database. It has the following general form:

+
+
dbName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for database objects:

+
+
dbName destroy
+

Destroys the database object.

+
dbName add user pwd storage
+

Add a new user or changes the data of an existing user. Stores +password and storage reference for the given user.

+
dbName remove user
+

Removes the specified user from the database.

+
dbName rename user newName
+

Changes the name of the specified user to newName.

+
dbName lookup user
+

Searches the database for the specified user and returns a +two-element list containing the associated password and storage +reference, in this order. Throws an error if the user could not be +found. This is the interface as expected by the authentication +callback of package pop3d.

+
dbName exists user
+

Returns true if the specified user is known to the database, +else false.

+
dbName who
+

Returns a list of users known to the database.

+
dbName save ?file?
+

Saves the contents of the database into the given file. If the +file is not specified the system will use the path last used in a call +to dbName read. The generated file can be read by the +read method.

+
dbName read file
+

Reads the specified file and adds the contained user definitions +to the database. As the file is actually source'd a safe +interpreter is employed to safeguard against malicious code. This +interpreter knows the add command for adding users and their +associated data to this database. This command has the same argument +signature as the method add. The path of the file is +remembered internally so that it can be used in the next call of +dbName save without an argument.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/profiler/profiler.html Index: embedded/www/tcllib/files/modules/profiler/profiler.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/profiler/profiler.html @@ -0,0 +1,222 @@ + + +profiler - Tcl Profiler + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

profiler(n) 0.3 tcllib "Tcl Profiler"

+

Name

+

profiler - Tcl source code profiler

+
+ + +

Description

+

The profiler package provides a simple Tcl source code +profiler. It is a function-level profiler; that is, it collects only +function-level information, not the more detailed line-level +information. It operates by redefining the Tcl proc command. +Profiling is initiated via the ::profiler::init command.

+
+

COMMANDS

+
+
::profiler::init
+

Initiate profiling. All procedures created after this command is +called will be profiled. To profile an entire application, this +command must be called before any other commands.

+
::profiler::dump pattern
+

Dump profiling information for the all functions matching +pattern. If no pattern is specified, information for all +functions will be returned. The result is a list of key/value pairs +that maps function names to information about that function. The +information about each function is in turn a list of key/value pairs. +The keys used and their values are:

+
+
totalCalls
+

The total number of times functionName was called.

+
callerDist
+

A list of key/value pairs mapping each calling function that called +functionName to the number of times it called +functionName.

+
compileTime
+

The runtime, in clock clicks, of functionName the first time +that it was called.

+
totalRuntime
+

The sum of the runtimes of all calls of functionName.

+
averageRuntime
+

Average runtime of functionName.

+
descendantTime
+

Sum of the time spent in descendants of functionName.

+
averageDescendantTime
+

Average time spent in descendants of functionName.

+
+
::profiler::print ?pattern?
+

Print profiling information for all functions matching pattern. +If no pattern is specified, information about all functions will be +displayed. The return result is a human readable display of the +profiling information.

+
::profiler::reset ?pattern?
+

Reset profiling information for all functions matching pattern. +If no pattern is specified, information will be reset for all +functions.

+
::profiler::suspend ?pattern?
+

Suspend profiling for all functions matching pattern. If no +pattern is specified, profiling will be suspended for all +functions. It stops gathering profiling information after this command +is issued. However, it does not erase any profiling information that +has been gathered previously. Use resume command to re-enable +profiling.

+
::profiler::resume ?pattern?
+

Resume profiling for all functions matching pattern. If no +pattern is specified, profiling will be resumed for all functions. +This command should be invoked after suspending the profiler in the +code.

+
::profiler::sortFunctions key
+

Return a list of functions sorted by a particular profiling statistic. +Supported values for key are: calls, +exclusiveTime, compileTime, nonCompileTime, +totalRuntime, avgExclusiveTime, and +avgRuntime. The return result is a list of lists, where each +sublist consists of a function name and the value of key for +that function.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category profiler of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/pt/pt.html Index: embedded/www/tcllib/files/modules/pt/pt.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt.html @@ -0,0 +1,673 @@ + + +pt - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt(n) 1 tcllib "Parser Tools"

+

Name

+

pt - Parser Tools Application

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes pt, the main application of the module, +a parser generator. Its intended audience are people who wish +to create a parser for some language of theirs. Should you wish to +modify the application instead, please see the section about the +application's Internals for the basic references.

+

It resides in the User Application Layer of Parser Tools.

+

arch_user_app

+
+

Command Line

+
+
pt generate resultformat ?options...? resultfile inputformat inputfile
+

This sub-command of the application reads the parsing expression +grammar stored in the inputfile in the format inputformat, +converts it to the resultformat under the direction of the +(format-specific) set of options specified by the user and stores the +result in the resultfile.

+

The inputfile has to exist, while the resultfile may be +created, overwriting any pre-existing content of the file. Any missing +directory in the path to the resultfile will be created as well.

+

The exact form of the result for, and the set of options supported by +the known result-formats, are explained in the upcoming sections of +this document, with the list below providing an index mapping between +format name and its associated section. In alphabetical order:

+
+
c
+

A resultformat. See section C Parser.

+
container
+

A resultformat. See section Grammar Container.

+
critcl
+

A resultformat. See section C Parser Embedded In Tcl.

+
json
+

A input- and resultformat. See section JSON Grammar Exchange.

+
oo
+

A resultformat. See section TclOO Parser.

+
peg
+

A input- and resultformat. See section PEG Specification Language.

+
snit
+

A resultformat. See section Snit Parser.

+
+
+

Of the seven possible results four are parsers outright (c, +critcl, oo, and snit), one (container) +provides code which can be used in conjunction with a generic parser +(also known as a grammar interpreter), and the last two (json +and peg) are doing double-duty as input formats, allowing the +transformation of grammars for exchange, reformatting, and the like.

+

The created parsers fall into three categories:

+

gen_options

+
+
Specialized parsers implemented in C
+

The fastest parsers are created when using the result formats +c and critcl. The first returns the raw C code for the +parser, while the latter wraps it into a Tcl package using +CriTcl.

+

This makes the latter much easier to use than the former. On the other +hand, the former can be adapted to the users' requirements through a +multitude of options, allowing for things like usage of the parser +outside of a Tcl environment, something the critcl format +doesn't support. As such the c format is meant for more +advanced users, or users with special needs.

+

A disadvantage of all the parsers in this section is the need to run +them through a C compiler to make them actually executable. This is +not something everyone has the necessary tools for. The parsers in the +next section are for people under such restrictions.

+
Specialized parsers implemented in Tcl
+

As the parsers in this section are implemented in Tcl they are quite a +bit slower than anything from the previous section. On the other hand +this allows them to be used in pure-Tcl environments, or in +environments which allow only a limited set of binary packages. In the +latter case it will be advantageous to lobby for the inclusion of the +C-based runtime support (notes below) into the environment to reduce +the impact of Tcl's on the speed of these parsers.

+

The relevant formats are snit and oo. Both place their +result into a Tcl package containing a snit::type, or TclOO +class respectively.

+

Of the supporting runtime, which is the package pt::rde, the +user has to know nothing but that it does exist and that the parsers +are dependent on it. Knowledge of the API exported by the runtime for +the parsers' consumption is not required by the parsers' users.

+
Interpreted parsing implemented in Tcl
+

The last category, grammar interpretation. This means that an +interpreter for parsing expression grammars takes the description of +the grammar to parse input for, and uses it guide the parsing process. +This is the slowest of the available options, as the interpreter has +to continually run through the configured grammar, whereas the +specialized parsers of the previous sections have the relevant +knowledge about the grammar baked into them.

+

The only places where using interpretation make sense is where the +grammar for some input may be changed interactively by the user, as +the interpretation allows for quick turnaround after each change, +whereas the previous methods require the generation of a whole new +parser, which is not as fast. +On the other hand, wherever the grammar to use is fixed, the previous +methods are much more advantageous as the time to generate the parser +is minuscule compared to the time the parser code is in use.

+

The relevant result format is container. +It (quickly) generates grammar descriptions (instead of a full parser) +which match the API expected by ParserTools' grammar interpreter. +The latter is provided by the package pt::peg::interp.

+
+

All the parsers generated by critcl, snit, and +oo, and the grammar interpreter share a common API for access +to the actual parsing functionality, making them all +plug-compatible. +It is described in the Parser API specification document.

+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

For either an introduction to or the formal specification of the +language, please go and read the PEG Language Tutorial.

+

When used as a result-format this format supports the following +options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put the generated +text and the values of the other options. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated text.

+
+
+
+

JSON Grammar Exchange

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

For the formal specification of the JSON grammar exchange format, +please go and read The JSON Grammar Exchange Format.

+

When used as a result-format this format supports the following +options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-indented boolean
+

If this option is set the system will break the generated JSON across +lines and indent it according to its inner structure, with each key of +a dictionary on a separate line.

+

If the option is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
-aligned boolean
+

If this option is set the system will ensure that the values for the +keys in a dictionary are vertically aligned with each other, for a +nice table effect. +To make this work this also implies that -indented is set.

+

If the option is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+
+

C Parser Embedded In Tcl

+

The critcl format is executable code, a parser for the +grammar. It is a Tcl package with the actual parser implementation +written in C and embedded in Tcl via the critcl package.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-class string
+

The value of this option is the name of the class to generate, without +leading colons. +The default value is CLASS.

+

For a simple value X without colons, like CLASS, the parser +command will be X::X. Whereas for a namespaced value +X::Y the parser command will be X::Y.

+
-package string
+

The value of this option is the name of the package to generate. +The default value is PACKAGE.

+
+
+

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.

+
+
+

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.

+
+
+

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.

+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_astree.html Index: embedded/www/tcllib/files/modules/pt/pt_astree.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_astree.html @@ -0,0 +1,346 @@ + + +pt::ast - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::ast(n) 1.1 tcllib "Parser Tools"

+

Name

+

pt::ast - Abstract Syntax Tree Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +abstract syntax trees as managed by the Parser Tools, and specified in +section AST serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::ast verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of an abstract syntax tree and will throw an error if +that is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +AST serialization format.

+
::pt::ast verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of an abstract syntax tree and will +throw an error if that is not the case. The result of the command is +the empty string.

+

For the specification of canonical serializations see the section +AST serialization format.

+
::pt::ast canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of an abstract syntax and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained tree and return it as its result. If the input is +already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section AST serialization format.

+
::pt::ast print serial
+

This command assumes that the argument serial contains a valid +serialization of an abstract syntax tree and returns a string +containing that tree in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +AST serialization format.

+
::pt::ast bottomup cmdprefix ast
+

This command walks the abstract syntax tree ast from the bottom +up to the root, invoking the command prefix cmdprefix for each +node. This implies that the children of a node N are handled before N.

+

The command prefix has the signature

+
+
cmdprefix ast
+

I.e. it is invoked with the ast node the walk is currently at.

+

The result returned by the command prefix replaces ast in the +node it was a child of, allowing transformations of the tree.

+

This also means that for all inner node the contents of the children +elements are the results of the command prefix invoked for the +children of this node.

+
+
::pt::ast topdown cmdprefix pe
+

This command walks the abstract syntax tree ast from the root +down to the leaves, invoking the command prefix cmdprefix for +each node. This implies that the children of a node N are handled +after N.

+

The command prefix has the same signature as for bottomup, +see above.

+

The result returned by the command prefix is ignored.

+
::pt::ast equal seriala serialb
+

This command tests the two sbstract syntax trees seriala and +serialb for structural equality. The result of the command is a +boolean value. It will be set to true if the trees are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two trees are +pure Tcl lists.

+
::pt::ast terminal loc
+

This command command constructs the ast for a terminal node refering +to the position loc in the input, and returns it as the result +of the command.

+
::pt::ast nonterminal s start end ?child...?
+

This command command constructs the ast for a nonterminal node +refering to the symbol s covering the range of positions +start to end in the input, and the set of child nodes +child ..., from left right. The latter may be empty. The +constructed node is returned as the result of the command.

+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html Index: embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html @@ -0,0 +1,181 @@ + + +pt::cparam::configuration::critcl - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::cparam::configuration::critcl(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::cparam::configuration::critcl - C/PARAM, Canned configuration, Critcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::cparam::configuration::critcl ?1.0.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::cparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::cparam to generate +critcl-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::cparam::configuration::critcl def name cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of critcl-based parsers +whose class is name.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::cparam +(pt::peg::to::cparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_from_api.html Index: embedded/www/tcllib/files/modules/pt/pt_from_api.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_from_api.html @@ -0,0 +1,539 @@ + + +pt_import_api - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt_import_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_import_api - Parser Tools Import API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes two APIs. First the API shared by all packages +for the conversion of some other format into Parsing Expression +Grammars , and then the API shared by the packages which implement the +import plugins sitting on top of the conversion packages.

+

Its intended audience are people who wish to create their own +converter for some type of input, and/or an import plugin for their or +some other converter.

+

It resides in the Import section of the Core Layer of Parser Tools.

+

arch_core_import

+
+

Converter API

+

Any (grammar) import converter has to follow the rules set out below:

+
    +

  1. A converter is a package. Its name is arbitrary, however it is + recommended to put it under the ::pt::peg::from + namespace.

    2. +

  2. The package provides either a single Tcl command following the + API outlined below, or a class command whose instances follow + the same API. The commands which follow the API are called + converter commands.

    3. +

  3. A converter command has to provide the following single method + with the given signature and semantic. Converter commands + are allowed to provide more methods of their own, but not + less, and they may not provide different semantics for the + standardized method.

    +
    +
    CONVERTER convert text
    +

    This method has to accept some text, a parsing expression +grammar in some format. +The result of the method has to be the canonical serialization of a +parsing expression grammar, as specified in section +PEG serialization format, the result of reading and +converting the input text.

    +
    +
    4. +
+
+

Plugin API

+

Any (grammar) import plugin has to follow the rules set out below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + pt::peg::import::FOO, + where FOO is the name of the format the plugin will + accept input for.

    3. +

  3. The plugin can expect that the package + pt::peg::import::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    +

    It is recommended that a plugin does check for the presence of + this package.

    4. +

  4. The plugin can expect that a command named IncludeFile + is present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide a single command, in the global + namespace, with the signature shown below. Plugins are allowed + to provide more commands of their own, but not less, and they + may not provide different semantics for the standardized + command.

    +
    +
    ::import text
    +

    This command has to accept the a text containing a parsing expression +grammar in some format. The result of the command has to be the result +of the converter invoked by the plugin for the input grammar, the +canonical serialization of the parsing expression grammar contained in +the input.

    +
    +
    string text
    +

    This argument will contain the parsing expression grammar for which to +generate the serialization. +The specification of what a canonical serialization is can be +found in the section PEG serialization format.

    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of an invokation of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

Usage

+

To use a converter do

+
+    # Get the converter (single command here, not class)
+    package require the-converter-package
+    # Perform the conversion
+    set serial [theconverter convert $thegrammartext]
+    ... process the result ...
+
+

To use a plugin FOO do

+
+    # Get an import plugin manager
+    package require pt::peg::import
+    pt::peg::import I
+    # Run the plugin, and the converter inside.
+    set serial [I import serial $thegrammartext FOO]
+    ... process the result ...
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_introduction.html Index: embedded/www/tcllib/files/modules/pt/pt_introduction.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_introduction.html @@ -0,0 +1,291 @@ + + +pt_introduction - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt_introduction(n) 1 tcllib "Parser Tools"

+

Name

+

pt_introduction - Introduction to Parser Tools

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Welcome to the Parser Tools, a system for the creation and +manipulation of parsers and the grammars driving them.

+

What are your goals which drove you here ?

+
    +

  1. Do you simply wish to create a parser for some language ?

    +

    In that case have a look at our parser generator application, +pt, or, for a slightly deeper access, the package underneath it, +pt::pgen.

    2. +

  2. Do you wish to know more about the architecture of the system ?

    +

    This is described in the section +Parser Tools Architecture, below

    3. +

  3. Is your interest in the theoretical background upon which the packages +and tools are build ?

    +

    See the Introduction to Parsing Expression Grammars.

    4. +
+
+

Parser Tools Architecture

+

The system can be split into roughly three layers, as seen in the +figure below

+

architecture

+

These layers are, from high to low:

+
    +

  1. At the top we have the application and the packages using the packages +of the layer below to implement common usecases. One example is the +aforementioned pt::pgen which provides a parser generator.

    +

    The list of packages belonging to this layer can be found in section +User Packages

    2. +

  2. In this layer we have the packages which provide the core of the +functionality for the whole system. They are, in essence, a set of +blocks which can be combined in myriad ways, like Lego (tm). The +packages in the previous level are 'just' pre-fabricated combinations +to cover the most important use cases.

    +

    The list of packages belonging to this layer can be found in section +Core Packages

    3. +

  3. Last, but not least is the layer containing support packages providing +generic functionality which not necessarily belong into the module.

    +

    The list of packages belonging to this layer can be found in section +Support Packages

    4. +
+ +

Core Packages

+

This layer is further split into six sections handling the storage, +import, export, transformation, and execution of grammars, plus +grammar specific support packages.

+
+
Storage
+
+
pt::peg::container
+
+
+
Export
+
+
pt::peg::export
+
+
pt::peg::export::container
+
+
pt::peg::export::json
+
+
pt::peg::export::peg
+
+
pt::peg::to::container
+
+
pt::peg::to::json
+
+
pt::peg::to::peg
+
+
pt::peg::to::param
+
+
pt::peg::to::tclparam
+
+
pt::peg::to::cparam
+
+
+
Import
+
+
pt::peg::import
+
+
pt::peg::import::container
+
+
pt::peg::import::json
+
+
pt::peg::import::peg
+
+
pt::peg::from::container
+
+
pt::peg::from::json
+
+
pt::peg::from::peg
+
+
+
Transformation
+
+
Execution
+
+
pt::peg::interp
+
+
pt::rde
+
+
+
Support
+
+
pt::tclparam::configuration::snit
+
+
pt::tclparam::configuration::tcloo
+
+
pt::cparam::configuration::critcl
+
+
pt::ast
+
+
pt::pe
+
+
pt::peg
+
+
+
+
+

Support Packages

+
+
pt::peg::container::peg
+
+
text::write
+
+
configuration
+
+
paths
+
+
char
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_json_language.html Index: embedded/www/tcllib/files/modules/pt/pt_json_language.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_json_language.html @@ -0,0 +1,537 @@ + + +pt::json_language - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::json_language(n) 1 tcllib "Parser Tools"

+

Name

+

pt::json_language - The JSON Grammar Exchange Format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_param.html Index: embedded/www/tcllib/files/modules/pt/pt_param.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_param.html @@ -0,0 +1,585 @@ + + +pt::param - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::param(n) 1 tcllib "Parser Tools"

+

Name

+

pt::param - PackRat Machine Specification

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the PackRat Machine (short: PARAM), a virtual +machine geared towards the support of recursive descent parsers, +especially packrat parsers. Towards this end it has features like the +caching and reuse of partial results, the caching of the encountered +input, and the ability to backtrack in both input and AST creation.

+

This document specifies the machine in terms of its architectural +state and instruction set.

+
+

Architectural State

+

Any PARAM implementation has to manage at least the following state:

+
+
Input (IN)
+

This is the channel the characters to process are read from.

+

This part of the machine's state is used and modified by the +instructions defined in the section Input Handling.

+
Current Character (CC)
+

The character from the input currently tested against its +possible alternatives.

+

This part of the machine's state is used and modified by the +instructions defined in the section Character Processing.

+
Current Location (CL)
+

The location of the current character in the input, as +offset relative to the beginning of the input. Character offsets are +counted from 0.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Character Processing, +Location Handling, and Nonterminal Execution.

+
Location Stack (LS)
+

A stack of locations in the input, saved for possible +backtracking.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Character Processing, +Location Handling, and Nonterminal Execution.

+
Status (ST)
+

The status of the last attempt of testing the input, indicating +either success or failure.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Status Control, +Character Processing, and Nonterminal Execution.

+
Semantic Value (SV)
+

The current semantic value, either empty, or a node for AST +constructed from the input.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
AST Reduction Stack (ARS)
+

The stack of partial ASTs constructed during the processing of +nonterminal symbols.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
AST Stack (AS)
+

The stack of reduction stacks, saved for possible backtracking.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
Error Status (ER)
+

The machine's current knowledge of errors. This is either empty, or +set to a pair of location in the input and the set of messages for +that location.

+

Note that this part of the machine's state can be set even if +the last test of the current character was successful. For +example, the *-operator (matching a sub-expression zero or more times) +in a PEG is always successful, even if it encounters a problem further +in the input and has to backtrack. Such problems must not be forgotten +when continuing the parsing.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Error Handling, +Character Processing, and Nonterminal Execution.

+
Error Stack (ES)
+

The stack of error stati, saved for backtracking. This enables the +machine to merge current and older error stati when performing +backtracking in choices after an failed match.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Error Handling, +Character Processing, and Nonterminal Execution.

+
Nonterminal Cache (NC)
+

A cache of machine states keyed by pairs name of nonterminal symbol +and location in the input. Each pair (N, L) is associated with a +4-tuple holding the values to use for CL, ST, SV, and ER after the +nonterminal N was parsed starting from the location L. +It is a performance aid for backtracking parsers, allowing them to +avoid an expensive reparsing of complex nonterminal symbols if they +have been encountered before at a given location.

+

The key location is where machine started the attempt to match the +named nonterminal symbol, and the location in the saved 4-tuple is +where machine ended up after the attempt completed, independent of the +success of the attempt.

+

This part of the machine's state is used and modified by the +instructions defined in the section Nonterminal Execution.

+
Terminal Cache (TC)
+

A cache of characters read from IN, with their location in IN as pair +of line and column, keyed by the location in IN, this time as +character offset from the beginning of IN. +It is a performance aid for backtracking parsers, allowing them to +avoid a possibly expensive rereading of characters from IN, or even +enabling backtracking at, i.e. in the case of IN not randomly +seekable.

+

This part of the machine's state is used and modified by the +instructions defined in the section Input Handling.

+
+
+

Instruction Set

+

With the machine's architectural state specified it is now possible to +specify the instruction set operating on that state and to be +implemented by any realization of the PARAM. The 37 instructions are +grouped roughly by the state they influence and/or query during their +execution.

+

Input Handling

+

The instructions in this section mainly access IN, pulling the +characters to process into the machine.

+
+
input_next msg
+

This method reads the next character, i.e. the character after CL, +from IN. If successful this character becomes CC, CL is advanced by +one, ES is cleared, and the operation is recorded as a success in ST.

+

The operation may read the character from IN if the next character +is not yet known to TC. If successful the new character is stored in +TC, with its location (line, column), and the operation otherwise +behaves as specified above. Future reads from the same location, +possible due to backtracking, will then be satisfied from TC instead +of IN.

+

If, on the other hand, the end of IN was reached, the operation is +recorded as failed in ST, CL is left unchanged, and the pair of CL and +msg becomes the new ES.

+
+
+

Character Processing

+

The instructions in this section mainly access CC, testing it against +character classes, ranges, and individual characters.

+
+
test_alnum
+

This instruction implements the special PE operator "alnum", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_alpha
+

This instruction implements the special PE operator "alpha", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_ascii
+

This instruction implements the special PE operator "ascii", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_char char
+

This instruction implements the character matching operator, i.e. it +checks if CC is char.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_ddigit
+

This instruction implements the special PE operator "ddigit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_digit
+

This instruction implements the special PE operator "digit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_graph
+

This instruction implements the special PE operator "graph", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_lower
+

This instruction implements the special PE operator "lower", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_print
+

This instruction implements the special PE operator "print", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_punct
+

This instruction implements the special PE operator "punct", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_range chars chare
+

This instruction implements the range matching operator, i.e. it +checks if CC falls into the interval of characters spanned up by the +two characters from chars to chare, both inclusive.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_space
+

This instruction implements the special PE operator "space", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_upper
+

This instruction implements the special PE operator "upper", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_wordchar
+

This instruction implements the special PE operator "wordchar", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_xdigit
+

This instruction implements the special PE operator "xdigit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
+
+

Error Handling

+

The instructions in this section mainly access ER and ES.

+
+
error_clear
+

This instruction clears ER.

+
error_push
+

This instruction makes a copy of ER and pushes it on ES.

+
error_pop_merge
+

This instruction takes the topmost entry of ES and merges the error +status it contains with ES, making the result the new ES.

+

The merge is governed by four rules, with the merge result

+
    +

  1. Empty if both states are empty.

    2. +

  2. The non-empty state if only one of the two states is non-empty.

    3. +

  3. The state with the larger location, if the two states specify +different locations.

    4. +

  4. The pair of the location shared by the two states, and the set-union +of their messages for states at the same location.

    5. +
+
error_nonterminal symbol
+

This is a guarded instruction. It does nothing if either ES is empty, +or if the location in ES is not just past the last location saved in +LS. Otherwise it sets the pair of that location and the nonterminal +symbol as the new ES.

+

Note: In the above "just past" means "that location plus one", +or also "the location of the next character after that location".

+
+
+

Status Control

+

The instructions in this section directly manipulate ST.

+
+
status_ok
+

This instruction sets ST to true, recording a success.

+
status_fail
+

This instruction sets ST to false, recording a failure.

+
status_negate
+

This instruction negates ST, turning a failure into a success and vice +versa.

+
+
+

Location Handling

+

The instructions in this section access CL and LS.

+
+
loc_push
+

This instruction makes a copy of CL and pushes it on LS.

+
loc_pop_discard
+

This instructions pops the last saved location from LS.

+
loc_pop_rewind
+

This instruction pops the last saved location from LS and restores it +as CL.

+
+
+

Nonterminal Execution

+

The instructions in this section access and manipulate NC.

+
+
symbol_restore symbol
+

This instruction checks if NC contains data for the nonterminal +symbol at CL, or not. The result of the instruction is a boolean +flag, with True indicating that data was found in the +cache. In that case the instruction has further updated the +architectural state of the machine with the cached information, namely +CL, ST, ER, and SV.

+

The method with which the instruction's result is transformed into +control flow is left undefined and the responsibility of the +implementation.

+
symbol_save symbol
+

This instructions saves the current settings of CL, ST, ER, and SV in +NC, using the pair of nonterminal symbol and the last location +saved in LS as key.

+
+
+

Value Construction

+

The instructions in this section manipulate SV.

+
+
value_clear
+

This instruction clears SV.

+
value_leaf symbol
+

This instruction constructs an AST node for symbol covering the +range of IN from one character after the last location saved on LS to +CL and stores it in SV. ...

+
value_reduce symbol
+

This instruction generally behaves like value_nonterminal_leaf, +except that it takes all AST nodes on ARS, if any, and makes them the +children of the new node, with the last node saved on ARS becoming the +right-most / last child. Note that ARS is not modfied by this +operation.

+
+
+

AST Construction

+

The instructions in this section manipulate ARS and AS.

+
+
ast_value_push
+

This instruction makes a copy of SV and pushes it on ARS.

+
ast_push
+

This instruction pushes the current state of ARS on AS and then clears +ARS.

+
ast_pop_rewind
+

This instruction pops the last entry saved on AS and restores it as +the new state of ARS.

+
ast_pop_discard
+

This instruction pops the last entry saved on AS.

+
+
+

Control Flow

+

Normally this section would contain the specifications of the control +flow instructions of the PARAM, i.e. (un)conditional jumps and the +like. However, this part of the PARAM is intentionally left +unspecified. This allows the implementations to freely choose how to +implement control flow.

+

The implementation of this machine in Parser Tools, i.e the package +pt::rde, is not only coded in Tcl, but also relies on Tcl +commands to provide it with control flow (instructions).

+
+
+

Interaction of the Instructions with the Architectural State

+
+Instruction		Inputs				Outputs
+======================= =======================		====================
+ast_pop_discard		AS			->	AS
+ast_pop_rewind		AS			->	AS, ARS
+ast_push		ARS, AS			->	AS
+ast_value_push		SV, ARS			->	ARS
+======================= =======================		====================
+error_clear		-			->	ER
+error_nonterminal sym	ER, LS			->	ER
+error_pop_merge   	ES, ER			->	ER
+error_push		ES, ER			->	ES
+======================= =======================		====================
+input_next msg		IN			->	TC, CL, CC, ST, ER
+======================= =======================		====================
+loc_pop_discard		LS			->	LS
+loc_pop_rewind		LS			->	LS, CL
+loc_push		CL, LS			->	LS
+======================= =======================		====================
+status_fail		-			->	ST
+status_negate		ST			->	ST
+status_ok		-			->	ST
+======================= =======================		====================
+symbol_restore sym	NC			->	CL, ST, ER, SV
+symbol_save    sym	CL, ST, ER, SV LS	->	NC
+======================= =======================		====================
+test_alnum  		CC			->	ST, ER
+test_alpha		CC			->	ST, ER
+test_ascii		CC			->	ST, ER
+test_char char		CC			->	ST, ER
+test_ddigit		CC			->	ST, ER
+test_digit		CC			->	ST, ER
+test_graph		CC			->	ST, ER
+test_lower		CC			->	ST, ER
+test_print		CC			->	ST, ER
+test_punct		CC			->	ST, ER
+test_range chars chare	CC			->	ST, ER
+test_space		CC			->	ST, ER
+test_upper		CC			->	ST, ER
+test_wordchar		CC			->	ST, ER
+test_xdigit		CC			->	ST, ER
+======================= =======================		====================
+value_clear		-			->	SV
+value_leaf symbol	LS, CL			->	SV
+value_reduce symbol	ARS, LS, CL		->	SV
+======================= =======================		====================
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_parser_api.html Index: embedded/www/tcllib/files/modules/pt/pt_parser_api.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_parser_api.html @@ -0,0 +1,481 @@ + + +pt_parser_api - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt_parser_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_parser_api - Parser API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes the API shared by the grammar interpreter +provided by the package pt::peg::interp and the parsers +generated by the pt application for the result formats +critcl, snit, and oo regarding access +to the actual parsing functionality.

+

Its intended audience are people who wish to create a parser for some +language of theirs and then use that parser within a Tcl-based package +or application.

+

It resides in the User Layer of Parser Tools.

+

arch_user_pkg

+
+

Class API

+
+
className ?objectName?
+

The class command constructs parser instances, i.e. objects. The +result of the command is the fully-qualified name of the instance +command.

+

If no objectName is specified the class will generate and use an +automatic name. If the objectName was specified, but is not +fully qualified the command will be created in the curent namespace.

+
+
+

Instance API

+

All parser instances provide at least the methods shown below:

+
+
objectName destroy
+

This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command.

+

The result of the command is the empty string.

+
objectName parse chan
+

This method runs the parser using the contents of chan as input +(starting at the current location in the channel), until parsing is +not possible anymore, either because parsing has completed, or run +into a syntax error.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+

Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +AST serialization format. +As a plain nested Tcl-list it can then be processed with any Tcl +commands the user likes, doing transformations, semantic checks, etc. +To help in this the package pt::ast provides a set of +convenience commands for validation of the tree's basic structure, +printing it for debugging, and walking it either from the bottom up, +or top down.

+

When encountering a syntax error the command will throw an error instead. +This error will be a 4-element Tcl-list, containing, in the order +listed below:

+
    +

  1. The string pt::rde identifying it as parser runtime error.

    2. +

  2. The location of the parse error, as character offset from the +beginning of the parsed input.

    3. +

  3. The location of parse error, now as a 2-element list containing +line-number and column in the line.

    4. +

  4. A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. + For the specification of atomic parsing expressions please see the +section PE serialization format.

    5. +
+
objectName parset text
+

This method runs the parser using the string in text as input. +In all other ways it behaves like the method parse, shown +above.

+
+
+

Usage

+

A generated parser is used like this

+
+    package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'.
+    set parser [the-parser-class]
+    set ast [$parser parse $channel]
+    ... process the abstract syntax tree ...
+
+

When using a grammar interpreter for parsing some differences creep in

+
+    package require the-grammar-package ;# Generated by result-format 'container' of 'pt'.
+    set grammar [the-grammar-class]
+    package require pt::peg::interp
+    set parser [pt::peg::interp]
+    $parser use $grammar
+    set ast [$parser parse $channel]
+    $parser destroy
+    ... process the abstract syntax tree ...
+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_container.html @@ -0,0 +1,664 @@ + + +pt::peg::container - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::container - PEG Storage

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a container class for parsing expression +grammars, with each instance storing a single grammar and allowing the +user to manipulate and query its definition.

+

It resides in the Storage section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_container

+

The other two pillars are, as shown above

+
    +

  1. PEG Import, and

    2. +

  2. PEG Export

    3. +
+

Packages related to this are:

+
+
pt::rde
+

This package provides an implementation of PARAM, a virtual machine +for the parsing of a channel, geared towards the needs of handling +PEGs.

+
pt::peg::interp
+

This package implements an interpreter for PEGs on top of the virtual +machine provided by pt::peg::rde

+
+

Class API

+

The package exports the API described here.

+
+
::pt::peg objectName ?=|:=|<--|as|deserialize src?
+

The command creates a new container object for a parsing expression +grammar and returns the fully qualified name of the object command as +its result. The API of this object command is described in the section +Object API. It may be used to invoke various operations on +the object.

+

The new container will be empty if no src is specified. Otherwise +it will contain a copy of the grammar contained in the src. +All operators except deserialize interpret src as a +container object command. The deserialize operator interprets +src as the serialization of a parsing expression grammar +instead, as specified in section PEG serialization format.

+

An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is valid, but not +useful.

+
+
+

Object API

+

All objects created by this package provide the following methods for +the manipulation and querying of their contents:

+
+
objectName destroy
+

This method destroys the object, releasing all claimed memory, and +deleting the associated object command.

+
objectName clear
+

This method resets the object to contain the empty grammar. It does +not destroy the object itself.

+
objectName importer
+

This method returns the import manager object currently attached to +the container, if any.

+
objectName importer object
+

This method attaches the object as import manager to the +container, and returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the table of contents contained in +the text, assuming the given format.

+
objectName exporter
+

This method returns the export manager object currently attached to +the container, if any.

+
objectName exporter object
+

This method attaches the object as export manager to the +container, and returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding table of contents stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the table of contents from which to generate the text.

+
objectName = source
+

This method assigns the contents of the PEG object source to +ourselves, overwriting the existing definition. This is the assignment +operator for grammars.

+

This operation is in effect equivalent to

+
+    objectName deserialize = [source serialize]
+
+
+
objectName --> destination
+

This method assigns our contents to the PEG object destination, +overwriting the existing definition. This is the reverse assignment +operator for grammars.

+

This operation is in effect equivalent to

+
+    destination deserialize = [objectName serialize]
+
+
+
objectName serialize ?format?
+

This method returns our grammar in some textual form usable for +transfer, persistent storage, etc. If no format is not specified +the returned result is the canonical serialization of the grammar, as +specified in the section PEG serialization format.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. In that case the method will fail +with an error if the container has no export manager attached to it.

+
objectName deserialize = data ?format?
+

This is the complementary method to serialize. +It replaces the current definition with the grammar contained in the +data. If no format was specified it is assumed to be the +regular serialization of a grammar, as specified in the section +PEG serialization format

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case the method will fail with an error if the container has +no import manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the grammar in the data to its +contents instead of replacing it. +The method will fail with an error and leave the grammar unchanged if +merging is not possible, i.e. would produce an invalid grammar.

+

The result of the method is the empty string.

+
objectName start
+

This method returns the current start expression of the grammar.

+
objectName start pe
+

This method defines the start expression of the grammar. It +replaces the current start expression with the parsing expression +pe, and returns the new start expression.

+

The method will fail with an error and leave the grammar unchanged if +pe does not contain a valid parsing expression as specified in +the section PE serialization format.

+
objectName nonterminals
+

This method returns the set of all nonterminal symbols known to the +grammar.

+
objectName modes
+

This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their semantic modes.

+
objectName modes dict
+

This method takes a dictionary mapping a set of nonterminal symbols +known to the grammar to their semantic modes, and returns the new full +mapping of nonterminal symbols to semantic modes.

+

The method will fail with an error if any of the nonterminal symbols +in the dictionary is not known to the grammar, or the empty string, +i.e. an invalid nonterminal symbol, or if any the chosen modes +is not one of the legal values.

+
objectName rules
+

This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their parsing expressions (right-hand +sides).

+
objectName rules dict
+

This method takes a dictionary mapping a set of nonterminal symbols +known to the grammar to their parsing expressions (right-hand sides), +and returns the new full mapping of nonterminal symbols to parsing +expressions.

+

The method will fail with an error any of the nonterminal symbols in +the dictionary is not known to the grammar, or the empty string, +i.e. an invalid nonterminal symbol, or any of the chosen parsing +expressions is not a valid parsing expression as specified in the +section PE serialization format.

+
objectName add ?nt...?
+

This method adds the nonterminal symbols nt, etc. to the +grammar, and defines default semantic mode and expression for it +(value and epsilon respectively). +The method returns the empty string as its result.

+

The method will fail with an error and leaves the grammar unchanged if +any of the nonterminal symbols are either already defined in our +grammar, or are the empty string (an invalid nonterminal symbol).

+

The method does nothing if no symbol was specified as argument.

+
objectName remove ?nt...?
+

This method removes the named nonterminal symbols nt, etc. from +the set of nonterminal symbols known to our grammar. +The method returns the empty string as its result.

+

The method will fail with an error and leave the grammar unchanged if +any of the nonterminal symbols is not known to the grammar, or is the +empty string, i.e. an invalid nonterminal symbol.

+
objectName exists nt
+

This method tests whether the nonterminal symbol nt is known +to our grammar or not. +The result is a boolean value. It will be set to true if +nt is known, and false otherwise.

+

The method will fail with an error if nt is the empty string, +i.e. an invalid nonterminal symbol.

+
objectName rename ntold ntnew
+

This method renames the nonterminal symbol ntold to ntnew. +The method returns the empty string as its result.

+

The method will fail with an error and leave the grammar unchanged if +either ntold is not known to the grammar, or ntnew is +already known, or any of them is the empty string, i.e. an invalid +nonterminal symbol.

+
objectName mode nt
+

This method returns the current semantic mode for the nonterminal +symbol nt.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol.

+
objectName mode nt mode
+

This mode sets the semantic mode for the nonterminal symbol nt, +and returns the new mode. +The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +the chosen mode is not one of the legal values.

+

The following modes are legal:

+
+
value
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

+
leaf
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

+
void
+

The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

+
+
objectName rule nt
+

This method returns the current parsing expression (right-hand side) +for the nonterminal symbol nt.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol.

+
objectName rule nt pe
+

This method set the parsing expression (right-hand side) of the +nonterminal nt to pe, and returns the new parsing +expression.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +pe does not contain a valid parsing expression as specified in +the section PE serialization format.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html @@ -0,0 +1,163 @@ + + +pt::peg::container::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::container::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::container::peg - PEG Storage. Canned PEG grammar specification

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit
    • +
  • package require pt::peg::container::peg ?1?
    • +
  • package require pt::peg::container
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a sub-type of pt::peg::container which +is preloaded with a parsing expression grammar describing a textual +format for parsing expression grammars.

+

The sub-type provides the exact same API as +pt::peg::container. Instead of duplicating its contents the +reader is asked to read the referenced document.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_export.html @@ -0,0 +1,536 @@ + + +pt::peg::export - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::export(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export - PEG Export

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a manager for parsing expression grammars, with +each instance handling a set of plugins for the export of them to +other formats, i.e. their conversion to, for example nroff, +HTML, etc.

+

It resides in the Export section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_export

+

The other two pillars are, as shown above

+
    +

  1. PEG Import, and

    2. +

  2. PEG Storage

    3. +
+

For information about the data structure which is the major input to +the manager objects provided by this package see the section +PEG serialization format.

+

The plugin system of this class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable GRAMMAR_PEG_EXPORT_PLUGINS,

    2. +

  2. the environment variable GRAMMAR_PEG_PLUGINS,

    3. +

  3. the environment variable GRAMMAR_PLUGINS,

    4. +

  4. the path "~/.grammar/peg/export/plugin"

    5. +

  5. the path "~/.grammar/peg/plugin"

    6. +

  6. the path "~/.grammar/plugin"

    7. +

  7. the path "~/.grammar/peg/export/plugins"

    8. +

  8. the path "~/.grammar/peg/plugins"

    9. +

  9. the path "~/.grammar/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using the Windows(tm) operating system.

+

The whole system is delivered with three predefined export plugins, +namely

+
+
container
+

See PEG Export Plugin. To CONTAINER format for details.

+
json
+

See PEG Export Plugin. To JSON format for details.

+
peg
+

See PEG Export Plugin. To PEG format for details.

+
+

For readers wishing to write their own export plugin for some format, +i.e. plugin writers, reading and understanding the +Parser Tools Export API specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail.

+
+

API

+

Package commands

+
+
::pt::peg::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::pt::peg::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a parsing expression +grammar stored in serial and converts it to the specified +format, using the export plugin for the format. This will fail +with an error if no plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to text.

+

The specification of what a canonical serialization is can be +found in the section PEG serialization format.

+

The plugin has to conform to the interface documented in the +Parser Tools Export API specification.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +parsing expression grammar. It invokes that method, feeds the result +into export serial and returns the resulting string as its +own result.

+
objectName configuration names
+

This method returns a list containing the names of all configuration +options currently known to the object.

+
objectName configuration get
+

This method returns a dictionary containing the names and values of +all configuration options currently known to the object.

+
objectName configuration set name ?value?
+

This method sets the configuration option name to the +specified value and returns the new value of the option.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that these configuration options and their values are simply +passed to a plugin when the actual export is performed. It is the +plugin which checks the validity, not the manager.

+
objectName configuration unset pattern...
+

This method unsets all configuration options matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration options.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html @@ -0,0 +1,549 @@ + + +pt::peg::export::container - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::export::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::container - PEG Export Plugin. Write CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::container ?1?
    • +
  • package require pt::peg::to::container
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of CONTAINER markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::container.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::container and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates CONTAINER markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The CONTAINER export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
enum mode
+

The value of this configuration variable controls which methods of +pt::peg instances the plugin will use to specify the +grammar. There are two legal values

+
+
bulk
+

In this mode the methods start, add, modes, +and rules are used to specify the grammar in a bulk manner, +i.e. as a set of nonterminal symbols, and two dictionaries mapping +from the symbols to their semantic modes and parsing expressions.

+

This mode is the default.

+
incremental
+

In this mode the methods start, add, mode, +and rule are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands.

+
+
string template
+

If this configuration variable is set it is assumed to contain a +string into which to put the generated code and other configuration +data. The various locations are expected to be specified with the +following placeholders:

+
+
@user@
+

To be replaced with the value of the configuration variable user.

+
@format@
+

To be replaced with the the constant CONTAINER.

+
@file@
+

To be replaced with the value of the configuration variable file.

+
@name@
+

To be replaced with the value of the configuration variable name.

+
@mode@
+

To be replaced with the value of the configuration variable mode.

+
@code@
+

To be replaced with the generated code.

+
+

If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "@code@".

+
+

Note that this plugin may ignore the standard configuration +variables user, format, file, and their values, +depending on the chosen template.

+

The content of the standard configuration variable name, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name a_pe_grammar.

+
+

Grammar Container

+

The container format is another form of describing parsing +expression grammars. While data in this format is executable it does +not constitute a parser for the grammar. It always has to be used in +conjunction with the package pt::peg::interp, a grammar +interpreter.

+

The format represents grammars by a snit::type, i.e. class, +whose instances are API-compatible to the instances of the +pt::peg::container package, and which are preloaded with the +grammar in question.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible CONTAINER serialization for it is

+
+snit::type a_pe_grammar {
+    constructor {} {
+        install myg using pt::peg::container ${selfns}::G
+        $myg start {n Expression}
+        $myg add   AddOp Digit Expression Factor MulOp Number Sign Term
+        $myg modes {
+            AddOp      value
+            Digit      value
+            Expression value
+            Factor     value
+            MulOp      value
+            Number     value
+            Sign       value
+            Term       value
+        }
+        $myg rules {
+            AddOp      {/ {t -} {t +}}
+            Digit      {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
+            Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
+            Factor     {x {n Term} {* {x {n AddOp} {n Term}}}}
+            MulOp      {/ {t *} {t /}}
+            Number     {x {? {n Sign}} {+ {n Digit}}}
+            Sign       {/ {t -} {t +}}
+            Term       {n Number}
+        }
+        return
+    }
+    component myg
+    delegate method * to myg
+}
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html @@ -0,0 +1,602 @@ + + +pt::peg::export::json - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::export::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::json - PEG Export Plugin. Write JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::json ?1?
    • +
  • package require pt::peg::to::json
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of JSON markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::json.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::json and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates JSON markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and name, and +their values.

+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html @@ -0,0 +1,592 @@ + + +pt::peg::export::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::export::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::peg - PEG Export Plugin. Write PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::peg ?1?
    • +
  • package require pt::peg::to::peg
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of PEG markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::peg.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::peg and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates PEG markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The PEG export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string template
+

If this configuration variable is set it is assumed to contain a +string into which to put the generated text and other configuration +data. The various locations are expected to be specified with the +following placeholders:

+
+
@user@
+

To be replaced with the value of the configuration variable user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the configuration variable file.

+
@name@
+

To be replaced with the value of the configuration variable name.

+
@code@
+

To be replaced with the generated text.

+
+

If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "@code@".

+
+

Note that this plugin may ignore the standard configuration +variables user, format, file, and their values, +depending on the chosen template.

+

The content of the standard configuration variable name, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name a_pe_grammar.

+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- END SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG"   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:   END             <- "END"   WHITESPACE ;
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html @@ -0,0 +1,161 @@ + + +pt::peg::from::container - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::from::container(n) 0 tcllib "Parser Tools"

+

Name

+

pt::peg::from::container - PEG Conversion. From CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package does not exist. +There is no need for it. +The CONTAINER format for parsing expression grammars is a piece of Tcl +code which, then sourced, provides a class whose instances have the +grammar we wish to import loaded. +Another way of looking at this is, the CONTAINER output is its own +import package.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html @@ -0,0 +1,570 @@ + + +pt::peg::from::json - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::from::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::from::json - PEG Conversion. Read JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::from::json ?1?
    • +
  • package require pt::peg
    • +
  • package require json
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from JSON markup to +parsing expression grammars.

+

It resides in the Import section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the import manager provided by +pt::peg::import. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +pt::peg::import::json sitting between converter +and import manager.

+

arch_core_iplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Import API +specification.

+
+
pt::peg::from::json convert text
+

This command takes the JSON markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html @@ -0,0 +1,550 @@ + + +pt::peg::from::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::from::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::from::peg - PEG Conversion. Read PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::from::peg ?1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from PEG markup to +parsing expression grammars.

+

It resides in the Import section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the import manager provided by +pt::peg::import. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +pt::peg::import::peg sitting between converter +and import manager.

+

arch_core_iplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Import API +specification.

+
+
pt::peg::from::peg convert text
+

This command takes the PEG markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- END SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG"   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:   END             <- "END"   WHITESPACE ;
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_import.html @@ -0,0 +1,552 @@ + + +pt::peg::import - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::import(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import - PEG Import

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a manager for parsing expression grammars, with +each instance handling a set of plugins for the import of them from +other formats, i.e. their conversion from, for example peg, +container, json, etc.

+

It resides in the Import section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_import

+

The other two pillars are, as shown above

+
    +

  1. PEG Export, and

    2. +

  2. PEG Storage

    3. +
+

For information about the data structure which is the major output of +the manager objects provided by this package see the section +PEG serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable GRAMMAR_PEG_IMPORT_PLUGINS,

    2. +

  2. the environment variable GRAMMAR_PEG_PLUGINS,

    3. +

  3. the environment variable GRAMMAR_PLUGINS,

    4. +

  4. the path "~/.grammar/peg/import/plugin"

    5. +

  5. the path "~/.grammar/peg/plugin"

    6. +

  6. the path "~/.grammar/plugin"

    7. +

  7. the path "~/.grammar/peg/import/plugins"

    8. +

  8. the path "~/.grammar/peg/plugins"

    9. +

  9. the path "~/.grammar/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using the Windows(tm) operating system.

+

The whole system is delivered with three predefined import plugins, +namely

+
+
container
+

See PEG Import Plugin. From CONTAINER format for details.

+
json
+

See PEG Import Plugin. From JSON format for details.

+
peg
+

See PEG Import Plugin. From PEG format for details.

+
+

For readers wishing to write their own import plugin for some format, +i.e. plugin writers, reading and understanding the +Parser Tools Impport API specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail.

+
+

API

+

Package commands

+
+
::pt::peg::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::pt::peg::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a parsing expression +grammar using the import plugin for the format. An error is thrown if +no plugin could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to text.

+

The specification of what a canonical serialization is can be +found in the section PEG serialization format.

+

The plugin has to conform to the interface documented in the +Parser Tools Import API specification.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +parsing expression grammar. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html @@ -0,0 +1,161 @@ + + +pt::peg::import::container - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::import::container(n) 0 tcllib "Parser Tools"

+

Name

+

pt::peg::import::container - PEG Import Plugin. From CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package does not exist. +There is no need for it. +The CONTAINER format for parsing expression grammars is a piece of Tcl +code which, then sourced, provides a class whose instances have the +grammar we wish to import loaded. +Another way of looking at this is, the CONTAINER output is its own +import package.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html @@ -0,0 +1,578 @@ + + +pt::peg::import::json - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::import::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import::json - PEG Import Plugin. Read JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::import::json ?1?
    • +
  • package require pt::peg::to::json
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar import plugin +processing JSON markup.

+

It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::import, the import +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::from::json.

+

arch_core_iplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::import and the import manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::from::json and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Import API +specification.

+
+
import text
+

This command takes the JSON markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html @@ -0,0 +1,560 @@ + + +pt::peg::import::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::import::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import::peg - PEG Import Plugin. Read PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::import::peg ?1?
    • +
  • package require pt::peg::to::peg
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar import plugin +processing PEG markup.

+

It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::import, the import +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::from::peg.

+

arch_core_iplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::import and the import manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::from::peg and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Import API +specification.

+
+
import text
+

This command takes the PEG markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- END SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG"   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:   END             <- "END"   WHITESPACE ;
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_interp.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_interp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_interp.html @@ -0,0 +1,478 @@ + + +pt::peg::interp - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::interp(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::interp - Interpreter for parsing expression grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::interp ?1?
    • +
  • package require pt::rde ?1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a class whose instances are Packrat parsers +configurable with a parsing expression grammar. The grammar is +executed directly, i.e. interpreted, with the underlying runtime +provided by the package pt::rde, basing everything on the +PARAM.

+

Like the supporting runtime this package resides in the Execution +section of the Core Layer of Parser Tools.

+

arch_core_transform

+

The interpreted grammar is copied from an instance of pt::peg::container, or anything providing the same API, like the +container classes created by pt::peg::to::container or the +associated export plugin pt::peg::export::container.

+

Class API

+

The package exports the API described here.

+
+
::pt::peg::interpreter objectName grammar
+

The command creates a new parser object and returns the fully +qualified name of the object command as its result. The API of this +object command is described in the section Object API. It +may be used to invoke various operations on the object.

+

This new parser is configured for the execution of an empty PEG. To +configure the object for any other PEG use the method use of +the Object API.

+
+
+

Object API

+

All objects created by this package provide the following methods.

+
+
objectName use grammar
+

This method configures the grammar interpreter / parser for the +execution of the PEG stored in grammar, an object which is +API-compatible to instances of pt::peg::container. The +parser copies the relevant information of the grammar, and does +not take ownership of the object.

+

The information of any previously used grammar is overwritten.

+

The result of the method the empty string.

+
objectName destroy
+

This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command.

+

The result of the command is the empty string.

+
objectName parse chan
+

This method runs the parser using the contents of chan as input +(starting at the current location in the channel), until parsing is +not possible anymore, either because parsing has completed, or run +into a syntax error.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+

Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +AST serialization format. +As a plain nested Tcl-list it can then be processed with any Tcl +commands the user likes, doing transformations, semantic checks, etc. +To help in this the package pt::ast provides a set of +convenience commands for validation of the tree's basic structure, +printing it for debugging, and walking it either from the bottom up, +or top down.

+

When encountering a syntax error the command will throw an error instead. +This error will be a 4-element Tcl-list, containing, in the order +listed below:

+
    +

  1. The string pt::rde identifying it as parser runtime error.

    2. +

  2. The location of the parse error, as character offset from the +beginning of the parsed input.

    3. +

  3. The location of parse error, now as a 2-element list containing +line-number and column in the line.

    4. +

  4. A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. + For the specification of atomic parsing expressions please see the +section PE serialization format.

    5. +
+
objectName parset text
+

This method runs the parser using the string in text as input. +In all other ways it behaves like the method parse, shown +above.

+
+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html @@ -0,0 +1,267 @@ + + +pt::pegrammar - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::pegrammar(n) 1 tcllib "Parser Tools"

+

Name

+

pt::pegrammar - Introduction to Parsing Expression Grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the introduction to Parsing Expression Grammars +(short: PEG), the formalism used by the Parser Tools. +It is assumed that the reader has a basic knowledge of parsing theory, +i.e. Context-Free Grammars (short: CFG), +languages, and associated terms like LL(k), +LR(k), terminal and nonterminal symbols, +etc. +We do not intend to recapitulate such basic definitions or terms like +useful, reachable, (left/right) recursive, +nullable, first/last/follow sets, etc. +Please see the References at the end instead if you are in +need of places and books which provide such background information.

+

PEGs are formally very similar to CFGs, with terminal and nonterminal +symbols, start symbol, and rules defining the structure of each +nonterminal symbol. +The main difference lies in the choice(sic!) of choice +operators. Where CFGs use an unordered choice to represent +alternatives PEGs use prioritized choice. Which is fancy way +of saying that a parser has to try the first alternative first and can +try the other alternatives if only if it fails for the first, and so +on.

+

On the CFG side this gives rise to LL(k) and LR(k) for making the +choice deterministic with a bounded lookahead of k +terminal symbols, where LL is in essence topdown aka +recursive descent parsing, and LR bottomup aka +shift reduce parsing.

+

On the PEG side we can parse input with recursive descent and +backtracking of failed choices, the latter of which amounts to +unlimited lookahead. +By additionally recording the success or failure of nonterminals at +the specific locations they were tried at and reusing this information +after backtracking we can avoid the exponential blowup of running time +usually associated with backtracking and keep the parsing linear. The +memory requirements are of course higher due to this cache, as we are +trading space for time.

+

This is the basic concept behind packrat parsers.

+

A limitation pure PEGs share with LL(k) CFGs is that +left-recursive grammars cannot be parsed, with the associated +recursive descent parser entering an infinite recursion. +This limitation is usually overcome by extending pure PEGs with +explicit operators to specify repetition, zero or more, and one or +more, or, formally spoken, for the kleene closure and +positive kleene closure. +This is what the Parser Tools are doing.

+

Another extension, specific to Parser Tools, is a set of operators +which map more or less directly to various character classes built +into Tcl, i.e. the classes reachable via string is.

+

The remainder of this document consists of the formal definition of +PEGs for the mathematically inclined, and an appendix listing +references to places with more information on PEGs specifically, and +parsing in general.

+
+

Formal definition

+

For the mathematically inclined, a Parsing Expression Grammar is a +4-tuple (VN,VT,R,eS) where

+
    +

  • VN is a set of nonterminal symbols,

    • +

  • VT is a set of terminal symbols,

    • +

  • R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and e a parsing expression.

    • +

  • eS is a parsing expression, the start expression.

    • +
+

Further constraints are

+
    +

  • The intersection of VN and VT is empty.

    • +

  • For all A in VT exists exactly one pair (A,e) in R. In other words, R +is a function from nonterminal symbols to parsing expressions.

    • +
+

Parsing expressions are inductively defined via

+
    +

  • The empty string (epsilon) is a parsing expression.

    • +

  • A terminal symbol a is a parsing expression.

    • +

  • A nonterminal symbol A is a parsing expression.

    • +

  • e1e2 is a parsing expression for parsing expressions +e1 and 2. This is called sequence.

    • +

  • e1/e2 is a parsing expression for parsing expressions +e1 and 2. This is called ordered choice.

    • +

  • e* is a parsing expression for parsing expression +e. This is called zero-or-more repetitions, also known +as kleene closure.

    • +

  • e+ is a parsing expression for parsing expression +e. This is called one-or-more repetitions, also known +as positive kleene closure.

    • +

  • !e is a parsing expression for parsing expression +e1. This is called a not lookahead predicate.

    • +

  • &e is a parsing expression for parsing expression +e1. This is called an and lookahead predicate.

    • +
+

PEGs are used to define a grammatical structure for streams of symbols +over VT. They are a modern phrasing of older formalisms invented by +Alexander Birham. These formalisms were called TS (TMG recognition +scheme), and gTS (generalized TS). Later they were renamed to TPDL +(Top-Down Parsing Languages) and gTPDL (generalized TPDL).

+

They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars.

+
+

References

+
    +

  1. The Packrat Parsing and Parsing Expression Grammars Page, +by Bryan Ford, Massachusetts Institute of Technology. This is the main +entry page to PEGs, and their realization through Packrat Parsers.

    2. +

  2. http://en.wikipedia.org/wiki/Parsing_expression_grammar +Wikipedia's entry about Parsing Expression Grammars.

    3. +

  3. Parsing Techniques - A Practical Guide , an online book +offering a clear, accessible, and thorough discussion of many +different parsing techniques with their interrelations and +applicabilities, including error recovery techniques.

    4. +

  4. Compilers and Compiler Generators, an online book using +CoCo/R, a generator for recursive descent parsers.

    5. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_language.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_language.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_language.html @@ -0,0 +1,527 @@ + + +pt::peg_language - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg_language(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg_language - PEG Language Tutorial

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the tutorial / introduction for the +PEG Specification Language. +If you are already familiar with the language we are about to discuss, +and only wish to refresh your memory you can, of course, skip ahead to +the aforementioned section and just read the full formal specification.

+
+

What is it?

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+
+

The elements of the language

+

Basic structure

+

The general outline of a textual PEG is

+
+PEG <<name>> (<<start-expression>>)
+   <<rules>>
+END;
+
+

Note: We are using text in double angle-brackets as +place-holders for things not yet explained.

+
+

Names

+

Names are mostly used to identify the nonterminal symbols of the +grammar, i.e. that which occurs on the left-hand side of a <rule>. +The exception to that is the name given after the keyword PEG +(see previous section), which is the name of the whole grammar itself.

+

The structure of a name is simple:

+
    +

  1. It begins with a letter, underscore, or colon, followed by

    2. +

  2. zero or more letters, digits, underscores, or colons.

    3. +
+

Or, in formal textual notation:

+
+    ([_:] / <alpha>) ([_:] / <alnum>)*
+
+

Examples of names:

+
+    Hello
+    ::world
+    _:submarine55_
+
+

Examples of text which are not names:

+
+    12
+    .bogus
+    0wrong
+    @location
+
+
+

Rules

+

The main body of the text of a grammar specification is taken up by +the rules. Each rule defines the sentence structure of one nonterminal +symbol. Their basic structure is

+
+     <<name>>  <-  <<expression>> ;
+
+

The <name> specifies the nonterminal symbol to be defined, the +<expression> after the arrow (<-) then declares its structure.

+

Note that each rule ends in a single semicolon, even the last. +I.e. the semicolon is a rule terminator, not a separator.

+

We can have as many rules as we like, as long as we define each +nonterminal symbol at most once, and have at least one rule for each +nonterminal symbol which occured in an expression, i.e. in either the +start expression of the grammar, or the right-hande side of a rule.

+
+

Expressions

+

The parsing expressions are the meat of any specification. They +declare the structure of the whole document (<<start-expression>>), +and of all nonterminal symbols.

+

All expressions are made up out of atomic expressions and +operators combining them. We have operators for choosing +between alternatives, repetition of parts, and for look-ahead +constraints. There is no explicit operator for the sequencing (also +known as concatenation) of parts however. This is specified by +simply placing the parts adjacent to each other.

+

Here are the operators, from highest to lowest priority (i.e. strength +of binding):

+
+    # Binary operators.
+    <<expression-1>>     <<expression-2>>  # sequence. parse 1, then 2.
+    <<expression-1>>  /  <<expression-2>>  # alternative. try to parse 1, and parse 2 if 1 failed to parse.
+    # Prefix operators. Lookahead constraints. Same priority. 
+    & <<expression>>  # Parse expression, ok on successful parse.
+    ! <<expression>>  # Ditto, except ok on failure to parse.
+    # Suffix operators. Repetition. Same priority.
+    <<expression>> ?  # Parse expression none, or once (repeat 0 or 1).
+    <<expression>> *  # Parse expression zero or more times.
+    <<expression>> +  # Parse expression one or more times.
+    # Expression nesting
+    ( <<expression>> ) # Put an expression in parens to change its priority.
+
+

With this we can now deconstruct the formal expression for names given +in section Names:

+
+    ([_:] / <alpha>) ([_:] / <alnum>)*
+
+

It is a sequence of two parts,

+
    [_:] / <alpha>
+

and

+
    ([_:] / <alnum>)*
+

The parentheses around the parts kept their inner alternatives bound +together against the normally higher priority of the sequence. Each of +the two parts is an alternative, with the second part additionally +repeated zero or more times, leaving us with the three atomic +expressions

+
+    [_:]
+    <alpha>
+    <alnum>
+
+

And atomic expressions are our next topic. They +fall into three classes:

+
    +

  1. names, i.e. nonterminal symbols,

    2. +

  2. string literals, and

    3. +

  3. character classes.

    4. +
+

Names we know about already, or see section Names for a +refresher.

+

String literals are simple. They are delimited by (i.e. start and end +with) either a single or double-apostroph, and in between the +delimiters we can have any character but the delimiter itself. They +can be empty as well. Examples of strings are

+
+    ''
+    ""
+    'hello'
+    "umbra"
+    "'"
+    '"'
+
+

The last two examples show how to place any of the delimiters into a +string.

+

For the last, but not least of our atomic expressions, character +classes, we have a number of predefined classes, shown below, and the +ability to construct or own. The predefined classes are:

+
+    <alnum>    # Any unicode alphabet or digit character (string is alnum).
+    <alpha>    # Any unicode alphabet character (string is alpha).
+    <ascii>    # Any unicode character below codepoint 0x80 (string is ascii).
+    <control>  # Any unicode control character (string is control).
+    <ddigit>   # The digit characters [0-9].
+    <digit>    # Any unicode digit character (string is digit).
+    <graph>    # Any unicode printing character, except space (string is graph).
+    <lower>    # Any unicode lower-case alphabet character (string is lower).
+    <print>    # Any unicode printing character, incl. space (string is print).
+    <punct>    # Any unicode punctuation character (string is punct).
+    <space>    # Any unicode space character (string is space).
+    <upper>    # Any unicode upper-case alphabet character (string is upper).
+    <wordchar> # Any unicode word character (string is wordchar).
+    <xdigit>   # The hexadecimal digit characters [0-9a-fA-F].
+    .          # Any character, except end of input.
+
+

And the syntax of custom-defined character classes is

+
+    [ <<range>>* ]
+
+

where each range is either a single character, or of the form

+
+   <<character>> - <character>>
+
+

Examples for character classes we have seen already in the course of +this introduction are

+
+    [_:]
+    [0-9]
+    [0-9a-fA-F]
+
+

We are nearly done with expressions. The only piece left is to tell +how the characters in character classes and string literals are +specified.

+

Basically characters in the input stand for themselves, and in +addition to that we several types of escape syntax to to repesent +control characters, or characters outside of the encoding the text is +in.

+

All the escaped forms are started with a backslash character ('\', +unicode codepoint 0x5C). This is then followed by a series of octal +digits, or 'u' and hexedecimal digits, or a regular character from a +fixed set for various control characters. Some examples:

+
+    \n \r \t \' \" \[ \] \\ # 
+    \000 up to \277         # octal escape, all ascii character, leading 0's can be removed.
+    \u2CA7                  # hexadecimal escape, all unicode characters.
+    #                       # Here 2ca7 <=> Koptic Small Letter Tau
+
+
+

Whitespace and comments

+

One issue not touched upon so far is whitespace and comments.

+

Whitespace is any unicode space character, i.e. anything in the +character class <space>, and comments. The latter are sequences of +characters starting with a '#' (hash, unicode codepoint 0x23) and +ending at the next end-of-line.

+

Whitespace can be freely used between all syntactical elements of a +grammar specification. It cannot be used inside of syntactical +elements, like names, string literals, predefined character classes, +etc.

+
+

Nonterminal attributes

+

Lastly, a more advanced topic. In the section Rules we gave +the structure of a rule as

+
+     <<name>>  <-  <<expression>> ;
+
+

This is not quite true. It is possible to associate a semantic mode +with the nonterminal in the rule, by writing it before the name, +separated from it by a colon, i.e. writing

+
+    <<mode>> : <<name>>  <-  <<expression>> ;
+
+

is also allowed. This mode is optional. The known modes and their +meanings are:

+
+
value
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

+
leaf
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

+
void
+

The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

+
+

Of these three modes only leaf and void can be +specified directly. value is implicitly specified by the +absence of a mode before the nonterminal.

+

Now, with all the above under our belt it should be possible to not +only read, but understand the formal specification of the text +representation shown in the next section, written in itself.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- END SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG"   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:   END             <- "END"   WHITESPACE ;
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html @@ -0,0 +1,563 @@ + + +pt::peg::to::container - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::container - PEG Conversion. Write CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::container ?1?
    • +
  • package require pt::peg
    • +
  • package require text::write
    • +
  • package require char
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to CONTAINER markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::container sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::container reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::container configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::container configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::container configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::container convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates CONTAINER markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the CONTAINER format recognizes the following options +and changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-mode bulk|incremental
+

The value of this option controls which methods of +pt::peg::container instances are used to specify the +grammar, i.e. preload it into the container. There are two legal +values, as listed below. The default is bulk.

+
+
bulk
+

In this mode the methods start, add, modes, +and rules are used to specify the grammar in a bulk manner, +i.e. as a set of nonterminal symbols, and two dictionaries mapping +from the symbols to their semantic modes and parsing expressions.

+

This mode is the default.

+
incremental
+

In this mode the methods start, add, mode, +and rule are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands.

+
+
-template string
+

The value of this option is a string into which to put the generated +code and the other configuration settings. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant CONTAINER.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@mode@
+

To be replaced with the value of the option -mode.

+
@code@
+

To be replaced with the generated code.

+
+
+
+

Grammar Container

+

The container format is another form of describing parsing +expression grammars. While data in this format is executable it does +not constitute a parser for the grammar. It always has to be used in +conjunction with the package pt::peg::interp, a grammar +interpreter.

+

The format represents grammars by a snit::type, i.e. class, +whose instances are API-compatible to the instances of the +pt::peg::container package, and which are preloaded with the +grammar in question.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible CONTAINER serialization for it is

+
+snit::type a_pe_grammar {
+    constructor {} {
+        install myg using pt::peg::container ${selfns}::G
+        $myg start {n Expression}
+        $myg add   AddOp Digit Expression Factor MulOp Number Sign Term
+        $myg modes {
+            AddOp      value
+            Digit      value
+            Expression value
+            Factor     value
+            MulOp      value
+            Number     value
+            Sign       value
+            Term       value
+        }
+        $myg rules {
+            AddOp      {/ {t -} {t +}}
+            Digit      {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
+            Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
+            Factor     {x {n Term} {* {x {n AddOp} {n Term}}}}
+            MulOp      {/ {t *} {t /}}
+            Number     {x {? {n Sign}} {+ {n Digit}}}
+            Sign       {/ {t -} {t +}}
+            Term       {n Number}
+        }
+        return
+    }
+    component myg
+    delegate method * to myg
+}
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html @@ -0,0 +1,584 @@ + + +pt::peg::to::cparam - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::cparam(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::cparam - PEG Conversion. Write CPARAM format

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to CPARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::cparam sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::cparam reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::cparam configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::cparam configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::cparam configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::cparam convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates CPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to C code recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant C/PARAM.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated Tcl code.

+
+

The following options are special, in that they will +occur within the generated code, and are replaced there as well.

+
+
@statedecl@
+

To be replaced with the value of the option state-decl.

+
@stateref@
+

To be replaced with the value of the option state-ref.

+
@strings@
+

To be replaced with the value of the option string-varname.

+
@self@
+

To be replaced with the value of the option self-command.

+
@def@
+

To be replaced with the value of the option fun-qualifier.

+
@ns@
+

To be replaced with the value of the option namespace.

+
@main@
+

To be replaced with the value of the option main.

+
@prelude@
+

To be replaced with the value of the option prelude.

+
+
-state-decl string
+

A C string representing the argument declaration to use in the +generated parsing functions to refer to the parsing state. In essence +type and argument name. +The default value is the string RDE_PARAM p.

+
-state-ref string
+

A C string representing the argument named used in the generated +parsing functions to refer to the parsing state. +The default value is the string p.

+
-self-command string
+

A C string representing the reference needed to call the generated +parser function (methods ...) from another parser fonction, per the +chosen framework (template). +The default value is the empty string.

+
-fun-qualifier string
+

A C string containing the attributes to give to the generated +functions (methods ...), per the chosen framework (template). +The default value is static.

+
-namespace string
+

The name of the C namespace the parser functions (methods, ...) shall +reside in, or a general prefix to add to the function names. +The default value is the empty string.

+
-main string
+

The name of the main function (method, ...) to be called by the chosen +framework (template) to start parsing input. +The default value is __main.

+
-string-varname string
+

The name of the variable used for the table of strings used by the +generated parser, i.e. error messages, symbol names, etc. +The default value is p_string.

+
-prelude string
+

A snippet of code to be inserted at the head of each generated parsing +function. +The default value is the empty string.

+
-indent integer
+

The number of characters to indent each line of the generated code by. +The default value is 0.

+
+

While the high parameterizability of this converter, as shown by the +multitude of options it supports, is an advantage to the advanced +user, allowing her to customize the output of the converter as needed, +a novice user will likely not see the forest for the trees.

+

To help these latter users an adjunct package is provided, containing +a canned configuration which will generate immediately useful full +parsers. It is

+
+
pt::cparam::configuration::critcl
+

Generated parsers are embedded into a Critcl-based framework.

+
+
+

C/PARAM code representation of parsing expression grammars

+

The c format is executable code, a parser for the grammar. The +parser implementation is written in C and can be tweaked to the users' +needs through a multitude of options.

+

The critcl format, for example, is implemented as a canned +configuration of these options on top of the generator for c.

+

The bulk of such a framework has to be specified through the option +-template. The additional options

+
+
-fun-qualifier string
+
+
-indent integer
+
+
-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.

+

Example

+

We are forgoing an example of this representation, with apologies. +It would be way to large for this document.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html @@ -0,0 +1,620 @@ + + +pt::peg::to::json - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::json - PEG Conversion. Write JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::json ?1?
    • +
  • package require pt::peg
    • +
  • package require json::write
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to JSON markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::json sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::json reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::json configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::json configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::json configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::json convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates JSON markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the JSON grammar exchange format recognizes the +following configuration variables and changes its behaviour as they +specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-indented boolean
+

If this option is set the system will break the generated JSON across +lines and indent it according to its inner structure, with each key of +a dictionary on a separate line.

+

If the option is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
-aligned boolean
+

If this option is set the system will ensure that the values for the +keys in a dictionary are vertically aligned with each other, for a +nice table effect. +To make this work this also implies that -indented is set.

+

If the option is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html @@ -0,0 +1,1081 @@ + + +pt::peg::to::param - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::param(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::param - PEG Conversion. Write PARAM format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::param ?1?
    • +
  • package require pt::peg
    • +
  • package require pt::pe
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to PARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::param sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::param reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::param configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::param configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::param configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::param convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates PARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to PARAM markup recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
-template string
+

The value of this configuration variable is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the configuration variable -user.

+
@format@
+

To be replaced with the the constant PARAM.

+
@file@
+

To be replaced with the value of the configuration variable -file.

+
@name@
+

To be replaced with the value of the configuration variable -name.

+
@code@
+

To be replaced with the generated text.

+
+
-name string
+

The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is a_pe_grammar.

+
-user string
+

The value of this configuration variable is the name of the user for +which the conversion is run. The default value is unknown.

+
-file string
+

The value of this configuration variable is the name of the file or +other entity from which the grammar came, for which the conversion is +run. The default value is unknown.

+
+
+

PARAM code representation of parsing expression grammars

+

The PARAM code representation of parsing expression grammars is +assembler-like text using the instructions of the virtual machine +documented in the PackRat Machine Specification, plus a +few more for control flow (jump ok, jump fail, call symbol, return).

+

It is not really useful, except possibly as a tool demonstrating how a +grammar is compiled in general, without getting distracted by the +incidentials of a framework, i.e. like the supporting C and Tcl code +generated by the other PARAM-derived formats.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible PARAM serialization for it is

+
+# -*- text -*-
+# Parsing Expression Grammar 'TEMPLATE'.
+# Generated for unknown, from file 'TEST'
+#
+# Grammar Start Expression
+#
+<<MAIN>>:
+         call              sym_Expression
+         halt
+#
+# value Symbol 'AddOp'
+#
+sym_AddOp:
+# /
+#     '-'
+#     '+'
+         symbol_restore    AddOp
+  found! jump              found_7
+         loc_push
+         call              choice_5
+   fail! value_clear
+     ok! value_leaf        AddOp
+         symbol_save       AddOp
+         error_nonterminal AddOp
+         loc_pop_discard
+found_7:
+     ok! ast_value_push
+         return
+choice_5:
+# /
+#     '-'
+#     '+'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t -"
+     ok! test_char         "-"
+         error_pop_merge
+     ok! jump              oknoast_4
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t +"
+     ok! test_char         "+"
+         error_pop_merge
+     ok! jump              oknoast_4
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_4:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Digit'
+#
+sym_Digit:
+# /
+#     '0'
+#     '1'
+#     '2'
+#     '3'
+#     '4'
+#     '5'
+#     '6'
+#     '7'
+#     '8'
+#     '9'
+         symbol_restore    Digit
+  found! jump              found_22
+         loc_push
+         call              choice_20
+   fail! value_clear
+     ok! value_leaf        Digit
+         symbol_save       Digit
+         error_nonterminal Digit
+         loc_pop_discard
+found_22:
+     ok! ast_value_push
+         return
+choice_20:
+# /
+#     '0'
+#     '1'
+#     '2'
+#     '3'
+#     '4'
+#     '5'
+#     '6'
+#     '7'
+#     '8'
+#     '9'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t 0"
+     ok! test_char         "0"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 1"
+     ok! test_char         "1"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 2"
+     ok! test_char         "2"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 3"
+     ok! test_char         "3"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 4"
+     ok! test_char         "4"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 5"
+     ok! test_char         "5"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 6"
+     ok! test_char         "6"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 7"
+     ok! test_char         "7"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 8"
+     ok! test_char         "8"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 9"
+     ok! test_char         "9"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_19:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Expression'
+#
+sym_Expression:
+# /
+#     x
+#         '\('
+#         (Expression)
+#         '\)'
+#     x
+#         (Factor)
+#         *
+#             x
+#                 (MulOp)
+#                 (Factor)
+         symbol_restore    Expression
+  found! jump              found_46
+         loc_push
+         ast_push
+         call              choice_44
+   fail! value_clear
+     ok! value_reduce      Expression
+         symbol_save       Expression
+         error_nonterminal Expression
+         ast_pop_rewind
+         loc_pop_discard
+found_46:
+     ok! ast_value_push
+         return
+choice_44:
+# /
+#     x
+#         '\('
+#         (Expression)
+#         '\)'
+#     x
+#         (Factor)
+#         *
+#             x
+#                 (MulOp)
+#                 (Factor)
+         error_clear
+         ast_push
+         loc_push
+         error_push
+         call              sequence_27
+         error_pop_merge
+     ok! jump              ok_43
+         ast_pop_rewind
+         loc_pop_rewind
+         ast_push
+         loc_push
+         error_push
+         call              sequence_40
+         error_pop_merge
+     ok! jump              ok_43
+         ast_pop_rewind
+         loc_pop_rewind
+         status_fail
+         return
+ok_43:
+         ast_pop_discard
+         loc_pop_discard
+         return
+sequence_27:
+# x
+#     '\('
+#     (Expression)
+#     '\)'
+         loc_push
+         error_clear
+         error_push
+         input_next        "t ("
+     ok! test_char         "("
+         error_pop_merge
+   fail! jump              failednoast_29
+         ast_push
+         error_push
+         call              sym_Expression
+         error_pop_merge
+   fail! jump              failed_28
+         error_push
+         input_next        "t )"
+     ok! test_char         ")"
+         error_pop_merge
+   fail! jump              failed_28
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_28:
+         ast_pop_rewind
+failednoast_29:
+         loc_pop_rewind
+         return
+sequence_40:
+# x
+#     (Factor)
+#     *
+#         x
+#             (MulOp)
+#             (Factor)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_Factor
+         error_pop_merge
+   fail! jump              failed_41
+         error_push
+         call              kleene_37
+         error_pop_merge
+   fail! jump              failed_41
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_41:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+kleene_37:
+# *
+#     x
+#         (MulOp)
+#         (Factor)
+         loc_push
+         error_push
+         call              sequence_34
+         error_pop_merge
+   fail! jump              failed_38
+         loc_pop_discard
+         jump              kleene_37
+failed_38:
+         loc_pop_rewind
+         status_ok
+         return
+sequence_34:
+# x
+#     (MulOp)
+#     (Factor)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_MulOp
+         error_pop_merge
+   fail! jump              failed_35
+         error_push
+         call              sym_Factor
+         error_pop_merge
+   fail! jump              failed_35
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_35:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+#
+# value Symbol 'Factor'
+#
+sym_Factor:
+# x
+#     (Term)
+#     *
+#         x
+#             (AddOp)
+#             (Term)
+         symbol_restore    Factor
+  found! jump              found_60
+         loc_push
+         ast_push
+         call              sequence_57
+   fail! value_clear
+     ok! value_reduce      Factor
+         symbol_save       Factor
+         error_nonterminal Factor
+         ast_pop_rewind
+         loc_pop_discard
+found_60:
+     ok! ast_value_push
+         return
+sequence_57:
+# x
+#     (Term)
+#     *
+#         x
+#             (AddOp)
+#             (Term)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_Term
+         error_pop_merge
+   fail! jump              failed_58
+         error_push
+         call              kleene_54
+         error_pop_merge
+   fail! jump              failed_58
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_58:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+kleene_54:
+# *
+#     x
+#         (AddOp)
+#         (Term)
+         loc_push
+         error_push
+         call              sequence_51
+         error_pop_merge
+   fail! jump              failed_55
+         loc_pop_discard
+         jump              kleene_54
+failed_55:
+         loc_pop_rewind
+         status_ok
+         return
+sequence_51:
+# x
+#     (AddOp)
+#     (Term)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_AddOp
+         error_pop_merge
+   fail! jump              failed_52
+         error_push
+         call              sym_Term
+         error_pop_merge
+   fail! jump              failed_52
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_52:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+#
+# value Symbol 'MulOp'
+#
+sym_MulOp:
+# /
+#     '*'
+#     '/'
+         symbol_restore    MulOp
+  found! jump              found_67
+         loc_push
+         call              choice_65
+   fail! value_clear
+     ok! value_leaf        MulOp
+         symbol_save       MulOp
+         error_nonterminal MulOp
+         loc_pop_discard
+found_67:
+     ok! ast_value_push
+         return
+choice_65:
+# /
+#     '*'
+#     '/'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t *"
+     ok! test_char         "*"
+         error_pop_merge
+     ok! jump              oknoast_64
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t /"
+     ok! test_char         "/"
+         error_pop_merge
+     ok! jump              oknoast_64
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_64:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Number'
+#
+sym_Number:
+# x
+#     ?
+#         (Sign)
+#     +
+#         (Digit)
+         symbol_restore    Number
+  found! jump              found_80
+         loc_push
+         ast_push
+         call              sequence_77
+   fail! value_clear
+     ok! value_reduce      Number
+         symbol_save       Number
+         error_nonterminal Number
+         ast_pop_rewind
+         loc_pop_discard
+found_80:
+     ok! ast_value_push
+         return
+sequence_77:
+# x
+#     ?
+#         (Sign)
+#     +
+#         (Digit)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              optional_70
+         error_pop_merge
+   fail! jump              failed_78
+         error_push
+         call              poskleene_73
+         error_pop_merge
+   fail! jump              failed_78
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_78:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+optional_70:
+# ?
+#     (Sign)
+         loc_push
+         error_push
+         call              sym_Sign
+         error_pop_merge
+   fail! loc_pop_rewind
+     ok! loc_pop_discard
+         status_ok
+         return
+poskleene_73:
+# +
+#     (Digit)
+         loc_push
+         call              sym_Digit
+   fail! jump              failed_74
+loop_75:
+         loc_pop_discard
+         loc_push
+         error_push
+         call              sym_Digit
+         error_pop_merge
+     ok! jump              loop_75
+         status_ok
+failed_74:
+         loc_pop_rewind
+         return
+#
+# value Symbol 'Sign'
+#
+sym_Sign:
+# /
+#     '-'
+#     '+'
+         symbol_restore    Sign
+  found! jump              found_86
+         loc_push
+         call              choice_5
+   fail! value_clear
+     ok! value_leaf        Sign
+         symbol_save       Sign
+         error_nonterminal Sign
+         loc_pop_discard
+found_86:
+     ok! ast_value_push
+         return
+#
+# value Symbol 'Term'
+#
+sym_Term:
+# (Number)
+         symbol_restore    Term
+  found! jump              found_89
+         loc_push
+         ast_push
+         call              sym_Number
+   fail! value_clear
+     ok! value_reduce      Term
+         symbol_save       Term
+         error_nonterminal Term
+         ast_pop_rewind
+         loc_pop_discard
+found_89:
+     ok! ast_value_push
+         return
+#
+#
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html @@ -0,0 +1,605 @@ + + +pt::peg::to::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::peg - PEG Conversion. Write PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::peg ?1?
    • +
  • package require pt::peg
    • +
  • package require pt::pe
    • +
  • package require text::write
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to PEG markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::peg sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::peg reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::peg configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::peg configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::peg configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::peg convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates PEG markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the PEG language recognizes the following options and +changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put the generated +text and the values of the other options. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated text.

+
+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- END SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ('_' / ':' / <alpha>) ('_' / ':' / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG"   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:   END             <- "END"   WHITESPACE ;
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html @@ -0,0 +1,567 @@ + + +pt::peg::to::tclparam - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg::to::tclparam(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::tclparam - PEG Conversion. Write TCLPARAM format

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to TCLPARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::tclparam sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::tclparam reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::tclparam configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::tclparam configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::tclparam configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::tclparam convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates TCLPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to Tcl/PARAM markup recognizes the following +configuration variables and changes its behaviour as they specify.

+
+
-template string
+

The value of this configuration variable is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the configuration variable -user.

+
@format@
+

To be replaced with the the constant Tcl/PARAM.

+
@file@
+

To be replaced with the value of the configuration variable -file.

+
@name@
+

To be replaced with the value of the configuration variable -name.

+
@code@
+

To be replaced with the generated Tcl code.

+
+

The following configuration variables are special, in that they will +occur within the generated code, and are replaced there as well.

+
+
@runtime@
+

To be replaced with the value of the configuration variable runtime-command.

+
@self@
+

To be replaced with the value of the configuration variable self-command.

+
@def@
+

To be replaced with the value of the configuration variable proc-command.

+
@ns@
+

To be replaced with the value of the configuration variable namespace.

+
@main@
+

To be replaced with the value of the configuration variable main.

+
@prelude@
+

To be replaced with the value of the configuration variable prelude.

+
+
-name string
+

The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is a_pe_grammar.

+
-user string
+

The value of this configuration variable is the name of the user for +which the conversion is run. The default value is unknown.

+
-file string
+

The value of this configuration variable is the name of the file or +other entity from which the grammar came, for which the conversion is +run. The default value is unknown.

+
-runtime-command string
+

A Tcl string representing the Tcl command or reference to it used to +call PARAM instruction from parser procedures, per the chosen +framework (template). +The default value is the empty string.

+
-self-command string
+

A Tcl string representing the Tcl command or reference to it used to +call the parser procedures (methods ...) from another parser +procedure, per the chosen framework (template). +The default value is the empty string.

+
-proc-command string
+

The name of the Tcl command used to define procedures (methods ...), +per the chosen framework (template). +The default value is proc.

+
-namespace string
+

The name of the namespace the parser procedures (methods, ...) shall +reside in, including the trailing '::' needed to separate it from the +actual procedure name. +The default value is ::.

+
-main string
+

The name of the main procedure (method, ...) to be called by the +chosen framework (template) to start parsing input. +The default value is __main.

+
-prelude string
+

A snippet of code to be insert at the head of each generated parsing +command. +The default value is the empty string.

+
-indent integer
+

The number of characters to indent each line of the generated code by. +The default value is 0.

+
+

While the high parameterizability of this converter, as shown by the +multitude of options it supports, is an advantage to the advanced +user, allowing her to customize the output of the converter as needed, +a novice user will likely not see the forest for the trees.

+

To help these latter users two adjunct packages are provided, each +containing a canned configuration which will generate immediately +useful full parsers. These are

+
+
pt::tclparam::configuration::snit
+

Generated parsers are classes based on the snit package, +i.e. snit::type's.

+
pt::tclparam::configuration::tcloo
+

Generated parsers are classes based on the OO package.

+
+
+

Tcl/PARAM code representation of parsing expression grammars

+

The Tcl/PARAM representation of parsing expression grammars is Tcl +code whose execution will parse input per the grammar. The code is +based on the virtual machine documented in the +PackRat Machine Specification, using its instructions +and a few more to handle control flow.

+

Note that the generated code by itself is not functional. It expects +to be embedded into a framework which provides services like the PARAM +state, implementations for the PARAM instructions, etc. +The bulk of such a framework has to be specified through the option +-template. The additional options

+
+
-indent integer
+
+
-main string
+
+
-namespace string
+
+
-prelude string
+
+
-proc-command string
+
+
-runtime-command string
+
+
-self-command string
+
+
+

provide code snippets which help to glue framework and generated code +together. Their placeholders are in the generated code.

+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pegrammar.html Index: embedded/www/tcllib/files/modules/pt/pt_pegrammar.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_pegrammar.html @@ -0,0 +1,481 @@ + + +pt::peg - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg - Parsing Expression Grammar Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +parsing expression grammars as managed by the Parser Tools, and +specified in section PEG serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::peg verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of a parsing expression and will throw an error if that +is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::peg verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a PEG and will throw an error if +that is not the case. The result of the command is the empty string.

+

For the specification of canonical serializations see the section +PEG serialization format.

+
::pt::peg canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a PEG and will throw an error if that +is not the case.

+

It will then convert the input into the canonical serialization +of the contained PEG and return it as its result. If the input is +already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section PEG serialization format.

+
::pt::peg print serial
+

This command assumes that the argument serial contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +PEG serialization format.

+
::pt::peg merge seriala serialb
+

This command accepts the regular serializations of two grammars and +uses them to create their union. The result of the command is the +canonical serialization of this unified grammar.

+

A merge errors occurs if for any nonterminal symbol S occuring in both +input grammars the two input grammars specify different semantic +modes.

+

The semantic mode of each nonterminal symbol S is the semantic mode of +S in any of its input grammars. The previous rule made sure that for +symbols occuring in both grammars these values are identical.

+

The right-hand side of each nonterminal symbol S occuring in both +input grammars is the choice between the right-hand sides of S in the +input grammars, with the parsing expression of S in seriala +coming first, except if both expressions are identical. In that case +the first expression is taken.

+

The right-hand side of each nonterminal symbol S occuring in only one +of the input grammars is the right-hand side of S in its input +grammar.

+

The start expression of the unified grammar is the choice between the +start expressions of the input grammars, with the start expression of +seriala coming first, except if both expressions are identical. +In that case the first expression is taken

+
::pt::peg equal seriala serialb
+

This command tests the two grammars seriala and serialb +for structural equality. The result of the command is a boolean +value. It will be set to true if the expressions are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two grammars +are pure Tcl lists and dictionaries.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html Index: embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html @@ -0,0 +1,344 @@ + + +pt::pe::op - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::pe::op(n) 1 tcllib "Parser Tools"

+

Name

+

pt::pe::op - Parsing Expression Utilities

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::pe::op ?1?
    • +
  • package require pt::pe ?1?
    • +
  • package require struct::set
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides additional commands to work with the +serializations of parsing expressions as managed by the PEG and +related packages, and specified in section +PE serialization format.

+

This is an internal package, for use by the higher level packages +handling PEGs, their conversion into and out of various other formats, +or other uses.

+
+

API

+
+
::pt::pe::op drop dropset pe
+

This command removes all occurences of any of the nonterminals symbols +in the set dropset from the parsing expression pe, and +simplifies it. This may result in the expression becoming "epsilon", +i.e. matching nothing.

+
::pt::pe::op rename nt ntnew pe
+

This command renames all occurences of the nonterminal nt in the +parsing expression pe into ntnew.

+
::pt::pe::op called pe
+

This command extracts the set of all nonterminal symbols used, +i.e. 'called', in the parsing expression pe.

+
::pt::pe::op flatten pe
+

This command transforms the parsing expression by eliminating +sequences nested in sequences, and choices in choices, lifting the +children of the nested expression into the parent. It further +eliminates all sequences and choices with only one child, as these are +redundant.

+

The resulting parsing expression is returned as the result of the +command.

+
::pt::pe::op fusechars pe
+

This command transforms the parsing expression by fusing adjacent +terminals in sequences and adjacent terminals and ranges in choices, +it (re)constructs highlevel strings and +character classes.

+

The resulting pseudo-parsing expression is returned as the result of +the command and may contain the pseudo-operators str for +character sequences, aka strings, and cl for character +choices, aka character classes.

+

The result is called a pseudo-parsing expression because it +is not a true parsing expression anymore, and will fail a check with +::pt::peg verify if the new pseudo-operators +are present in the result, but is otherwise of sound structure for a +parsing expression. +Notably, the commands ::pt::peg bottomup and +::pt::peg topdown will process them without +trouble.

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pexpression.html Index: embedded/www/tcllib/files/modules/pt/pt_pexpression.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_pexpression.html @@ -0,0 +1,470 @@ + + +pt::pe - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::pe(n) 1 tcllib "Parser Tools"

+

Name

+

pt::pe - Parsing Expression Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +parsing expressions as managed by the Parser Tools, and specified in +section PE serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::pe verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of a parsing expression and will throw an error if that +is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::pe verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a parsing expression and will throw +an error if that is not the case. The result of the command is the +empty string.

+

For the specification of canonical serializations see the section +PE serialization format.

+
::pt::pe canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a parsing expression and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of this parsing expression and return it as its result. If the input +is already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section PE serialization format.

+
::pt::pe print serial
+

This command assumes that the argument serial contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::pe bottomup cmdprefix pe
+

This command walks the parsing expression pe from the bottom up +to the root, invoking the command prefix cmdprefix for each +partial expression. This implies that the children of a parsing +expression PE are handled before PE.

+

The command prefix has the signature

+
+
cmdprefix pe op arguments
+

I.e. it is invoked with the parsing expression pe the walk is +currently at, the op'erator in the pe, and the operator's +arguments.

+

The result returned by the command prefix replaces pe in the +parsing expression it was a child of, allowing transformations of the +expression tree.

+

This also means that for all inner parsing expressions the contents of +arguments are the results of the command prefix invoked for the +children of this inner parsing expression.

+
+
::pt::pe topdown cmdprefix pe
+

This command walks the parsing expression pe from the root down +to the leaves, invoking the command prefix cmdprefix for each +partial expression. This implies that the children of a parsing +expression PE are handled after PE.

+

The command prefix has the same signature as for bottomup, +see above.

+

The result returned by the command prefix is ignored.

+
::pt::pe equal seriala serialb
+

This command tests the two parsing expressions seriala and +serialb for structural equality. The result of the command is a +boolean value. It will be set to true if the expressions are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two parsing +expressions are pure Tcl lists.

+
::pt::pe epsilon
+

This command constructs the atomic parsing expression for epsilon.

+
::pt::pe dot
+

This command constructs the atomic parsing expression for dot.

+
::pt::pe alnum
+

This command constructs the atomic parsing expression for alnum.

+
::pt::pe alpha
+

This command constructs the atomic parsing expression for alpha.

+
::pt::pe ascii
+

This command constructs the atomic parsing expression for ascii.

+
::pt::pe control
+

This command constructs the atomic parsing expression for control.

+
::pt::pe digit
+

This command constructs the atomic parsing expression for digit.

+
::pt::pe graph
+

This command constructs the atomic parsing expression for graph.

+
::pt::pe lower
+

This command constructs the atomic parsing expression for lower.

+
::pt::pe print
+

This command constructs the atomic parsing expression for print.

+
::pt::pe punct
+

This command constructs the atomic parsing expression for punct.

+
::pt::pe space
+

This command constructs the atomic parsing expression for space.

+
::pt::pe upper
+

This command constructs the atomic parsing expression for upper.

+
::pt::pe wordchar
+

This command constructs the atomic parsing expression for wordchar.

+
::pt::pe xdigit
+

This command constructs the atomic parsing expression for xdigit.

+
::pt::pe ddigit
+

This command constructs the atomic parsing expression for ddigit.

+
::pt::pe terminal t
+

This command constructs the atomic parsing expression for the terminal +symbol t.

+
::pt::pe range ta tb
+

This command constructs the atomic parsing expression for the range of +terminal symbols ta ... tb.

+
::pt::pe nonterminal nt
+

This command constructs the atomic parsing expression for the +nonterminal symbol nt.

+
::pt::pe choice pe...
+

This command constructs the parsing expression representing the +ordered or prioritized choice between the argument parsing +expressions. The first argument has the highest priority.

+
::pt::pe sequence pe...
+

This command constructs the parsing expression representing the +sequence of the argument parsing expression. The first argument is the +first element of the sequence.

+
::pt::pe repeat0 pe
+

This command constructs the parsing expression representing the zero +or more repetition of the argument parsing expression pe, also +known as the kleene closure.

+
::pt::pe repeat1 pe
+

This command constructs the parsing expression representing the one or +more repetition of the argument parsing expression pe, also +known as the positive kleene closure.

+
::pt::pe optional pe
+

This command constructs the parsing expression representing the +optionality of the argument parsing expression pe.

+
::pt::pe ahead pe
+

This command constructs the parsing expression representing the +positive lookahead of the argument parsing expression pe.

+
::pt::pe notahead pe
+

This command constructs the parsing expression representing the +negative lookahead of the argument parsing expression pe.

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pgen.html Index: embedded/www/tcllib/files/modules/pt/pt_pgen.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_pgen.html @@ -0,0 +1,297 @@ + + +pt::pgen - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::pgen(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::pgen - Parser Generator

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::pgen ?1.0.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a command implementing a +parser generator +taking parsing expression grammars as input.

+

It is the implementation of method generate of pt, the +Parser Tools Application.

+

As such the intended audience of this document are people wishing to +modify and/or extend this part of pt's functionality. Users of +pt on the other hand are hereby refered to the applications' +manpage, i.e. Parser Tools Application.

+

It resides in the User Package Layer of Parser Tools.

+

arch_user_pkg

+
+

API

+
+
::pt::pgen inputformat text resultformat ?options...?
+

This command takes the parsing expression grammar in text (in +the format specified by inputformat), and returns the same +grammar in the format resultformat as the result of the command.

+

The two known input formats are peg and json. +Introductions to them, including their formal specifications, can be +found in the PEG Language Tutorial and +The JSON Grammar Exchange Format. The packages used to +parse these formats are

+
+
peg
+

pt::peg::from::peg

+
json
+

pt::peg::from::json

+
+

On the output side the known formats, and the packages used to +generate them are

+
+
c
+

pt::peg::to::cparam

+
container
+

pt::peg::to::container

+
critcl
+

pt::peg::to::cparam + + pt::cparam::configuration::critcl

+
json
+

pt::peg::to::json

+
oo
+

pt::peg::to::tclparam + + pt::tclparam::configuration::tcloo

+
peg
+

pt::peg::to::peg

+
snit
+

pt::peg::to::tclparam + + pt::tclparam::configuration::snit

+
+

The options supported by each of these formats are documented +with their respective packages.

+
+
+

Example

+

In this section we are working a complete example, starting with a PEG +grammar and ending with running the parser generated from it over some +input, following the outline shown in the figure below:

+

flow

+

Our grammar, assumed to the stored in the file "calculator.peg" +is

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

From this we create a snit-based parser +using the script "gen"

+
+package require Tcl 8.5
+package require fileutil
+package require pt::pgen
+lassign $argv name
+set grammar [fileutil::cat $name.peg]
+set pclass  [pt::pgen peg $gr snit -class $name -file  $name.peg -name  $name]
+fileutil::writeFile $name.tcl $pclass
+exit 0
+
+

calling it like

+
 tclsh8.5 gen calculator
+

which leaves us with the parser package and class written to the file +"calculator.tcl". +Assuming that this package is then properly installed in a place where +Tcl can find it we can now use this class via a script like

+
+    package require calculator
+    lassign $argv input
+    set channel [open $input r]
+    set parser [calculator]
+    set ast [$parser parse $channel]
+    $parser destroy
+    close $channel
+    ... now process the returned abstract syntax tree ...
+
+

where the abstract syntax tree stored in the variable will look like

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

assuming that the input file and channel contained the text

+
 120+5
+

A more graphical representation of the tree would be

+

expr_ast

+

Regardless, at this point it is the user's responsibility to work with +the tree to reach whatever goal she desires. I.e. analyze it, +transform it, etc. The package pt::ast should be of help +here, providing commands to walk such ASTs structures in various ways.

+

One important thing to note is that the parsers used here return a +data structure representing the structure of the input per the grammar +underlying the parser. There are no callbacks during the +parsing process, i.e. no parsing actions, as most other +parsers will have.

+

Going back to the last snippet of code, the execution of the parser +for some input, note how the parser instance follows the specified +Parser API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_rdengine.html Index: embedded/www/tcllib/files/modules/pt/pt_rdengine.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_rdengine.html @@ -0,0 +1,830 @@ + + +pt::rde - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::rde(n) 1.0.2 tcllib "Parser Tools"

+

Name

+

pt::rde - Parsing Runtime Support, PARAM based

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::rde ?1.0.2?
    • +
  • package require snit
    • +
  • package require struct::stack 1.4
    • +
  • package require pt::ast 1.1
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a class whose instances provide the runtime +support for recursive descent parsers with backtracking, as is needed +for the execution of, for example, parsing expression grammars. It +implements the PackRat Machine Specification, as such that +document is required reading to understand both this manpage, +and the package itself. The description below does make numerous +shorthand references to the PARAM's instructions and the various parts +of its architectural state.

+

The package resides in the Execution section of the Core Layer of +Parser Tools.

+

arch_core_transform

+

Note: This package not only has the standard Tcl implementation, but +also an accelerator, i.e. a C implementation, based on Critcl.

+

Class API

+

The package exports the API described here.

+
+
::pt::rde objectName
+

The command creates a new runtime object for a recursive descent +parser with backtracking and returns the fully qualified name of the +object command as its result. The API of this object command is +described in the section Object API. It may be used to +invoke various operations on the object.

+
+
+

Object API

+

All objects created by this package provide the following 63 methods +for the manipulation and querying of their state, which is, in essence +the architectural state of a PARAM.

+

First some general methods and the state accessors.

+
+
objectName destroy
+

This method destroys the object, releasing all claimed memory, and +deleting the associated object command.

+
objectName reset chan
+

This method resets the state of the runtme to its defaults, preparing +it for the parsing of the character in the channel chan, which +becomes IN.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+
objectName complete
+

This method completes parsing, either returning the AST made from the +elements of ARS, or throwing an error containing the current ER.

+
objectName chan
+

This method returns the handle of the channel which is IN.

+
objectName line
+

This method returns the line number for the position IN is currently +at. Note that this may not match with the line number for CL, due to +backtracking.

+
objectName column
+

This method returns the column for the position IN is currently +at. Note that this may not match with the column for CL, due to +backtracking.

+
objectName current
+

This method returns CC.

+
objectName location
+

This method returns CL.

+
objectName locations
+

This method returns the LS. The topmost entry of the stack will be the +first element of the returned list.

+
objectName ok
+

This method returns ST.

+
objectName value
+

This method returns SV.

+
objectName error
+

This method returns ER. This is either the empty string for an empty +ER, or a list of 2 elements, the location the error is for, and a set +of messages which specify which symbols were expected at the +location. The messages are encoded as one of the possible atomic +parsing expressions (special operators, terminal, range, and +nonterminal operator).

+
objectName errors
+

This method returns ES. The topmost entry of the stack will be the +first element of the returned list. Each entry is encoded as described +for error.

+
objectName tokens ?from ?to??
+

This method returns the part of TC for the range of locations of IN +starting at from and ending at to. If to is not +specified it is taken as identical to from. If neither argument +is specified the whole of TC is returned.

+

Each token in the returned list is a list of three elements itself, +containing the character at the location, and the associated line and +column numbers, in this order.

+
objectName symbols
+

This method returns a dictionary containing NC. Keys are two-element +lists containing nonterminal symbol and location, in this order. The +values are 4-tuples containing CL, ST, ER, and SV, in this order. ER +is encoded as specified for the method error.

+
objectName known
+

This method returns a list containing the keys of SC. They are +encoded in the same manner as is done by method symbols.

+
objectName reducible
+

This method returns ARS. The topmost entry of the stack will be the +first element of the returned list

+
objectName asts
+

This method returns AS. The topmost entry of the stack will be the +first element of the returned list

+
objectName ast
+

This is a convenience method returning the topmost element of ARS.

+
objectName position loc
+

This method returns the line and column numbers for the specified +location of IN, assuming that this location has already been reached +during the parsing process.

+
+

The following methods implement all PARAM instructions. They all have +the prefix "i_".

+

The control flow is mainly provided by Tcl's builtin commands, like +if, while, etc., plus a few guarded variants of PARAM +instructions and Tcl commands.. That means that these instruction +variants will do nothing if their guard condition is not +fulfilled. They can be recognized by the prefix "i:ok_" and "i:fail_", +which denote the value ST has to have for the instruction to execute.

+

The instructions are listed in the same order they occur in the +PackRat Machine Specification, with the guard variants +listed after their regular implementation, if any, or in their place.

+
+
objectName i_input_next msg
+

This method implements the PARAM instruction input_next.

+
objectName i_test_alnum
+

This method implements the PARAM instruction test_alnum.

+
objectName i_test_alpha
+

This method implements the PARAM instruction test_alpha.

+
objectName i_test_ascii
+

This method implements the PARAM instruction test_ascii.

+
objectName i_test_char char
+

This method implements the PARAM instruction test_char.

+
objectName i_test_ddigit
+

This method implements the PARAM instruction test_ddigit.

+
objectName i_test_digit
+

This method implements the PARAM instruction test_digit.

+
objectName i_test_graph
+

This method implements the PARAM instruction test_graph.

+
objectName i_test_lower
+

This method implements the PARAM instruction test_lower.

+
objectName i_test_print
+

This method implements the PARAM instruction test_print.

+
objectName i_test_punct
+

This method implements the PARAM instruction test_punct.

+
objectName i_test_range chars chare
+

This method implements the PARAM instruction test_range.

+
objectName i_test_space
+

This method implements the PARAM instruction test_space.

+
objectName i_test_upper
+

This method implements the PARAM instruction test_upper.

+
objectName i_test_wordchar
+

This method implements the PARAM instruction test_wordchar.

+
objectName i_test_xdigit
+

This method implements the PARAM instruction test_xdigit.

+
objectName i_error_clear
+

This method implements the PARAM instruction error_clear.

+
objectName i_error_push
+

This method implements the PARAM instruction error_push.

+
objectName i_error_pop_merge
+

This method implements the PARAM instruction error_pop_merge.

+
objectName i_error_nonterminal symbol
+

This method implements the PARAM instruction error_nonterminal.

+
objectName i_status_ok
+

This method implements the PARAM instruction status_ok.

+
objectName i_status_fail
+

This method implements the PARAM instruction status_fail.

+
objectName i_status_negate
+

This method implements the PARAM instruction status_negate.

+
objectName i_loc_push
+

This method implements the PARAM instruction loc_push.

+
objectName i_loc_pop_discard
+

This method implements the PARAM instruction loc_pop_discard.

+
objectName i_loc_pop_rewind
+

This method implements the PARAM instruction loc_pop_rewind.

+
objectName i:ok_loc_pop_rewind
+

This guarded method, a variant of i_loc_pop_rewind, executes only +for "ST == ok".

+
objectName i_loc_pop_rewind/discard
+

This method is a convenient combination of control flow and the two +PARAM instructions loc_pop_rewind and loc_pop_discard. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_symbol_restore symbol
+

This method implements the PARAM instruction symbol_restore.

+

The boolean result of the check is returned as the result of +the method and can be used with standard Tcl control flow commands.

+
objectName i_symbol_save symbol
+

This method implements the PARAM instruction symbol_save.

+
objectName i_value_clear
+

This method implements the PARAM instruction value_clear.

+
objectName i_value_clear/leaf
+

This method is a convenient combination of control flow and the two +PARAM instructions value_clear and value_leaf. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_value_clear/reduce
+

This method is a convenient combination of control flow and the two +PARAM instructions value_clear and value_reduce. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i:ok_ast_value_push
+

This method implements a guarded variant of the the PARAM instruction +ast_value_push, which executes only for "ST == ok".

+
objectName i_ast_push
+

This method implements the PARAM instruction ast_push.

+
objectName i_ast_pop_rewind
+

This method implements the PARAM instruction ast_pop_rewind.

+
objectName i:fail_ast_pop_rewind
+

This guarded method, a variant of i_ast_pop_rewind, executes only +for "ST == fail".

+
objectName i_ast_pop_rewind/discard
+

This method is a convenient combination of control flow and the two +PARAM instructions ast_pop_rewind and ast_pop_discard. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_ast_pop_discard
+

This method implements the PARAM instruction ast_pop_discard.

+
objectName i_ast_pop_discard/rewind
+

This method is a convenient combination of control flow and the two +PARAM instructions ast_pop_discard and ast_pop_rewind. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i:ok_continue
+

This guarded method executes only for "ST == ok". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure.

+
objectName i:fail_continue
+

This guarded method executes only for "ST == fail". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure.

+
objectName i:fail_return
+

This guarded method executes only for "ST == fail". Then it aborts the +calling Tcl procedure.

+
objectName i:ok_return
+

This guarded method executes only for "ST == ok". Then it aborts the +calling Tcl procedure.

+
+

The next set of methods are super instructions, meaning that +each implements a longer sequence of instructions commonly used in +parsers. The combinated instructions of the previous set, i.e. those +with names matching the pattern "i_*/*", are actually super +instructions as well, albeit with limited scope, handling 2 +instructions with their control flow. The upcoming set is much broader +in scope, folding as much as six or more PARAM instructions into a +single method call.

+

In this we can see the reasoning behind their use well:

+
    +

  1. By using less instructions the generated parsers become smaller, as +the common parts are now truly part of the common runtime, and not +explicitly written in the parser's code over and over again.

    2. +

  2. Using less instructions additionally reduces the overhead associated +with calls into the runtime, i.e. the cost of method dispatch and of +setting up the variable context.

    3. +

  3. Another effect of the super instructions is that their internals can +be optimized as well, especially regarding control flow, and stack +use, as the runtime internals are accessible to all instructions +folded into the sequence.

    4. +
+
+
objectName si:void_state_push
+

This method combines

+
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of void sequences and choices +with a void initial branch.

+
objectName si:void2_state_push
+

This method combines

+
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of optional and repeated expressions.

+
objectName si:value_state_push
+

This method combines

+
+i_ast_push
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of sequences generating an AST and +choices with an initial branch generating an AST.

+
objectName si:void_state_merge
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+
+

Parsers use it at the end of void sequences and choices whose last +branch is void.

+
objectName si:void_state_merge_ok
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+i_status_ok
+
+

Parsers use it at the end of optional expressions

+
objectName si:value_state_merge
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_rewind/discard
+i_loc_pop_rewind/discard
+
+

Parsers use it at the end of sequences generating ASTs and choices +whose last branch generates an AST

+
objectName si:value_notahead_start
+

This method combines

+
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of negative lookahead predicates which +generate ASTs.

+
objectName si:void_notahead_exit
+

This method combines

+
+i_loc_pop_rewind
+i_status_negate
+
+

Parsers use it at the end of void negative lookahead predicates.

+
objectName si:value_notahead_exit
+

This method combines

+
+i_ast_pop_discard/rewind
+i_loc_pop_rewind
+i_status_negate
+
+

Parsers use it at the end of negative lookahead predicates which +generate ASTs.

+
objectName si:kleene_abort
+

This method combines

+
+i_loc_pop_rewind/discard
+i:fail_return
+
+

Parsers use it to stop a positive repetition when its first, required, expression fails.

+
objectName si:kleene_close
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+i:fail_status_ok
+i:fail_return
+
+

Parsers use it at the end of repetitions.

+
objectName si:voidvoid_branch
+

This method combines

+
+i_error_pop_merge
+i:ok_loc_pop_discard
+i:ok_return
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when both are void.

+
objectName si:voidvalue_branch
+

This method combines

+
+i_error_pop_merge
+i:ok_loc_pop_discard
+i:ok_return
+i_ast_push
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when the +failing branch is void, and the next to test generates an AST.

+
objectName si:valuevoid_branch
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_rewind/discard
+i:ok_loc_pop_discard
+i:ok_return
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when the +failing branch generates an AST, and the next to test is void.

+
objectName si:valuevalue_branch
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_discard
+i:ok_loc_pop_discard
+i:ok_return
+i_ast_rewind
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when both +generate ASTs.

+
objectName si:voidvoid_part
+

This method combines

+
+i_error_pop_merge
+i:fail_loc_pop_rewind
+i:fail_return
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and both +are void.

+
objectName si:voidvalue_part
+

This method combines

+
+i_error_pop_merge
+i:fail_loc_pop_rewind
+i:fail_return
+i_ast_push
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and the +sucessfully matched part is void, and after it an AST is generated.

+
objectName si:valuevalue_part
+

This method combines

+
+i_error_pop_merge
+i:fail_ast_pop_rewind
+i:fail_loc_pop_rewind
+i:fail_return
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and both +parts generate ASTs.

+
objectName si:value_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found:ok_ast_value_push
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a nonterminal symbol generating an +AST, whose right-hand side may have generated an AST as well.

+
objectName si:value_void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found:ok_ast_value_push
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side may generate an AST.

+
objectName si:void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a nonterminal symbol generating an +AST whose right-hand side is void.

+
objectName si:void_void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found_return
+i_loc_push
+
+

Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side is void as well.

+
objectName si:reduce_symbol_end symbol
+

This method combines

+
+i_value_clear/reduce $symbol
+i_symbol_save        $symbol
+i_error_nonterminal  $symbol
+i_ast_pop_rewind
+i_loc_pop_discard
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +using the AST generated by the right-hand side as child.

+
objectName si:void_leaf_symbol_end symbol
+

This method combines

+
+i_value_clear/leaf  $symbol
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +whose right-hand side is void.

+
objectName si:value_leaf_symbol_end symbol
+

This method combines

+
+i_value_clear/leaf  $symbol
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i_ast_pop_rewind
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +discarding the AST generated by the right-hand side.

+
objectName si:value_clear_symbol_end symbol
+

This method combines

+
+i_value_clear
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i_ast_pop_rewind
+
+

Parsers use it at the end of a void non-terminal symbol, discarding +the AST generated by the right-hand side.

+
objectName si:void_clear_symbol_end symbol
+

This method combines

+
+i_value_clear
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+
+

Parsers use it at the end of a void non-terminal symbol with a void +right-hand side.

+
objectName si:next_char tok
+
+
objectName si:next_range toks toke
+
+
objectName si:next_alnum
+
+
objectName si:next_alpha
+
+
objectName si:next_ascii
+
+
objectName si:next_ddigit
+
+
objectName si:next_digit
+
+
objectName si:next_graph
+
+
objectName si:next_lower
+
+
objectName si:next_print
+
+
objectName si:next_punct
+
+
objectName si:next_space
+
+
objectName si:next_upper
+
+
objectName si:next_wordchar
+
+
objectName si:next_xdigit
+

These methods all combine

+
+i_input_next $msg
+i:fail_return
+
+

with the appropriate i_test_xxx instruction. Parsers use them for +handling atomic expressions.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html Index: embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html @@ -0,0 +1,181 @@ + + +pt::tclparam::configuration::snit - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::tclparam::configuration::snit(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::tclparam::configuration::snit - Tcl/PARAM, Canned configuration, Snit

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::tclparam::configuration::snit ?1.0.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::tclparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::tclparam to generate +snit-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::tclparam::configuration::snit def name cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of snit-based parsers +whose class is name.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::tclparam +(pt::peg::to::tclparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html Index: embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html @@ -0,0 +1,181 @@ + + +pt::tclparam::configuration::tcloo - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt::tclparam::configuration::tcloo(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::tclparam::configuration::tcloo - Tcl/PARAM, Canned configuration, Tcloo

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::tclparam::configuration::tcloo ?1.0.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::tclparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::tclparam to generate +OO-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::tclparam::configuration::tcloo def name cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of OO-based parsers +whose class is name.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::tclparam +(pt::peg::to::tclparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_to_api.html Index: embedded/www/tcllib/files/modules/pt/pt_to_api.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/pt/pt_to_api.html @@ -0,0 +1,553 @@ + + +pt_export_api - Parser Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

pt_export_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_export_api - Parser Tools Export API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes two APIs. First the API shared by all packages +for the conversion of Parsing Expression Grammars into some other +format, and then the API shared by the packages which implement the +export plugins sitting on top of the conversion packages.

+

Its intended audience are people who wish to create their own +converter for some type of output, and/or an export plugin for +their or some other converter.

+

It resides in the Export section of the Core Layer of Parser Tools.

+

arch_core_export

+
+

Converter API

+

Any (grammar) export converter has to follow the rules set out below:

+
    +

  1. A converter is a package. Its name is arbitrary, however it is + recommended to put it under the ::pt::peg::to + namespace.

    2. +

  2. The package provides either a single Tcl command following the + API outlined below, or a class command whose instances follow + the same API. The commands which follow the API are called + converter commands.

    3. +

  3. A converter command has to provide the following three methods + with the given signatures and semantics. Converter commands + are allowed to provide more methods of their own, but not + less, and they may not provide different semantics for the + standardized methods.

    +
    +
    CONVERTER reset
    +

    This method has to reset the configuration of the converter to its +default settings. The result of the method has to be the empty +string.

    +
    CONVERTER configure
    +

    This method, in this form, has to return a dictionary containing the +current configuration of the converter.

    +
    CONVERTER configure option
    +

    This method, in this form, has to return the current value of the +specified configuration option of the converter.

    +

    Please read the section Options for the set of standard +options any converter has to accept. +Any other options accepted by a specific converter will be described +in its manpage.

    +
    CONVERTER configure option value...
    +

    This command, in this form, sets the specified options of the +converter to the given values.

    +

    Please read the section Options for the set of standard +options a converter has to accept. +Any other options accepted by a specific converter will be described +in its manpage.

    +
    CONVERTER convert serial
    +

    This method has to accept the canonical serialization of a parsing +expression grammar, as specified in section +PEG serialization format, and contained in serial. +The result of the method has to be the result of converting the input +grammar into whatever the converter is for, per its configuration.

    +
    +
    4. +
+
+

Plugin API

+

Any (grammar) export plugin has to follow the rules set out below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + pt::peg::export::FOO, + where FOO is the name of the format the plugin will + generate output for.

    3. +

  3. The plugin can expect that the package + pt::peg::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    +

    It is recommended that a plugin does check for the presence of + this package.

    4. +

  4. A plugin has to provide a single command, in the global + namespace, with the signature shown below. Plugins are allowed + to provide more command of their own, but not less, and they + may not provide different semantics for the standardized + command.

    +
    +
    ::export serial configuration
    +

    This command has to accept the canonical serialization of a parsing +expression grammar and the configuration for the converter invoked by +the plugin. The result of the command has to be the result of the +converter invoked by the plugin for th input grammar and +configuration.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +parsing expression grammar for which to generate the output. +The specification of what a canonical serialization is can be +found in the section PEG serialization format.

    +
    dictionary configuration
    +

    This argument will contain the configuration to configure the +converter with before invoking it, as a dictionary mapping from +options to values.

    +

    Please read the section Options for the set of standard +options any converter has to accept, and thus any plugin as well. +Any other options accepted by a specific plugin will be described in +its manpage.

    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of an invokation of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

Options

+

Each export converter and plugin for an export converter has to accept +the options below in their configure method. Converters are +allowed to ignore the contents of these options when performing a +conversion, but they must not reject them. Plugins are expected to +pass the options given to them to the converter they are invoking.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
+
+

Usage

+

To use a converter do

+
+    # Get the converter (single command here, not class)
+    package require the-converter-package
+    # Provide a configuration
+    theconverter configure ...
+    # Perform the conversion
+    set result [theconverter convert $thegrammarserial]
+    ... process the result ...
+
+

To use a plugin FOO do

+
+    # Get an export plugin manager
+    package require pt::peg::export
+    pt::peg::export E
+    # Provide a configuration
+    E configuration set ...
+    # Run the plugin, and the converter inside.
+    set result [E export serial $grammarserial FOO]
+    ... process the result ...
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/rc4/rc4.html Index: embedded/www/tcllib/files/modules/rc4/rc4.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/rc4/rc4.html @@ -0,0 +1,230 @@ + + +rc4 - RC4 Stream Cipher + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

rc4(n) 1.1.0 tcllib "RC4 Stream Cipher"

+

Name

+

rc4 - Implementation of the RC4 stream cipher

+
+ + +

Description

+

This package is an implementation in Tcl of the RC4 stream cipher +developed by Ron Rivest of RSA Data Security Inc. The cipher was a +trade secret of RSA but was reverse-engineered and published to the +internet in 1994. It is used in a number of network protocols for +securing communications. To evade trademark restrictions this cipher +is sometimes known as ARCFOUR.

+
+

COMMANDS

+
+
::rc4::rc4 ?-hex? -key keyvalue ?-command lst? ?-out channel? [ -in channel | -infile filename | string ]
+

Perform the RC4 algorithm on either the data provided by the argument +or on the data read from the -in channel. If an -out +channel is given then the result will be written to this channel. +Giving the -hex option will return a hexadecimal encoded +version of the result if not using an -out channel.

+

The data to be processes can be specified either as a string argument to +the rc4 command, or as a filename or a pre-opened channel. If the +-infile argument is given then the file is opened, the data read +and processed and the file is closed. If the -in argument is +given then data is read from the channel until the end of file. The +channel is not closed. If the -out argument is given then the +processing result is written to this channel.

+

If -command is provided then the rc4 command does not return +anything. Instead the command provided is called with the rc4 result data +appended as the final parameter. This is most useful when reading from Tcl +channels as a fileevent is setup on the channel and the data processed in +chunks

+

Only one of -infile, -in or string should be given.

+
+
+

PROGRAMMING INTERFACE

+
+
::rc4::RC4Init keydata
+

Initialize a new RC4 key. The keydata is any amount of binary +data and is used to initialize the cipher internal state.

+
::rc4::RC4 Key data
+

Encrypt or decrypt the input data using the key obtained by calling +RC4Init.

+
::rc4::RC4Final Key
+

This should be called to clean up resources associated with +Key. Once this function has been called the key is destroyed.

+
+
+

EXAMPLES

+
+% set keydata [binary format H* 0123456789abcdef]
+% rc4::rc4 -hex -key $keydata HelloWorld
+3cf1ae8b7f1c670b612f
+% rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f]
+HelloWorld
+
+
+ set Key [rc4::RC4Init "key data"]
+ append ciphertext [rc4::RC4 $Key $plaintext]
+ append ciphertext [rc4::RC4 $Key $additional_plaintext]
+ rc4::RC4Final $Key
+
+
+ proc ::Finish {myState data} {
+     DoStuffWith $myState $data
+ }
+ rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
+
+
+

AUTHORS

+

Pat Thoyts

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rc4 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/rcs/rcs.html Index: embedded/www/tcllib/files/modules/rcs/rcs.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/rcs/rcs.html @@ -0,0 +1,348 @@ + +rcs - RCS low level utilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

rcs(n) 2.0.2 tcllib "RCS low level utilities"

+

Name

+

rcs - RCS low level utilities

+
+ + +

Description

+

The Revision Control System, short RCS, is a set of +applications and related data formats which allow a system to persist +the history of changes to a text. It, and its relative SCCS are the +basis for many other such systems, like CVS, etc.

+

This package does not implement RCS.

+

It only provides a number of low level commands which should be useful +in the implementation of any revision management system, namely:

+
    +

  1. The conversion of texts into and out of a data structures which allow +the easy modification of such text by patches, i.e. sequences +of instructions for the transformation of one text into an other.

    2. +

  2. And the conversion of one particular format for patches, the so-called +RCS patches, into and out of data structures which allow +their easy application to texts.

    3. +
+
+

COMMANDS

+
+
::rcs::text2dict text
+

Converts the argument text into a dictionary containing and +representing the same text in an indexed form and returns that +dictionary as its result. +More information about the format of the result can be found in +section TEXT DICT DATA STRUCTURE. This command returns the +canonical representation of the input.

+
::rcs::dict2text dict
+

This command provides the complementary operation to +::rcs::text2dict. It converts a dictionary in the form described +in section TEXT DICT DATA STRUCTURE back into a text and +returns that text as its result. The command does accept non-canonical +representations of the text as its input.

+
::rcs::file2dict filename
+

This command is identical to ::rcs::text2dict, except that it +reads the text to convert from the file with path filename. The +file has to exist and must be readable as well.

+
::rcs::dict2file filename dict
+

This command is identical to ::rcs::2dict2text, except that it +stores the resulting text in the file with path filename. The +file is created if it did not exist, and must be writable. The result +of the command is the empty string.

+
::rcs::decodeRcsPatch text
+

Converts the text argument into a patch command list (PCL) as +specified in the section RCS PATCH COMMAND LIST and +returns this list as its result. +It is assumed that the input text is in diff -n format, also +known as RCS patch format, as specified in the section +RCS PATCH FORMAT. +Please note that the command ignores no-ops in the input, in other +words the resulting PCL contains only instructions doing something.

+
::rcs::encodeRcsPatch pcmds
+

This command provides the complementary operation to +::rcs::decodeRcsPatch. It convert a patch comand list (PCL) list +as specified in the section RCS PATCH COMMAND LIST back +into a text in RCS PATCH FORMAT and returns that text as its result.

+

Note that this command and ::rcs::decodeRcsPatch are not exactly +complementary, as the latter strips no-ops from its input, which the +encoder cannot put back anymore into the generated RCS patch. In other +words, the result of a decode/encode step may not match the original +input at the character level, but it will match it at the functional +level.

+
::rcs::applyRcsPatch text pcmds
+

This operation applies a patch in the form of a PCL to a text given in +the form of a dictionary and returns the modified text, again as +dictionary, as its result.

+

To handle actual text use the commands ::rcs::text2dict (or +equivalent) and ::rcs::decodeRcsPatch to transform the inputs +into data structures acceptable to this command. Analogously use the +command ::rcs::dict2text (or equivalent) to transform the +result of this command into actuall text as required.

+
+
+

TEXT DICT DATA STRUCTURE

+

A text dictionary is a dictionary whose keys are integer numbers and +text strings as the associated values. The keys represent the line +numbers of a text and the values the text of that line. Note that one +text can have many representations as a dictionary, as the index +values only have to be properly ordered for reconstruction, their +exact values do not matter. Similarly the strings may actually span +multiple physical lines.

+

The text

+
Hello World,
+how are you ?
+Fine, and you ?
+

for example can be represented by

+
{{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}}
+

or

+
{{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}}
+

or

+
{{-1 {Hello World,
+how are you ?}} {4 {Fine, and you ?}}}
+

The first dictionary is the canonical representation of the +text, with line numbers starting at 1, increasing in steps of +1 and without gaps, and each value representing exactly one +physical line.

+

All the commands creating dictionaries from text will return the +canonical representation of their input text. The commands taking a +dictionary and returning text will generally accept all +representations, canonical or not.

+

The result of applying a patch to a text dictionary will in general +cause the dictionary to become non-canonical.

+
+

RCS PATCH FORMAT

+

A patch is in general a series of instructions how to transform +an input text T into a different text T', and also encoded in text +form as well.

+

The text format for patches understood by this package is a very +simple one, known under the names RCS patch or +diff -n format.

+

Patches in this format contain only two different commands, for the +deletion of old text, and addition of new text. The replacement of +some text by a different text is handled as combination of a deletion +following by an addition.

+

The format is line oriented, with each line containing either a +command or text data associated with the preceding command. +The first line of a RCS patch is always a command line.

+

The commands are:

+
+
""
+

The empty line is a command which does nothing.

+
"astart n"
+

A line starting with the character a is a command for the +addition of text to the output. It is followed by n lines of +text data. When applying the patch the data is added just between the +lines start and start+1. The same effect is had by +appending the data to the existing text on line start. A +non-existing line start is created.

+
"dstart n"
+

A line starting with the character d is a command for the +deletion of text from the output. When applied it deletes n +lines of text, and the first line deleted is at index start.

+
+

Note that the line indices start always refer to the text which +is transformed as it is in its original state, without taking the +precending changes into account.

+

Note also that the instruction have to be applied in the order they +occur in the patch, or in a manner which produces the same result as +in-order application.

+

This is the format of results returned by the command +::rcs::decodeRcsPatch and accepted by the commands +::rcs::encodeRcsPatch and ::rcs::appplyRcsPatch +resp. +Note however that the decoder will strip no-op commands, and the +encoder will not generate no-ops, making them not fully complementary +at the textual level, only at the functional level.

+

And example of a RCS patch is

+
d1 2
+d4 1
+a4 2
+The named is the mother of all things.
+a11 3
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+
+

RCS PATCH COMMAND LIST

+

Patch command lists (sort: PCL's) are the data structures generated by +patch decoder command and accepted by the patch encoder and applicator +commands. They represent RCS patches in the form of Tcl data +structures.

+

A PCL is a list where each element represents a single patch +instruction, either an addition, or a deletion. The elements are lists +themselves, where the first item specifies the command and the +remainder represent the arguments of the command.

+
+
a
+

This is the instruction for the addition of text. It has two +arguments, the index of the line where to add the text, and the text +to add, in this order.

+
d
+

This is the instruction for the deletion of text. It has two +arguments, the index of the line where to start deleting text, and the +number of lines to delete, in this order.

+
+

This is the format returned by the patch decoder command and accepted +as input by the patch encoder and applicator commands.

+

An example for a patch command is shown below, it represents the +example RCS patch found in section RCS PATCH FORMAT.

+
{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.
+}} {a 11 {They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!}}}
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rcs of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/report/report.html Index: embedded/www/tcllib/files/modules/report/report.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/report/report.html @@ -0,0 +1,476 @@ + + +report - Matrix reports + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

report(n) 0.3.1 tcllib "Matrix reports"

+

Name

+

report - Create and manipulate report objects

+
+ + +

Description

+

This package provides report objects which can be used by the +formatting methods of matrix objects to generate tabular reports of +the matrix in various forms. The report objects defined here break +each report down into three REGIONS and ten classes of +lines (various separator- and data-lines). See the following +section for more detailed explanations.

+
+
::report::report reportName columns ?style style arg...?
+

Creates a new report object for a report having columns columns +with an associated global Tcl command whose name is +reportName. This command may be used to invoke various +configuration operations on the report. It has the following general +form:

+
+
reportName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section REPORT METHODS for more +explanations. If no style is specified the report will use +the builtin style plain as its default configuration.

+
+
::report::defstyle styleName arguments script
+

Defines the new style styleName. See section STYLES +for more information.

+
::report::rmstyle styleName
+

Deletes the style styleName. Trying to delete an unknown or +builtin style will result in an error. Beware, this command will not +check that there are no other styles depending on the deleted +one. Deleting a style which is still used by another style FOO will +result in a runtime error when FOO is applied to a newly instantiated +report.

+
::report::stylearguments styleName
+

This introspection command returns the list of arguments associated +with the style styleName.

+
::report::stylebody styleName
+

This introspection command returns the script associated with the +style styleName.

+
::report::styles
+

This introspection command returns a list containing the names of all +styles known to the package at the time of the call. The order of the +names in the list reflects the order in which the styles were +created. In other words, the first item is the predefined style +plain, followed by the first style defined by the user, and +so on.

+
+
+

REGIONS

+

The three regions are the top caption, +data area and bottom caption. These are, +roughly speaking, the title, the values to report and a title at the +bottom. The size of the caption regions can be specified by the user +as the number of rows they occupy in the matrix to format. The size of +the data area is specified implicitly.

+
+

LINES

+

TEMPLATES are associated with each of the ten line classes, +defining the formatting for this kind of line. The user is able to +enable and disable the separator lines at will, but not the data +lines. Their usage is solely determined by the number of rows +contained in the three regions. Data lines and all enabled separators +must have a template associated with them.

+

Note that the data-lines in a report and the rows in the matrix the +report was generated from are not in a 1:1 relationship if +any row in the matrix has a height greater than one.

+

The different kinds of lines and the codes used by the report methods +to address them are:

+
+
top
+

The topmost line of a report. Separates the report from anything which +came before it. The user can enable the usage of this line at will.

+
topdatasep
+

This line is used to separate the data rows in the top caption region, +if it contains more than one row and the user enabled its usage.

+
topcapsep
+

This line is used to separate the top caption and data regions, if the +top caption is not empty and the user enabled its usage.

+
datasep
+

This line is used to separate the data rows in the data region, if it +contains more than one row and the user enabled its usage.

+
botcapsep
+

This line is used to separate the data and bottom caption regions, if +the bottom caption is not empty and the user enabled its usage.

+
botdatasep
+

This line is used to separate the data rows in the bottom caption +region, if it contains more than one row and the user enabled its +usage.

+
bottom
+

The bottommost line of a report. Separates the report from anything +which comes after it. The user can enable the usage of this line at +will.

+
topdata
+

This line defines the format of data lines in the top caption region +of the report.

+
data
+

This line defines the format of data lines in the data region of the +report.

+
botdata
+

This line defines the format of data lines in the bottom caption +region of the report.

+
+
+

TEMPLATES

+

Each template is a list of strings used to format the line it is +associated with. For a report containing n columns a template +for a data line has to contain "n+1" items and a template for a +separator line "2*n+1" items.

+

The items in a data template specify the strings used to separate the +column information. Together with the corresponding items in the +separator templates they form the vertical lines in the report.

+

Note that the corresponding items in all defined templates +have to be of equal length. This will be checked by the report +object. The first item defines the leftmost vertical line and the last +item defines the rightmost vertical line. The item at index k +("1",...,"n-2") separates the information in the columns +"k-1" and "k".

+

The items in a separator template having an even-numbered index +("0","2",...) specify the column separators. The item at index +"2*k" ("0","2",...,"2*n") corresponds to the items at +index "k" in the data templates.

+

The items in a separator template having an odd-numbered index +("1","3",...) specify the strings used to form the horizontal lines in +the separator lines. The item at index "2*k+1" +("1","3",...,"2*n+1") corresponds to column "k". When +generating the horizontal lines the items are replicated to be at +least as long as the size of their column and then cut to the exact +size.

+
+

STYLES

+

Styles are a way for the user of this package to define common +configurations for report objects and then use them later during the +actual instantiation of report objects. They are defined as tcl +scripts which when executed configure the report object into the +requested configuration.

+

The command to define styles is ::report::defstyle. Its last +argument is the tcl script performing the actual +reconfiguration of the report object to obtain the requested style.

+

In this script the names of all previously defined styles are +available as commands, as are all commands found in a safe interpreter +and the configuration methods of report objects. The latter implicitly +operate on the object currently executing the style script. The +arguments declared here are available in the script as +variables. When calling the command of a previously declared style all +the arguments expected by it have to be defined in the call.

+
+

REPORT METHODS

+

The following commands are possible for report objects:

+
+
reportName destroy
+

Destroys the report, including its storage space and associated +command.

+
reportName templatecode disable|enable
+

Enables or disables the usage of the template addressed by the +templatecode. Only the codes for separator lines are allowed +here. It is not possible to enable or disable data lines.

+

Enabling a template causes the report to check all used templates for +inconsistencies in the definition of the vertical lines (See section +TEMPLATES).

+
reportName templatecode enabled
+

Returns the whether the template addressed by the templatecode +is currently enabled or not.

+
reportName templatecode get
+

Returns the template currently associated with the kind of line +addressed by the templatecode. All known templatecodes are +allowed here.

+
reportName templatecode set templatedata
+

Sets the template associated with the kind of line addressed by the +templatecode to the new value in templatedata. See section +TEMPLATES for constraints on the length of templates.

+
reportName tcaption ?size?
+

Specifies the size of the top caption region as the number rows +it occupies in the matrix to be formatted. Only numbers greater than +or equal to zero are allowed. If no size is specified the +command will return the current size instead.

+

Setting the size of the top caption to a value greater than zero +enables the corresponding data template and causes the report to check +all used templates for inconsistencies in the definition of the +vertical lines (See section TEMPLATES).

+
reportName bcaption size
+

Specifies the size of the bottom caption region as the number +rows it occupies in the matrix to be formatted. Only numbers greater +than or equal to zero are allowed. If no size is specified the +command will return the current size instead.

+

Setting the size of the bottom caption to a value greater than zero +enables the corresponding data template and causes the report to check +all used templates for inconsistencies in the definition of the +vertical lines (See section TEMPLATES).

+
reportName size column ?number|dyn?
+

Specifies the size of the column in the output. The value +dyn means that the columnwidth returned by the matrix to be +formatted for the specified column shall be used. The formatting of +the column is dynamic. If a fixed number is used instead of +dyn it means that the column has a width of that many +characters (padding excluded). Only numbers greater than zero are +allowed here.

+

If no size specification is given the command will return the current +size of the column instead.

+
reportName sizes ?size-list?
+

This method allows the user to specify the sizes of all columns in one +call. Its argument is a list containing the sizes to associate with +the columns. The first item is associated with column 0, the next with +column 1, and so on.

+

If no size-list is specified the command will return a list +containing the currently set sizes instead.

+
reportName pad column ?left|right|both ?padstring??
+

This method allows the user to specify padding on the left, right or +both sides of a column. If the padstring is not specified +it defaults to a single space character. Note: An alternative +way of specifying the padding is to use vertical separator strings +longer than one character in the templates (See section +TEMPLATES).

+

If no pad specification is given at all the command will return the +current state of padding for the column instead. This will be a list +containing two elements, the first element the left padding, the +second describing the right padding.

+
reportName justify column ?left|right|center?
+

Declares how the cell values for a column are filled into the +report given the specified size of a column in the report.

+

For left and right justification a cell value +shorter than the width of the column is bound with its named edge to +the same edge of the column. The other side is filled with spaces. In +the case of center the spaces are placed to both sides of the +value and the left number of spaces is at most one higher than the +right number of spaces.

+

For a value longer than the width of the column the value is cut at +the named edge. This means for left justification that the +tail (i.e. the right part) of the value is made +visible in the output. For center the value is cut at both +sides to fit into the column and the number of characters cut at the +left side of the value is at most one less than the number of +characters cut from the right side.

+

If no justification was specified the command will return the current +justification for the column instead.

+
reportName printmatrix matrix
+

Formats the matrix according to the configuration of the report +and returns the resulting string. The matrix has to have the same +number of columns as the report. The matrix also has to have enough +rows so that the top and bottom caption regions do not overlap. The +data region is allowed to be empty.

+
reportName printmatrix2channel matrix chan
+

Formats the matrix according to the configuration of the report +and writes the result into the channel chan. The matrix has to +have the same number of columns as the report. The matrix also has to +have enough rows so that the top and bottom caption regions do not +overlap. The data region is allowed to be empty.

+
reportName columns
+

Returns the number of columns in the report.

+
+

The methods size, pad and justify all take +a column index as their first argument. This index is allowed to use +all the forms of an index as accepted by the lindex command. The +allowed range for indices is + "0,...,[reportName columns]-1".

+
+

EXAMPLES

+

Our examples define some generally useful report styles.

+

A simple table with lines surrounding all information and vertical +separators, but without internal horizontal separators.

+
+    ::report::defstyle simpletable {} {
+	data	set [split "[string repeat "| "   [columns]]|"]
+	top	set [split "[string repeat "+ - " [columns]]+"]
+	bottom	set [top get]
+	top	enable
+	bottom	enable
+    }
+
+

An extension of a simpletable, see above, with a title area.

+
+    ::report::defstyle captionedtable {{n 1}} {
+	simpletable
+	topdata   set [data get]
+	topcapsep set [top get]
+	topcapsep enable
+	tcaption $n
+    }
+
+

Given the definitions above now an example which actually formats a +matrix into a tabular report. It assumes that the matrix actually +contains useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % r printmatrix m
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % m format 2string r
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category report of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/rest/rest.html Index: embedded/www/tcllib/files/modules/rest/rest.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/rest/rest.html @@ -0,0 +1,321 @@ + + +rest - A framework for RESTful web services + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

rest(n) 1.0 tcllib "A framework for RESTful web services"

+

Name

+

rest - define REST web APIs and call them inline or asychronously

+
+ + +

Description

+

There are 2 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 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, a simple call is easier and quicker to implement but less featureful. It takes the url and a few options on 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 http method procedures and then check or process the returned data yourself

+
+
::rest::simple url query ?config? ?body?
+
+
::rest::get url query ?config? ?body?
+
+
::rest::post url query ?config? ?body?
+
+
::rest::head url query ?config? ?body?
+
+
::rest::put url query ?config? ?body?
+
+
::rest::delete url query ?config? ?body?
+
+
+

The above 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? dict, otherwise it defaults to get. If a body is needed then the config dict must be present, however it may be empty.

+
+    set appid APPID
+    set search tcl
+    set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]]
+    set res [rest::format_json $res]
+
+
+    set res [rest::simple http://twitter.com/statuses/update.json  [list status $text]  {
+          method post
+          auth {basic user password}
+          format json
+        }
+    ]
+
+

the options supported in the config dict are as follows +headers +cookie +auth +format +method +content-type +Interface usage +An interface to a REST API consists of a series of definitions of REST calls contained in an array. The array name becomes a namespace containing the defined commands. Each array element defines the name of the call and takes the form of a dict, aka key/value pairs. These keys are the defined configuration options below. +After creating the definitions simply call rest::create_interface on the array to create the commands.

+
+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]
+
+

::${name}::basic_auth u p +::${name}::set_static_args ?args?]

+
+
::rest::save name file
+

saves a copy of the dynamically created procs to a file for later loading

+
::rest::describe name
+

print a description of defined api calls

+
::rest::parameters url ?args?
+

parse a url query string into a dict

+
::rest::parse_opts static required optional string
+
+
::rest::substitute string ?var?
+

take a string and substitute real values for any option identifiers

+
::rest::create_interface name
+

TOKENS + the value is substituted into the url at call time. tokens in the form of %name:default_value% will be an optional argument with a default value. +url + the target of the http request +description + a string which describes the call. used only for

+
describe
+

body + indicates if arguments are required for the request body or not. should + be one of none, optional, required, argument or mime_multipart. default is optional. + if argument is used then the option is parsed as a list where the second value is the name + of a option. the body will then be used as the value for that option. + if the value is mime_multipart then the body is required and interpreted as each argument + representing one part of a mime multipart document. each argument should be a 2 item list with the first being + a list of header keys and values, and the second being the mime part body.

+
+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
+
+
+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]
+
+

method + The HTTP method to call on the url. The default is GET. +copy + this copies the definition of a previously defined call. after copying you can override selected options by defining them again. +unset + removes the named option. useful when using copy of another definition. +headers + the value must be another dict containing header fields and their values. The default is to not add any additional headers. +content-type + Specifies the content type for the request data. +req_args + a list of the required arguments. names ending in a colon will require a value. +opt_args + arguments that may be present but are not required. +static_args + arguments that are always the same. no sense in troubling the user with these. A leading - is allowed but not required to maintain consistancy with the command line. +auth + should be one of basic or sign. if basic is used you can configure basic auth with the proc auth_basic which takes 2 arguments, the username and password. + if sign is specified then the value must be a list with the second element being the name of a proc which will be called to perform the request signing.

+
+set delicious(updated) {
+    url https://api.del.icio.us/v1/posts/update
+    auth basic
+}
+rest::create_interface flickr
+flickr::basic_auth username password
+
+
+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
+}
+
+

callback + If this option is present then the method will be created as an async call. An async call will return immediately with the value of the http token. The event loop must be active to use this option. The value of this option is the name of a proc which is invoked when the HTTP call is complete. The proc receives three arguments, the name of the calling procedure, the status of the result (one of OK or ERROR), and the data associated with the result. + the http request header is available via

+
uplevel token token
+

cookie + a list of cookies to be passed in the http header. this is just a shortcut to the headers option +input_transform + commands which take the variable $query and transform it in some manner before returning a new value. return value must be a dict which will be passed to http::formatQuery + the request body is accessible via

+
upvar body body
+

format or result + defines the format of the returned data. should be one of discard, raw, json, xml, or tdom. the default is auto which should auto detect between xml and json. rss is formated as + a special case of xml. +pre_transform + this value takes the form of a proc which should perform some action on $result and return a value. it is run on the result before the output (xml/json/etc) transformation is done. + the http request header is available via

+
uplevel token token
+

result + may have the value xml, json, tdom, raw, or auto. the default is auto and should auto detect json or xml results and transform them into a tcl list. this is here if you want to specify it explicitly. +post_transform + this value takes the form of a proc which should perform some action on $result and return a value. it is run on the result after the output transformation but before returning the value to the calling procedure. + the http request header is available via

+
uplevel token token
+

check_result + this value should be a list of 2 expressions either of which may be empty. the first expression is checks the OK condition, it must return true when the result is satisfactory. the second expression is the error condition, it must return false unless there is an error.

+
+
+

INCLUDED

+

functional but incomplete implementations are included for the following services: +flickr +twitter +yahoo boss +yahoo weather +google calendar +facebook +del.icio.us +read the file or source it and use describe for more information. also see the +developers documentation on the respective sites.

+
+
ADDED embedded/www/tcllib/files/modules/ripemd/ripemd128.html Index: embedded/www/tcllib/files/modules/ripemd/ripemd128.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ripemd/ripemd128.html @@ -0,0 +1,277 @@ + +ripemd128 - RIPEMD Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ripemd128(n) 1.0.3 tcllib "RIPEMD Message-Digest Algorithm"

+

Name

+

ripemd128 - RIPEMD-128 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the RIPEMD-128 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and +generates a 128-bit message digest from the input. The RIPEMD-128 +algorithm is based upon the MD4 algorithm (2, 4) but has been +cryptographically strengthened against weaknesses that have been found +in MD4 (4). RIPEMD-128 has been designed to be a drop-in replacement +for MD4 and MD5 (5). If security is the major consideration, then +RIPEMD-160 or SHA1 should be considered.

+

This package will use Trf to +accelerate the digest computation if available. In +the absence of an accelerator package the pure-Tcl implementation will +be used.

+
+

COMMANDS

+
+
::ripemd::ripemd128 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the RIPEMD-128 digest of the data given in string. This is +returned as a binary string by default. Giving the -hex option +will return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the ripemd128 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::ripemd::hmac128 ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the +RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and +provide a RIPEMD-128 digest that includes a key. All options other +than -key are as for the ::ripemd::ripemd128 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, hash functions can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +uniquely derived from the data that was poured into the bucket. The +programming interface to the hash operates on a token (equivalent to the +bucket). You call RIPEMD128Init to obtain a token and then call +RIPEMD128Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +RIPEMD128Final. An equivalent set of functions gives you a keyed +digest (HMAC).

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Alternatively if both the Trf and Memchan +extensions are available then these will be used. Finally the package +will revert to a pure-Tcl implementation. The programming interface +remains the same, however.

+
+
::ripemd::RIPEMD128Init
+

Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the +remaining functions.

+
::ripemd::RIPEMD128Update token data
+

Add data to the hash identified by token. Calling +RIPEMD128Update $token "abcd" is equivalent to calling +RIPEMD128Update $token "ab" followed by +RIPEMD128Update $token "cb". See EXAMPLES.

+
::ripemd::RIPEMD128Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit +RIPEMD-128 digest value.

+
::ripemd::RIPEHMAC128Init key
+

This is equivalent to the ::ripemd::RIPEMD128Init command +except that it requires the key that will be included in the HMAC.

+
::ripemd::RIPEHMAC128Update token data
+
+
::ripemd::RIPEHMAC128Final token
+

These commands are identical to the RIPEMD128 equivalent commands.

+
+
+

EXAMPLES

+
+% ripemd::ripemd128 -hex "Tcl does RIPEMD-128"
+3cab177bae65205d81e7978f63556c63
+
+
+% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128"
+b359dc5971a05beea0be7b106b30e389
+
+
+% set tok [ripemd::RIPEMD128Init]
+::ripemd::1
+% ripemd::RIPEMD128Update $tok "Tcl "
+% ripemd::RIPEMD128Update $tok "does "
+% ripemd::RIPEMD128Update $tok "RIPEMD-128"
+% ripemd::Hex [ripemd::RIPEMD128Final $tok]
+3cab177bae65205d81e7978f63556c63
+
+
+

REFERENCES

+
    +

  1. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    4. +

  4. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology + vol 11 (4), pp. 253-271 (1998)

    5. +

  5. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    6. +

  6. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    7. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ripemd of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/ripemd/ripemd160.html Index: embedded/www/tcllib/files/modules/ripemd/ripemd160.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/ripemd/ripemd160.html @@ -0,0 +1,266 @@ + +ripemd160 - RIPEMD Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

ripemd160(n) 1.0.3 tcllib "RIPEMD Message-Digest Algorithm"

+

Name

+

ripemd160 - RIPEMD-160 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the RIPEMD-160 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and +generates a 160-bit message digest from the input. The RIPEMD-160 +algorithm is based upon the MD4 algorithm (2, 4) but has been +cryptographically strengthened against weaknesses that have been found +in MD4 (4).

+

This package will use cryptkit or Trf to +accelerate the digest computation if either package is available. In +the absence of an accelerator package the pure-Tcl implementation will +be used.

+
+

COMMANDS

+
+
::ripemd::ripemd160 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the RIPEMD-160 digest of the data given in string. This is +returned as a binary string by default. Giving the -hex option +will return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the ripemd160 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::ripemd::hmac160 ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the +RIPEMD-160 digest algorithm. HMACs are described in RFC 2104 (5) and +provide a RIPEMD-160 digest that includes a key. All options other +than -key are as for the ::ripemd::ripemd160 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, hash functions can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +uniquely derived from the data that was poured into the bucket. The +programming interface to the hash operates on a token (equivalent to the +bucket). You call RIPEMD160Init to obtain a token and then call +RIPEMD160Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +RIPEMD160Final. An equivalent set of functions gives you a keyed +digest (HMAC).

+
+
::ripemd::RIPEMD160Init
+

Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the +remaining functions.

+
::ripemd::RIPEMD160Update token data
+

Add data to the hash identified by token. Calling +RIPEMD160Update $token "abcd" is equivalent to calling +RIPEMD160Update $token "ab" followed by +RIPEMD160Update $token "cb". See EXAMPLES.

+
::ripemd::RIPEMD160Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 160 bit +RIPEMD-160 digest value.

+
::ripemd::RIPEHMAC160Init key
+

This is equivalent to the ::ripemd::RIPEMD160Init command +except that it requires the key that will be included in the HMAC.

+
::ripemd::RIPEHMAC160Update token data
+
+
::ripemd::RIPEHMAC160Final token
+

These commands are identical to the RIPEMD160 equivalent commands.

+
+
+

EXAMPLES

+
+% ripemd::ripemd160 -hex "Tcl does RIPEMD-160"
+0829dea75a1a7074c702896723fe37763481a0a7
+
+
+% ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160"
+bf0c927231733686731dddb470b64a9c23f7f53b
+
+
+% set tok [ripemd::RIPEMD160Init]
+::ripemd::1
+% ripemd::RIPEMD160Update $tok "Tcl "
+% ripemd::RIPEMD160Update $tok "does "
+% ripemd::RIPEMD160Update $tok "RIPEMD-160"
+% ripemd::Hex [ripemd::RIPEMD160Final $tok]
+0829dea75a1a7074c702896723fe37763481a0a7
+
+
+

REFERENCES

+
    +

  1. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    4. +

  4. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology + vol 11 (4), pp. 253-271 (1998)

    5. +

  5. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    6. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ripemd of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/sasl/sasl.html Index: embedded/www/tcllib/files/modules/sasl/sasl.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/sasl/sasl.html @@ -0,0 +1,394 @@ + + +SASL - Simple Authentication and Security Layer (SASL) + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

SASL(n) 1.3.0 tcllib "Simple Authentication and Security Layer (SASL)"

+

Name

+

SASL - Implementation of SASL mechanisms for Tcl

+
+ + +

Description

+

The Simple Authentication and Security Layer (SASL) is a framework +for providing authentication and authorization to comunications +protocols. The SASL framework is structured to permit negotiation +among a number of authentication mechanisms. SASL may be used in +SMTP, IMAP and HTTP authentication. It is also in use in XMPP, LDAP +and BEEP. See MECHANISMS for the set of available SASL +mechanisms provided with tcllib.

+

The SASL framework operates using a simple multi-step challenge +response mechanism. All the mechanisms work the same way although the +number of steps may vary. In this implementation a callback procedure +must be provided from which the SASL framework will obtain users +details. See CALLBACK PROCEDURE for details of this +procedure.

+
+

COMMANDS

+
+
::SASL::new option value ?...?
+

Contruct a new SASL context. See OPTIONS for details of the +possible options to this command. A context token is required for most +of the SASL procedures.

+
::SASL::configure option value ?...?
+

Modify and inspect the SASL context option. See OPTIONS for +further details.

+
::SASL::step context challenge ?...?
+

This is the core procedure for using the SASL framework. The +step procedure should be called until it returns 0. Each step takes a +server challenge string and the response is calculated and stored in +the context. Each mechanism may require one or more steps. For some +steps there may be no server challenge required in which case an empty +string should be provided for this parameter. All mechanisms should accept +an initial empty challenge.

+
::SASL::response context
+

Returns the next response string that should be sent to the server.

+
::SASL::reset context
+

Re-initialize the SASL context. Discards any internal state and +permits the token to be reused.

+
::SASL::cleanup context
+

Release all resources associated with the SASL context. The context +token may not be used again after this procedure has been called.

+
::SASL::mechanisms ?type? ?minimum?
+

Returns a list of all the available SASL mechanisms. The list is +sorted by the mechanism preference value (see register) with the +preferred mechanisms and the head of the list. Any mechanism with a +preference value less than theminimum (which defaults to 0) is removed +from the returned list. This permits a security threshold to be set. Mechanisms +with a preference less that 25 transmit authentication are particularly +susceptible to eavesdropping and should not be provided unless a secure +channel is in use (eg: tls).

+

The type parameter +may be one of client or server and defaults to client. +Only mechanisms that have an implementation matching the type are +returned (this permits servers to correctly declare support only for +mechanisms that actually provide a server implementation).

+
::SASL::register mechanism preference clientproc ?serverproc?
+

New mechanisms can be added to the package by registering the +mechanism name and the implementing procedures. The server procedure +is optional. The preference value is an integer that is used to order +the list returned by the mechanisms command. Higher values +indicate a preferred mechanism. If the mechanism is already registered +then the recorded values are updated.

+
+
+

OPTIONS

+
+
-callback
+

Specify a command to be evaluated when the SASL mechanism requires +information about the user. The command is called with the current +SASL context and a name specifying the information desired. See +EXAMPLES.

+
-mechanism
+

Set the SASL mechanism to be used. See mechanisms for a list of +supported authentication mechanisms.

+
-service
+

Set the service type for this context. Some mechanisms may make use of +this parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it +defaults to an empty string. If the -type is set to 'server' +then this option should be set to a valid service identity. Some +examples of valid service names are smtp, ldap, beep and xmpp.

+
-server
+

This option is used to set the server name used in SASL challenges +when operating as a SASL server.

+
-type
+

The context type may be one of 'client' or 'server'. The default is to +operate as a client application and respond to server +challenges. Mechanisms may be written to support server-side SASL and +setting this option will cause each step to issue the next +challenge. A new context must be created for each incoming client +connection when in server mode.

+
+
+

CALLBACK PROCEDURE

+

When the SASL framework requires any user details it will call the +procedure provided when the context was created with an argument that +specfies the item of information required.

+

In all cases a single response string should be returned.

+
+
login
+

The callback procedure should return the users authorization identity. +Return an empty string unless this is to be different to the authentication +identity. Read [1] for a discussion about the specific meaning of +authorization and authentication identities within SASL.

+
username
+

The callback procedure should return the users authentication identity. +Read [1] for a discussion about the specific meaning of +authorization and authentication identities within SASL.

+
password
+

The callback procedure should return the password that matches the +authentication identity as used within the current realm.

+

For server mechanisms the password callback should always be called with +the authentication identity and the realm as the first two parameters.

+
realm
+

Some SASL mechanisms use realms to partition authentication identities. +The realm string is protocol dependent and is often the current DNS +domain or in the case of the NTLM mechanism it is the Windows NT domain name.

+
hostname
+

Returns the client host name - typically [info host].

+
+
+

MECHANISMS

+
+
ANONYMOUS
+

As used in FTP this mechanism only passes an email address for +authentication. The ANONYMOUS mechanism is specified in [2].

+
PLAIN
+

This is the simplest mechanism. The users authentication details are +transmitted in plain text. This mechanism should not be provided +unless an encrypted link is in use - typically after SSL or TLS has +been negotiated.

+
LOGIN
+

The LOGIN [1] mechanism transmits the users details with base64 +encoding. This is no more secure than PLAIN and likewise should not be +used without a secure link.

+
CRAM-MD5
+

This mechanism avoids sending the users password over the network in +plain text by hashing the password with a server provided random value +(known as a nonce). A disadvantage of this mechanism is that the +server must maintain a database of plaintext passwords for +comparison. CRAM-MD5 was defined in [4].

+
DIGEST-MD5
+

This mechanism improves upon the CRAM-MD5 mechanism by avoiding the +need for the server to store plaintext passwords. With digest +authentication the server needs to store the MD5 digest of the users +password which helps to make the system more secure. As in CRAM-MD5 +the password is hashed with a server nonce and other data before being +transmitted across the network. Specified in [3].

+
OTP
+

OTP is the One-Time Password system described in RFC 2289 [6]. +This mechanism is secure against replay attacks and also avoids storing +password or password equivalents on the server. Only a digest of a seed +and a passphrase is ever transmitted across the network. Requires the +otp package from tcllib and one or more of the cryptographic +digest packages (md5 or sha-1 are the most commonly used).

+
NTLM
+

This is a proprietary protocol developed by Microsoft [5] and is +in common use for authenticating users in a Windows network +environment. NTLM uses DES encryption and MD4 digests of the users +password to authenticate a connection. Certain weaknesses have been +found in NTLM and thus there are a number of versions of the protocol. +As this mechanism has additional dependencies it is made available as +a separate sub-package. To enable this mechanism your application must +load the SASL::NTLM package.

+
X-GOOGLE-TOKEN
+

This is a proprietary protocol developed by Google and used for +authenticating users for the Google Talk service. This mechanism makes +a pair of HTTP requests over an SSL channel and so this mechanism +depends upon the availability of the tls and http packages. To enable +this mechanism your application must load the SASL::XGoogleToken package. +In addition you are recommended to make use of the autoproxy package to +handle HTTP proxies reasonably transparently.

+
+
+

EXAMPLES

+

See the examples subdirectory for more complete samples using SASL +with network protocols. The following should give an idea how the SASL +commands are to be used. In reality this should be event +driven. Each time the step command is called, the last server +response should be provided as the command argument so that the SASL +mechanism can take appropriate action.

+
+proc ClientCallback {context command args} {
+    switch -exact -- $command {
+        login    { return "" }
+        username { return $::tcl_platform(user) }
+        password { return "SecRet" }
+        realm    { return "" }
+        hostname { return [info host] }
+        default  { return -code error unxpected }
+    }
+}
+proc Demo {{mech PLAIN}} {
+    set ctx [SASL::new -mechanism $mech -callback ClientCallback]
+    set challenge ""
+    while {1} {
+        set more_steps [SASL::step $ctx challenge]
+        puts "Send '[SASL::response $ctx]'"
+        puts "Read server response into challenge var"
+        if {!$more_steps} {break}
+    }
+    SASL::cleanup $ctx
+}
+
+
+

REFERENCES

+
    +

  1. Myers, J. "Simple Authentication and Security Layer (SASL)", + RFC 2222, October 1997. + (http://www.ietf.org/rfc/rfc2222.txt)

    2. +

  2. Newman, C. "Anonymous SASL Mechanism", + RFC 2245, November 1997. + (http://www.ietf.org/rfc/rfc2245.txt)

    3. +

  3. Leach, P., Newman, C. "Using Digest Authentication as a SASL + Mechanism", RFC 2831, May 2000, + (http://www.ietf.org/rfc/rfc2831.txt)

    4. +

  4. Klensin, J., Catoe, R. and Krumviede, P., + "IMAP/POP AUTHorize Extension for Simple Challenge/Response" + RFC 2195, September 1997. + (http://www.ietf.org/rfc/rfc2195.txt)

    5. +

  5. No official specification is available. However, + http://davenport.sourceforge.net/ntlm.html provides a good + description.

    6. +

  6. Haller, N. et al., "A One-Time Password System", + RFC 2289, February 1998, + (http://www.ieft.org/rfc/rfc2289.txt)

    7. +
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/sha1/sha1.html Index: embedded/www/tcllib/files/modules/sha1/sha1.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/sha1/sha1.html @@ -0,0 +1,271 @@ + +sha1 - SHA-x Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

sha1(n) 2.0.3 tcllib "SHA-x Message-Digest Algorithm"

+

Name

+

sha1 - SHA1 Message-Digest Algorithm

+
+ + +

Description

+

This package provides an implementation in Tcl of the SHA1 +message-digest algorithm as specified by FIPS PUB 180-1 (1). This +algorithm takes a message and generates a 160-bit digest from the +input. The SHA1 algorithm is related to the MD4 algorithm (2) but has +been strengthend against certain types of cryptographic attack. SHA1 +should be used in preference to MD4 or MD5 in new applications.

+

This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA1 as the +message-digest.

+
+

COMMANDS

+
+
::sha1::sha1 ?-hex|-bin? [ -channel channel | -file filename | string ]
+

The command takes a message and returns the SHA1 digest of this message +as a hexadecimal string. You may request the result as binary data by +giving -bin.

+

The data to be hashed can be specified either as a string argument to +the sha1 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed. NOTE use of the channel or filename +options results in the internal use of vwait. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below).

+

Only one of -file, -channel or string should be given.

+
::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.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the SHA1 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the SHA1 hash operates on a token (equivalent to the +bucket). You call SHA1Init to obtain a token and then call +SHA1Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +SHA1Final. An equivalent set of functions gives you a keyed digest +(HMAC).

+

If you have critcl and have built the tcllibc package +then the implementation of the hashing function will be performed by compiled +code. Failing that if you have the Trf package then this can +be used otherwise there is a pure-tcl equivalent. The programming +interface remains the same in all cases.

+
+
::sha1::SHA1Init
+

Begins a new SHA1 hash. Returns a token ID that must be used for the +remaining functions.

+
::sha1::SHA1Update token data
+

Add data to the hash identified by token. Calling +SHA1Update $token "abcd" is equivalent to calling +SHA1Update $token "ab" followed by +SHA1Update $token "cb". See EXAMPLES.

+
::sha1::SHA1Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 20 bytes representing the 160 bit SHA1 +digest value.

+
::sha1::HMACInit key
+

This is equivalent to the ::sha1::SHA1Init command except that +it requires the key that will be included in the HMAC.

+
::sha1::HMACUpdate token data
+
+
::sha1::HMACFinal token
+

These commands are identical to the SHA1 equivalent commands.

+
+
+

EXAMPLES

+
+% sha1::sha1 "Tcl does SHA1"
+285a6a91c45a9066bf39fcf24425796ef0b2a8bf
+
+
+% sha1::hmac Sekret "Tcl does SHA1"
+ae6251fa51b95b18cba2be95eb031d07475ff03c
+
+
+% set tok [sha1::SHA1Init]
+::sha1::1
+% sha1::SHA1Update $tok "Tcl "
+% sha1::SHA1Update $tok "does "
+% sha1::SHA1Update $tok "SHA1"
+% sha1::Hex [sha1::SHA1Final $tok]
+285a6a91c45a9066bf39fcf24425796ef0b2a8bf
+
+
+

REFERENCES

+
    +

  1. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sha1 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/sha1/sha256.html Index: embedded/www/tcllib/files/modules/sha1/sha256.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/sha1/sha256.html @@ -0,0 +1,280 @@ + +sha256 - SHA-x Message-Digest Algorithm + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

sha256(n) 1.0.3 tcllib "SHA-x Message-Digest Algorithm"

+

Name

+

sha256 - SHA256 Message-Digest Algorithm

+
+ + +

Description

+

This package provides an implementation in Tcl of the SHA256 and +SHA224 message-digest algorithms as specified by FIPS PUB 180-1 +(1). These algorithms take a message and generates a 256-bit (224-bit) +digest from the input. The SHA2 algorithms are related to the SHA1 +algorithm.

+

This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA256 as the +message-digest.

+
+

COMMANDS

+
+
::sha2::sha256 ?-hex|-bin? [ -channel channel | -file filename | string ]
+

The command takes a message and returns the SHA256 digest of this +message as a hexadecimal string. You may request the result as binary +data by giving -bin.

+

The data to be hashed can be specified either as a string argument to +the sha256 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed. NOTE use of the channel or filename +options results in the internal use of vwait. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below).

+

Only one of -file, -channel or string should be given.

+
::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.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the SHA256 hash can be viewed as a bucket into +which one pours data. When you have finished, you extract a value that +is derived from the data that was poured into the bucket. The +programming interface to the SHA256 hash operates on a token +(equivalent to the bucket). You call SHA256Init to obtain a +token and then call SHA256Update as many times as required to +add data to the hash. To release any resources and obtain the hash +value, you then call SHA256Final. An equivalent set of +functions gives you a keyed digest (HMAC).

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Failing that there is a pure-tcl +equivalent. The programming interface remains the same in all cases.

+
+
::sha2::SHA256Init
+
+
::sha2::SHA224Init
+

Begins a new SHA256/SHA224 hash. Returns a token ID that must be used +for the remaining functions.

+
::sha2::SHA256Update token data
+

Add data to the hash identified by token. Calling +SHA256Update $token "abcd" is equivalent to calling +SHA256Update $token "ab" followed by +SHA256Update $token "cb". See EXAMPLES. +Note that this command is used for both SHA256 and SHA224. Only the +initialization and finalization commands of both hashes differ.

+
::sha2::SHA256Final token
+
+
::sha2::SHA224Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 32/28 bytes representing the 256/224 bit +SHA256 / SHA224 digest value.

+
::sha2::HMACInit key
+

This is equivalent to the ::sha2::SHA256Init command except +that it requires the key that will be included in the HMAC.

+
::sha2::HMACUpdate token data
+
+
::sha2::HMACFinal token
+

These commands are identical to the SHA256 equivalent commands.

+
+
+

EXAMPLES

+
+% sha2::sha256 "Tcl does SHA256"
+0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
+
+
+% sha2::hmac Sekret "Tcl does SHA256"
+4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
+
+
+% set tok [sha2::SHA256Init]
+::sha2::1
+% sha2::SHA256Update $tok "Tcl "
+% sha2::SHA256Update $tok "does "
+% sha2::SHA256Update $tok "SHA256"
+% sha2::Hex [sha2::SHA256Final $tok]
+0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
+
+
+

REFERENCES

+
    +

  1. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sha1 of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/annealing.html Index: embedded/www/tcllib/files/modules/simulation/annealing.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/simulation/annealing.html @@ -0,0 +1,324 @@ + + +simulation::annealing - Tcl Simulation Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

simulation::annealing(n) 0.2 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::annealing - Simulated annealing

+
+ + +

Description

+

The technique of simulated annealing provides methods to +estimate the global optimum of a function. It is described in some +detail on the Wiki http://wiki.tcl.tk/.... The idea is simple:

+
    +

  • randomly select points within a given search space

    • +

  • evaluate the function to be optimised for each of these +points and select the point that has the lowest (or highest) +function value or - sometimes - accept a point that has a less optimal +value. The chance by which such a non-optimal point is accepted diminishes over +time.

    • +

  • Accepting less optimal points means the method does not necessarily get +stuck in a local optimum and theoretically it is capable of finding the +global optimum within the search space.

    • +
+

The method resembles the cooling of material, hence the name.

+

The package simulation::annealing offers the command findMinimum:

+
+    puts [::simulation::annealing::findMinimum  -trials 300  -parameters {x -5.0 5.0 y -5.0 5.0}  -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
+
+

prints the estimated minimum value of the function f(x,y) = +x**2+y**2+sin(10*x)+4*cos(20*y) and the values of x and y where +the minimum was attained:

+
+result -4.9112922923 x -0.181647676593 y 0.155743646974
+
+
+

PROCEDURES

+

The package defines the following auxiliary procedures:

+
+
::simulation::annealing::getOption keyword
+

Get the value of an option given as part of the findMinimum +command.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::annealing::hasOption keyword
+

Returns 1 if the option is available, 0 if not.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::annealing::setOption keyword value
+

Set the value of the given option.

+
+
string keyword
+

Given keyword (without leading minus)

+
string value
+

(New) value for the option

+
+
+

The main procedures are findMinimum and findCombinatorialMinimum:

+
+
::simulation::annealing::findMinimum args
+

Find the minimum of a function using simulated annealing. The function +and the method's parameters is given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
::simulation::annealing::findCombinatorialMinimum args
+

Find the minimum of a function of discrete variables using simulated +annealing. The function and the method's parameters is given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
+

The findMinimum command predefines the following options:

+
    +

  • -parameters list: triples defining parameters and ranges

    • +

  • -function expr: expression defining the function

    • +

  • -code body: body of code to define the function (takes +precedence over -function). The code should set the variable +"result"

    • +

  • -init code: code to be run at start up +-final code: code to be run at the end +-trials n: number of trials before reducing the temperature +-reduce factor: reduce the temperature by this factor (between 0 and 1) +-initial-temp t: initial temperature +-scale s: scale of the function (order of magnitude of the values) +-estimate-scale y/n: estimate the scale (only if -scale +is not present) +-verbose y/n: print detailed information on progress to the +report file (1) or not (0) +-reportfile file: opened file to print to (defaults to stdout)

    • +
+

Any other options can be used via the getOption procedure +in the body. +The findCombinatorialMinimum command predefines the following +options:

+
    +

  • -number-params n: number of binary parameters (the solution +space consists of lists of 1s and 0s). This is a required option.

    • +

  • -initial-values: list of 1s and 0s constituting the start of +the search.

    • +
+

The other predefined options are identical to those of findMinimum.

+
+

TIPS

+

The procedure findMinimum works by constructing a temporary +procedure that does the actual work. It loops until the point +representing the estimated optimum does not change anymore within the +given number of trials. As the temperature gets lower and lower the +chance of accepting a point with a higher value becomes lower too, so +the procedure will in practice terminate.

+

It is possible to optimise over a non-rectangular region, but some care +must be taken:

+
    +

  • If the point is outside the region of interest, you can specify a very +high value.

    • +

  • This does mean that the automatic determination of a scale factor is +out of the question - the high function values that force the point +inside the region would distort the estimation.

    • +
+

Here is an example of finding an optimum inside a circle:

+
+    puts [::simulation::annealing::findMinimum  -trials 3000  -reduce 0.98  -parameters {x -5.0 5.0 y -5.0 5.0}  -code {
+            if { hypot($x-5.0,$y-5.0) < 4.0 } {
+                set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
+            } else {
+                set result 1.0e100
+            }
+        }]
+
+

The method is theoretically capable of determining the global optimum, +but often you need to use a large number of trials and a slow reduction +of temperature to get reliable and repeatable estimates.

+

You can use the -final option to use a deterministic optimization +method, once you are sure you are near the required optimum.

+

The findCombinatorialMinimum procedure is suited for situations +where the parameters have the values 0 or 1 (and there can be many of +them). Here is an example:

+
    +

  • We have a function that attains an absolute minimum if the first ten +numbers are 1 and the rest is 0:

    +
    +proc cost {params} {
+    set cost 0
+    foreach p [lrange $params 0 9] {
+        if { $p == 0 } {
+            incr cost
+        }
+    }
+    foreach p [lrange $params 10 end] {
+        if { $p == 1 } {
+            incr cost
+        }
+    }
+    return $cost
+}
+
    +
    • +

  • We want to find the solution that gives this minimum for various lengths +of the solution vector params:

    +
    +foreach n {100 1000 10000} {
+    break
+    puts "Problem size: $n"
+    puts [::simulation::annealing::findCombinatorialMinimum  -trials 300  -verbose 0  -number-params $n  -code {set result [cost $params]}]
+}
+
    +
    • +

  • As the vector grows, the computation time increases, but the procedure +will stop if some kind of equilibrium is reached. To achieve a useful +solution you may want to try different values of the trials parameter +for instance. Also ensure that the function to be minimized depends on +all or most parameters - see the source code for a counter example and +run that.

    • +
+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/montecarlo.html Index: embedded/www/tcllib/files/modules/simulation/montecarlo.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/simulation/montecarlo.html @@ -0,0 +1,295 @@ + + +simulation::montecarlo - Tcl Simulation Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

simulation::montecarlo(n) 0.1 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::montecarlo - Monte Carlo simulations

+
+ + +

Description

+

The technique of Monte Carlo simulations is basically simple:

+
    +

  • generate random values for one or more parameters.

    • +

  • evaluate the model of some system you are interested in and record the +interesting results for each realisation of these parameters.

    • +

  • after a suitable number of such trials, deduce an overall characteristic +of the model.

    • +
+

You can think of a model of a network of computers, an ecosystem of some +kind or in fact anything that can be quantitatively described and has +some stochastic element in it.

+

The package simulation::montecarlo offers a basic framework for +such a modelling technique:

+
+#
+# MC experiments:
+# Determine the mean and median of a set of points and compare them
+#
+::simulation::montecarlo::singleExperiment -init {
+    package require math::statistics
+    set prng [::simulation::random::prng_Normal 0.0 1.0]
+} -loop {
+    set numbers {}
+    for { set i 0 } { $i < [getOption samples] } { incr i } {
+        lappend numbers [$prng]
+    }
+    set mean   [::math::statistics::mean $numbers]
+    set median [::math::statistics::median $numbers] ;# ? Exists?
+    setTrialResult [list $mean $median]
+} -final {
+    set result [getTrialResults]
+    set means   {}
+    set medians {}
+    foreach r $result {
+        foreach {m M} $r break
+        lappend means   $m
+        lappend medians $M
+    }
+    puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]"
+} -trials 100 -samples 10 -verbose 1 -columns {Mean Median}
+
+

This example attemps to find out how well the median value and the mean +value of a random set of numbers correlate. Sometimes a median value is +a more robust characteristic than a mean value - especially if you have +a statistical distribution with "fat" tails.

+
+

PROCEDURES

+

The package defines the following auxiliary procedures:

+
+
::simulation::montecarlo::getOption keyword
+

Get the value of an option given as part of the singeExperiment command.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::montecarlo::hasOption keyword
+

Returns 1 if the option is available, 0 if not.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::montecarlo::setOption keyword value
+

Set the value of the given option.

+
+
string keyword
+

Given keyword (without leading minus)

+
string value
+

(New) value for the option

+
+
::simulation::montecarlo::setTrialResult values
+

Store the results of the trial for later analysis

+
+
list values
+

List of values to be stored

+
+
::simulation::montecarlo::setExpResult values
+

Set the results of the entire experiment (typically used in the final +phase).

+
+
list values
+

List of values to be stored

+
+
::simulation::montecarlo::getTrialResults
+

Get the results of all individual trials for analysis (typically used in +the final phase or after completion of the command).

+
::simulation::montecarlo::getExpResult
+

Get the results of the entire experiment (typically used in the final +phase or even after completion of the singleExperiment command).

+
::simulation::montecarlo::transposeData values
+

Interchange columns and rows of a list of lists and return the result.

+
+
list values
+

List of lists of values

+
+
+

There are two main procedures: integral2D and singleExperiment.

+
+
::simulation::montecarlo::integral2D ...
+

Integrate a function over a two-dimensional region using a Monte Carlo +approach.

+

Arguments PM

+
::simulation::montecarlo::singleExperiment args
+

Iterate code over a number of trials and store the results. The +iteration is gouverned by parameters given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
+

The singleExperiment command predefines the following +options:

+
    +

  • -init code: code to be run at start up

    • +

  • -loop body: body of code that defines the computation to +be run time and again. The code should use setTrialResult +to store the results of each trial (typically a list of numbers, +but the interpretation is up to the implementation). Note: Required keyword.

    • +

  • -final code: code to be run at the end

    • +

  • -trials n: number of trials in the experiment (required)

    • +

  • -reportfile file: opened file to send the output to (default: stdout)

    • +

  • -verbose: write the intermediate results (1) or not (0) (default: 0)

    • +

  • -analysis proc: either "none" (no automatic analysis), standard +(basic statistics of the trial results and a correlation matrix) or the +name of a procedure that will take care of the analysis.

    • +

  • -columns list: list of column names, useful for verbose output +and the analysis

    • +
+

Any other options can be used via the getOption procedure +in the body.

+
+

TIPS

+

The procedure singleExperiment works by constructing a +temporary procedure that does the actual work. It loops for the given +number of trials.

+

As it constructs a temporary procedure, local variables defined at the +start continue to exist in the loop.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/simulation_random.html Index: embedded/www/tcllib/files/modules/simulation/simulation_random.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/simulation/simulation_random.html @@ -0,0 +1,303 @@ + + +simulation::random - Tcl Simulation Tools + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

simulation::random(n) 0.1 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::random - Pseudo-random number generators

+
+ + +

Description

+

This package consists of commands to generate pseudo-random number +generators. These new commands deliver

+
    +

  • numbers that are distributed normally, uniformly, according to a +Pareto or Gumbel distribution and so on

    • +

  • coordinates of points uniformly spread inside a sphere or a rectangle

    • +
+

For example:

+
+    set p [::simulation::random::prng_Normal -1.0 10.0]
+
+

produces a new command (whose name is stored in the variable "p") that +generates normally distributed numbers with a mean of -1.0 and a +standard deviation of 10.0.

+
+

PROCEDURES

+

The package defines the following public procedures for discrete +distributions:

+
+
::simulation::random::prng_Bernoulli p
+

Create a command (PRNG) that generates numbers with a Bernoulli +distribution: the value is either 1 or 0, with a chance p to be 1

+
+
float p
+

Chance the outcome is 1

+
+
::simulation::random::prng_Discrete n
+

Create a command (PRNG) that generates numbers 0 to n-1 with equal +probability.

+
+
int n
+

Number of different values (ranging from 0 to n-1)

+
+
::simulation::random::prng_Poisson lambda
+

Create a command (PRNG) that generates numbers according to the Poisson +distribution.

+
+
float lambda
+

Mean number per time interval

+
+
+

The package defines the following public procedures for continuous distributions:

+
+
::simulation::random::prng_Uniform min max
+

Create a command (PRNG) that generates uniformly distributed numbers +between "min" and "max".

+
+
float min
+

Minimum number that will be generated

+
float max
+

Maximum number that will be generated

+
+
::simulation::random::prng_Exponential min mean
+

Create a command (PRNG) that generates exponentially distributed numbers +with a given minimum value and a given mean value.

+
+
float min
+

Minimum number that will be generated

+
float mean
+

Mean value for the numbers

+
+
::simulation::random::prng_Normal mean stdev
+

Create a command (PRNG) that generates normally distributed numbers +with a given mean value and a given standard deviation.

+
+
float mean
+

Mean value for the numbers

+
float stdev
+

Standard deviation

+
+
::simulation::random::prng_Pareto min steep
+

Create a command (PRNG) that generates numbers distributed according to +Pareto with a given minimum value and a given distribution steepness.

+
+
float min
+

Minimum number that will be generated

+
float steep
+

Steepness of the distribution

+
+
::simulation::random::prng_Gumbel min f
+

Create a command (PRNG) that generates numbers distributed according to +Gumbel with a given minimum value and a given scale factor. The +probability density function is:

+
+     P(v) = exp( -exp(f*(v-min)))
+
+
+
float min
+

Minimum number that will be generated

+
float f
+

Scale factor for the values

+
+
::simulation::random::prng_chiSquared df
+

Create a command (PRNG) that generates numbers distributed according to +the chi-squared distribution with df degrees of freedom. The mean is 0 +and the standard deviation is 1.

+
+
float df
+

Degrees of freedom

+
+
+

The package defines the following public procedures for random point sets:

+
+
::simulation::random::prng_Disk rad
+

Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a disk of given radius.

+
+
float rad
+

Radius of the disk

+
+
::simulation::random::prng_Sphere rad
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over the surface of a sphere of given radius.

+
+
float rad
+

Radius of the disk

+
+
::simulation::random::prng_Ball rad
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread within a ball of given radius.

+
+
float rad
+

Radius of the ball

+
+
::simulation::random::prng_Rectangle length width
+

Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a rectangle.

+
+
float length
+

Length of the rectangle (x-direction)

+
float width
+

Width of the rectangle (y-direction)

+
+
::simulation::random::prng_Block length width depth
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over a block

+
+
float length
+

Length of the block (x-direction)

+
float width
+

Width of the block (y-direction)

+
float depth
+

Depth of the block (z-direction)

+
+
+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/smtpd/smtpd.html Index: embedded/www/tcllib/files/modules/smtpd/smtpd.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/smtpd/smtpd.html @@ -0,0 +1,342 @@ + + +smtpd - Tcl SMTP Server Package + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

smtpd(n) 1.5 tcllib "Tcl SMTP Server Package"

+

Name

+

smtpd - Tcl SMTP server implementation

+
+ + +

Description

+

The smtpd package provides a simple Tcl-only server library +for the Simple Mail Transfer Protocol as described in +RFC 821 (http://www.rfc-editor.org/rfc/rfc821.txt) and +RFC 2821 (http://www.rfc-editor.org/rfc/rfc2821.txt). +By default the server will bind to the default network address and the +standard SMTP port (25).

+

This package was designed to permit testing of Mail User Agent code +from a developers workstation. It does not attempt to deliver mail to your mailbox. Instead users of this package are expected to +write a procedure that will be called when mail arrives. Once this +procedure returns, the server has nothing further to do with the mail.

+
+

SECURITY

+

On Unix platforms binding to the SMTP port requires root privileges. I +would not recommend running any script-based server as root unless +there is some method for dropping root privileges immediately after +the socket is bound. Under Windows platforms, it is not necessary to +have root or administrator privileges to bind low numbered +sockets. However, security on these platforms is weak anyway.

+

In short, this code should probably not be used as a permanently +running Mail Transfer Agent on an Internet connected server, even +though we are careful not to evaluate remote user input. There are +many other well tested and security audited programs that can be used +as mail servers for internet connected hosts.

+
+

COMMANDS

+
+
::smtpd::start ?myaddr? ?port?
+

Start the service listening on port or the default port 25. If +myaddr is given as a domain-style name or numerical +dotted-quad IP address then the server socket will be bound to that +network interface. By default the server is bound to all network +interfaces. For example:

+
+  set sock [::smtpd::start [info hostname] 0]
+
+

will bind to the hosts internet interface on the first available port.

+

At present the package only supports a single instance of a SMTP +server. This could be changed if required at the cost of making the +package a little more complicated to read. If there is a good reason +for running multiple SMTP services then it will only be necessary to +fix the options array and the ::smtpd::stopped variable +usage.

+

As the server code uses fileevent(n) handlers to process the +input on sockets you will need to run the event loop. This means +either you should be running from within wish(1) or you +should vwait(n) on the ::smtpd::stopped variable which is +set when the server is stopped.

+
::smtpd::stop
+

Halt the server and release the listening socket. If the server has +not been started then this command does nothing. +The ::smtpd::stopped variable is set for use with +vwait(n).

+

It should be noted that stopping the server does not disconnect any +currently active sessions as these are operating over an independent +channel. Only explicitly tracking and closing these sessions, or +exiting the server process will close down all the running +sessions. This is similar to the usual unix daemon practice where the +server performs a fork(2) and the client session continues on +the child process.

+
::smptd::configure ?option value? ?option value ...?
+

Set configuration options for the SMTP server. Most values are the +name of a callback procedure to be called at various points in the +SMTP protocol. See the CALLBACKS section for details of the +procedures.

+
+
-banner text
+

Text of a custom banner message. The default banner is "tcllib smtpd 1.5". +Note that changing the banner does not affect the bracketing text +in the full greeting, printing status 220, server-address, and timestamp.

+
-validate_host proc
+

Callback to authenticate new connections based on the ip-address of +the client.

+
-validate_sender proc
+

Callback to authenticate new connections based on the senders email +address.

+
-validate_recipient proc
+

Callback to validate and authorize a recipient email address

+
-deliverMIME proc
+

Callback used to deliver mail as a mime token created by the tcllib +mime package.

+
-deliver proc
+

Callback used to deliver email. This option has no effect if +the -deliverMIME option has been set.

+
+
::smtpd::cget ?option?
+

If no option is specified the command will return a list of all +options and their current values. If an option is specified it will +return the value of that option.

+
+
+

CALLBACKS

+
+
validate_host callback
+

This procedure is called with the clients ip address as soon as a +connection request has been accepted and before any protocol commands +are processed. If you wish to deny access to a specific host then an +error should be returned by this callback. For example:

+
+ proc validate_host {ipnum} {
+    if {[string match "192.168.1.*" $ipnum]} {
+       error "go away!"
+    }
+ }
+
+

If access is denied the client will receive a standard message that +includes the text of your error, such as:

+
+ 550 Access denied: I hate you.
+
+

As per the SMTP protocol, the connection is not closed but we wait for +the client to send a QUIT command. Any other commands cause a +503 Bad Sequence error.

+
validate_sender callback
+

The validate_sender callback is called with the senders mail address +during processing of a MAIL command to allow you to accept or reject +mail based upon the declared sender. To reject mail you should throw +an error. For example, to reject mail from user "denied":

+
+ proc validate_sender {address} {
+    eval array set addr [mime::parseaddress $address]
+    if {[string match "denied" $addr(local)]} {
+         error "mailbox $addr(local) denied"
+    }
+    return    
+ }
+
+

The content of any error message will not be passed back to the client.

+
validate_recipient callback
+

The validate_recipient callback is similar to the validate_sender +callback and permits you to verify a local mailbox and accept mail for +a local user address during RCPT command handling. To reject mail, +throw an error as above. The error message is ignored.

+
deliverMIME callback
+

] +The deliverMIME callback is called once a mail message has been +successfully passed to the server. A mime token is constructed from +the sender, recipients and data and the users procedure it called with +this single argument. When the call returns, the mime token is cleaned +up so if the user wishes to preserve the data she must make a copy.

+
+ proc deliverMIME {token} {
+     set sender [lindex [mime::getheader $token From] 0]
+     set recipients [lindex [mime::getheader $token To] 0]
+     set mail "From $sender [clock format [clock seconds]]"
+     append mail "\n" [mime::buildmessage $token]
+     puts $mail
+ }
+
+
+
deliver callback
+

The deliver callback is called once a mail message has been +successfully passed to the server and there is no -deliverMIME option +set. The procedure is called with the sender, a list of recipients and +the text of the mail as a list of lines. For example:

+
+ proc deliver {sender recipients data} {
+    set mail "From $sender  [clock format [clock seconds]]"
+    append mail "\n" [join $data "\n"]
+    puts "$mail"
+ }
+
+

Note that the DATA command will return an error if no sender or +recipient has yet been defined.

+
+
+

VARIABLES

+
+
::smtpd::stopped
+

This variable is set to true during the ::smtpd::stop +command to permit the use of the vwait(n) command.

+
+
+ +

LICENSE

+

This software is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file +"license.terms" for more details.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category smtpd of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/snit/snit.html Index: embedded/www/tcllib/files/modules/snit/snit.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/snit/snit.html @@ -0,0 +1,2088 @@ + + +snit - Snit's Not Incr Tcl, OO system + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

snit(n) 2.3.2 tcllib "Snit's Not Incr Tcl, OO system"

+

Name

+

snit - Snit's Not Incr Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit ?2.3.2?
    • +
+ +
+
+

Description

+

Snit is a pure Tcl object and megawidget system. It's +unique among Tcl object systems in that it's based not on inheritance +but on delegation. Object systems based on inheritance only allow you +to inherit from classes defined using the same system, which is +limiting. In Tcl, an object is +anything that acts like an object; it shouldn't matter how the object +was implemented. Snit is intended to help you build applications out of +the materials at hand; thus, Snit is designed to be able to +incorporate and build on any object, whether it's a hand-coded object, +a Tk widget, an Incr Tcl object, +a BWidget or almost anything else.

+

This man page is intended to be a reference only; see the accompanying +snitfaq for a gentler, more tutorial introduction to Snit +concepts.

+
+

SNIT VERSIONS

+

This man page covers both Snit 2.2 and Snit 1.3. The primary +difference between the two versions is simply that Snit 2.2 contains +speed optimizations based on new features of Tcl 8.5; Snit 1.3 +supports all of Tcl 8.3, 8.4 and Tcl 8.5. There are a few minor +inconsistencies; they are flagged in the body of the man page with the +label "Snit 1.x Incompatibility"; they are also discussed in the snitfaq.

+
+

REFERENCE

+

Type and Widget Definitions

+

Snit provides the following commands for defining new types:

+
+
snit::type name definition
+

Defines a new abstract data type called name. If name is +not a fully qualified command name, it is assumed to be a name in the +namespace in which the snit::type command was called (usually the +global namespace). It returns the fully qualified name of the new type.

+

The type name is then a command that is used to create objects of the +new type, along with other activities.

+

The snit::type definition block is a script that may +contain the following definitions:

+
+
typevariable name ?-array? ?value?
+

Defines a type variable with the specified name, and optionally +the specified value. Type variables are shared by all instances +of the type. If the -array option is included, then +value should be a dictionary; it will be +assigned to the variable using array set.

+
typemethod name arglist body
+

Defines a type method, a subcommand of the new type command, +with the specified name, argument list, and +body. The arglist is a normal Tcl argument list and may contain +default arguments and the args argument; however, it may not +contain the argument names type, self, selfns, or +win.

+

The variable type is automatically defined in the body to +the type's fully-qualified name. In addition, +type variables are automatically visible in the body +of every type method.

+

If the name consists of two or more tokens, Snit handles it specially:

+
    typemethod {a b} {arg} { puts "Got $arg" }
+
+

This statement implicitly defines a type method called a which +has a subcommand b. b is called like this:

+
    $type a b "Hello, world!"
+
+

a may have any number of subcommands. This makes it possible +to define a hierarchical command structure; see method, below, +for more examples.

+

Type methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type's type methods can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+

Snit 1.x Incompatibility: In Snit 1.x, the following +following two calls to this type method are equivalent:

+
    $type a b "Hello, world!"
+    $type {a b} "Hello, world!"
+
+

In Snit 2.2, the second form is invalid.

+
typeconstructor body
+

The type constructor's body is executed once when the +type is first defined; it is typically used to +initialize array-valued type variables and to add +entries to The Tk Option Database.

+

The variable type is automatically defined in the body, +and contains the type's fully-qualified name. In addition, +type variables are automatically visible in the body of the type +constructor.

+

A type may define at most one type constructor.

+

The type constructor can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type constructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
variable name ?-array? ?value?
+

Defines an instance variable, a private variable associated with each +instance of this type, and optionally its initial value. +If the -array option is included, then +value should be a dictionary; it will be +assigned to the variable using array set.

+
method name arglist body
+

Defines an instance method, a subcommand of each instance of this +type, with the specified name, argument list and body. +The arglist is a normal Tcl argument list and may contain +default arguments and the args argument.

+

The method is implicitly passed the following arguments as well: +type, which contains the fully-qualified type name; self, +which contains the current instance command name; selfns, which +contains the name of the instance's private namespace; and win, +which contains the original instance name. +Consequently, the arglist may not contain the argument names +type, self, selfns, or win.

+

An instance method defined in this way is said to be +locally defined.

+

Type and instance variables are +automatically visible in all instance methods. If the type has +locally defined options, the options array is also visible.

+

If the name consists of two or more tokens, Snit handles it specially:

+
    method {a b} {} { ... }
+
+

This statement implicitly defines a method called a which +has a subcommand b. b is called like this:

+
    $self a b "Hello, world!"
+
+

a may have any number of subcommands. This makes it possible +to define a hierarchical command structure:

+
% snit::type dog {
+    method {tail wag}   {} {return "Wag, wag"}
+    method {tail droop} {} {return "Droop, droop"}
+}
+::dog
+% dog spot
+::spot
+% spot tail wag
+Wag, wag
+% spot tail droop
+Droop, droop
+%
+
+

What we've done is implicitly defined a "tail" method with subcommands +"wag" and "droop". Consequently, it's an error to define "tail" +explicitly.

+

Methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type's methods can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+

Snit 1.x Incompatibility: In Snit 1.x, the following +following two calls to this method are equivalent:

+
    $self a b "Hello, world!"
+    $self {a b} "Hello, world!"
+
+

In Snit 2.2, the second form is invalid.

+
option namespec ?defaultValue?
+
+
option namespec ?options...?
+

Defines an option for instances of this type, and optionally gives it +an initial value. The initial value defaults to the empty string if +no defaultValue is specified.

+

An option defined in this way is said to be locally defined.

+

The namespec is a list defining the option's +name, resource name, and class name, e.g.:

+
    option {-font font Font} {Courier 12}
+
+

The option name must begin with a hyphen, and must not contain any +upper case letters. The resource name and class name are optional; if +not specified, the resource name defaults to the option name, minus +the hyphen, and the class name defaults to the resource name with the +first letter capitalized. Thus, the following statement is equivalent +to the previous example:

+
    option -font {Courier 12}
+
+

See The Tk Option Database for more information about +resource and class names.

+

Options are normally set and retrieved using the standard +instance methods configure and cget; within instance code +(method bodies, etc.), option values are available through the +options array:

+
    set myfont $options(-font)
+
+

If the type defines any option handlers (e.g., -configuremethod), +then it should probably use configure and cget to +access its options to avoid subtle errors.

+

The option statement may include the following options:

+
+
-default defvalue
+

Defines the option's default value; the option's default value +will be "" otherwise.

+
-readonly flag
+

The flag can be any Boolean value recognized by Tcl. +If flag is true, then the option is read-only--it can only +be set using configure or configurelist +at creation time, i.e., in the type's constructor.

+
-type type
+

Every locally-defined option may define its validation type, which may +be either the name of a validation type or a specification for a +validation subtype

+

For example, an option may declare that its value must be an integer +by specifying snit::integer as its validation type:

+
    option -number -type snit::integer
+
+

It may also declare that its value is an integer between 1 and 10 +by specifying a validation subtype:

+
    option -number -type {snit::integer -min 1 -max 10}
+
+

If a validation type or subtype is defined for an option, then +it will be used to validate the option's value whenever it is +changed by the object's configure or +configurelist methods. In addition, all such options +will have their values validated automatically immediately +after the constructor executes.

+

Snit defines a family of validation types and subtypes, and it's +quite simple to define new ones. See +Validation Types for the complete list, and +Defining Validation Types for an explanation of how +to define your own.

+
-cgetmethod methodName
+

Every locally-defined option may define a -cgetmethod; +it is called when the option's value is retrieved using the +cget method. Whatever the method's body returns will +be the return value of the call to cget.

+

The named method must take one argument, the option name. +For example, this code is equivalent to (though slower than) +Snit's default handling of cget:

+
    option -font -cgetmethod GetOption
+    method GetOption {option} {
+        return $options($option)
+    }
+
+

Note that it's possible for any number of options to share a +-cgetmethod.

+
-configuremethod methodName
+

Every locally-defined option may define a -configuremethod; +it is called when the option's value is set using the +configure or configurelist methods. It is the +named method's responsibility to save the option's value; in other +words, the value will not be saved to the options() array unless +the method saves it there.

+

The named method must take two arguments, the option name and +its new value. For example, this code is equivalent to +(though slower than) Snit's default handling of configure:

+
    option -font -configuremethod SetOption
+    method SetOption {option value} {
+        set options($option) $value
+    }
+
+

Note that it's possible for any number of options to share a +single -configuremethod.

+
-validatemethod methodName
+

Every locally-defined option may define a -validatemethod; +it is called when the option's value is set using the +configure or configurelist methods, just before +the -configuremethod (if any). It is the +named method's responsibility to validate the option's new value, +and to throw an error if the value is invalid.

+

The named method must take two arguments, the option name and +its new value. For example, this code verifies that +-flag's value is a valid Boolean value:

+
    option -font -validatemethod CheckBoolean
+    method CheckBoolean {option value} {
+        if {![string is boolean -strict $value]} {
+            error "option $option must have a boolean value."
+        }
+    }
+
+

Note that it's possible for any number of options to share a +single -validatemethod.

+
+
constructor arglist body
+

The constructor definition specifies a body of code to be +executed when a new instance is created. The arglist is a +normal Tcl argument list and may contain default arguments and +the args argument.

+

As with methods, the arguments type, self, selfns, +and win are defined implicitly, and all type and instance +variables are automatically visible in its body.

+

If the definition doesn't explicitly define the constructor, +Snit defines one implicitly. If the type declares at least one option +(whether locally or by delegation), the default constructor will +be defined as follows:

+
    constructor {args} {
+        $self configurelist $args
+    }
+
+

For standard Tk widget behavior, the argument list should be +the single name args, as shown.

+

If the definition defines neither a constructor nor +any options, the default constructor is defined as follows:

+
    constructor {} {}
+
+

As with methods, the constructor can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the constructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
destructor body
+

The destructor is used to code any actions that must take place when +an instance of the type is destroyed: typically, the destruction of +anything created in the constructor.

+

The destructor takes no explicit arguments; as with methods, the +arguments type, self, selfns, and win, are +defined implicitly, and all type and instance +variables are automatically visible in its body. +As with methods, the destructor can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the destructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
proc name args body
+

Defines a new Tcl procedure in the type's namespace.

+

The defined proc differs from a normal Tcl proc in that all type +variables are automatically visible. The proc can access +instance variables as well, provided that it is passed +selfns (with precisely that name) as one of its arguments.

+

Although they are not implicitly defined for procs, the argument names +type, self, and win should be avoided.

+

As with methods and typemethods, procs can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the proc can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
delegate method name to comp ?as target?
+

Delegates method name to component comp. That is, when +method name is called on an instance of this type, the method +and its arguments will be passed to the named component's command +instead. That is, the following statement

+
    delegate method wag to tail
+
+

is roughly equivalent to this explicitly defined method:

+
    method wag {args} {
+        uplevel $tail wag $args
+    }
+
+

As with methods, the name may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method.

+

The optional as clause allows you to specify the delegated +method name and possibly add some arguments:

+
    delegate method wagtail to tail as "wag briskly"
+
+

A method cannot be both locally defined and delegated.

+

Note: All forms of delegate method can delegate to +both instance components and type components.

+
delegate method name ?to comp? using pattern
+

In this form of the delegate statement, the using clause +is used to specify the precise form of the command to which method +name name is delegated. In this form, the to clause is +optional, since the chosen command might not involve any particular +component.

+

The value of the using clause is a list that may contain +any or all of the following substitution codes; these codes are +substituted with the described value to build the delegated command +prefix. Note that the following two statements are equivalent:

+
    delegate method wag to tail
+    delegate method wag to tail using "%c %m"
+
+

Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string.

+

Substitutions:

+
+
%%
+

This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c".

+
%c
+

This is replaced with the named component's command.

+
%m
+

This is replaced with the final token of the method name; if +the method name has one token, this is identical to %M.

+
%M
+

This is replaced by the method name; if the name consists +of multiple tokens, they are joined by space characters.

+
%j
+

This is replaced by the method name; if the name consists +of multiple tokens, they are joined by underscores ("_").

+
%t
+

This is replaced with the fully qualified type name.

+
%n
+

This is replaced with the name of the instance's private namespace.

+
%s
+

This is replaced with the name of the instance command.

+
%w
+

This is replaced with the original name of the instance command; for +Snit widgets and widget adaptors, it will be the Tk window name. +It remains constant, even if the instance command is renamed.

+
+
delegate method * ?to comp? ?using pattern? ?except exceptions?
+

The form delegate method * delegates all unknown method names to the +specified component. The except clause can be used to +specify a list of exceptions, i.e., method names that will not +be so delegated. The using clause is defined as given above. +In this form, the statement must contain the to clause, the +using clause, or both.

+

In fact, the "*" can be a list of two or more tokens whose last +element is "*", as in the following example:

+
    delegate method {tail *} to tail
+
+

This implicitly defines the method tail whose subcommands will +be delegated to the tail component.

+
delegate option namespec to comp
+
+
delegate option namespec to comp as target
+
+
delegate option * to comp
+
+
delegate option * to comp except exceptions
+

Defines a delegated option; the namespec is defined as for the +option statement. +When the configure, configurelist, or cget +instance method is used to set or retrieve the option's value, the +equivalent configure or cget command will be applied +to the component as though the option was defined with the following +-configuremethod and -cgetmethod:

+
    method ConfigureMethod {option value} {
+        $comp configure $option $value
+    }
+    method CgetMethod {option} {
+        return [$comp cget $option]
+    }
+
+

Note that delegated options never appear in the options array.

+

If the as clause is specified, then the target option +name is used in place of name.

+

The form delegate option * delegates all unknown options to the +specified component. The except clause can be used to +specify a list of exceptions, i.e., option names that will not +be so delegated.

+

Warning: options can only be delegated to a component if it supports +the configure and cget instance methods.

+

An option cannot be both locally defined and delegated. +TBD: Continue from here.

+
component comp ?-public method? ?-inherit flag?
+

Explicitly declares a component called comp, and automatically +defines the component's instance variable.

+

If the -public option is specified, then the option is made +public by defining a method whose subcommands are delegated +to the component e.g., specifying -public mycomp is +equivalent to the following:

+
    component mycomp
+    delegate method {mymethod *} to mycomp
+
+

If the -inherit option is specified, then flag must be a +Boolean value; if flag is true then all unknown methods and +options will be delegated to this component. The name -inherit +implies that instances of this new type inherit, in a sense, the +methods and options of the component. That is, -inherit yes is +equivalent to:

+
    component mycomp
+    delegate option * to mycomp
+    delegate method * to mycomp
+
+
+
delegate typemethod name to comp ?as target?
+

Delegates type method name to type component comp. That is, when +type method name is called on this type, the type method +and its arguments will be passed to the named type component's command +instead. That is, the following statement

+
    delegate typemethod lostdogs to pound
+
+

is roughly equivalent to this explicitly defined method:

+
    typemethod lostdogs {args} {
+        uplevel $pound lostdogs $args
+    }
+
+

As with type methods, the name may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method.

+

The optional as clause allows you to specify the delegated +method name and possibly add some arguments:

+
    delegate typemethod lostdogs to pound as "get lostdogs"
+
+

A type method cannot be both locally defined and delegated.

+
delegate typemethod name ?to comp? using pattern
+

In this form of the delegate statement, the using clause +is used to specify the precise form of the command to which type method +name name is delegated. In this form, the to clause is +optional, since the chosen command might not involve any particular +type component.

+

The value of the using clause is a list that may contain +any or all of the following substitution codes; these codes are +substituted with the described value to build the delegated command +prefix. Note that the following two statements are equivalent:

+
    delegate typemethod lostdogs to pound
+    delegate typemethod lostdogs to pound using "%c %m"
+
+

Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string.

+

Substitutions:

+
+
%%
+

This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c".

+
%c
+

This is replaced with the named type component's command.

+
%m
+

This is replaced with the final token of the type method name; if +the type method name has one token, this is identical to %M.

+
%M
+

This is replaced by the type method name; if the name consists +of multiple tokens, they are joined by space characters.

+
%j
+

This is replaced by the type method name; if the name consists +of multiple tokens, they are joined by underscores ("_").

+
%t
+

This is replaced with the fully qualified type name.

+
+
delegate typemethod * ?to comp? ?using pattern? ?except exceptions?
+

The form delegate typemethod * delegates all unknown type +method names to the +specified type component. The except clause can be used to +specify a list of exceptions, i.e., type method names that will not +be so delegated. The using clause is defined as given above. +In this form, the statement must contain the to clause, the +using clause, or both.

+

Note: By default, Snit interprets $type foo, where +foo is +not a defined type method, as equivalent to $type create foo, where +foo is the name of a new instance of the type. If you +use delegate typemethod *, then the create type +method must always be used explicitly.

+

The "*" can be a list of two or more tokens whose last +element is "*", as in the following example:

+
    delegate typemethod {tail *} to tail
+
+

This implicitly defines the type method tail whose subcommands will +be delegated to the tail type component.

+
typecomponent comp ?-public typemethod? ?-inherit flag?
+

Explicitly declares a type component called comp, and automatically +defines the component's type variable. A type component is an arbitrary +command to which type methods and instance methods can be delegated; +the command's name is stored in a type variable.

+

If the -public option is specified, then the type component is made +public by defining a typemethod whose subcommands are delegated to +the type component, e.g., specifying -public mytypemethod +is equivalent to the following:

+
    typecomponent mycomp
+    delegate typemethod {mytypemethod *} to mycomp
+
+

If the -inherit option is specified, then flag must be a +Boolean value; if flag is true then all unknown type methods +will be delegated to this type component. (See the note on "delegate +typemethod *", above.) The name -inherit +implies that this type inherits, in a sense, the behavior of +the type component. That is, -inherit yes is equivalent to:

+
    typecomponent mycomp
+    delegate typemethod * to mycomp
+
+
+
pragma ?options...?
+

The pragma statement provides control over how Snit generates a +type. It takes the following options; in each case, flag must +be a Boolean value recognized by Tcl, e.g., 0, 1, +yes, no, and so +on.

+

By setting the -hastypeinfo, -hastypedestroy, and +-hasinstances pragmas to false and defining appropriate +type methods, you can create an ensemble command without any extraneous +behavior.

+
+
-canreplace flag
+

If false (the default) Snit will not create an instance of a +snit::type that has the same name as an existing command; this +prevents subtle errors. Setting this pragma to true restores the +behavior of Snit V0.93 and earlier versions.

+
-hastypeinfo flag
+

If true (the default), the generated type will have a type method +called info that is used for type introspection; the info +type method is documented below. If false, it will not.

+
-hastypedestroy flag
+

If true (the default), the generated type will have a type method +called destroy that is used to destroy the type and all of its +instances. The destroy type method is documented below. If +false, it will not.

+
-hastypemethods flag
+

If true (the default), the generated type's type command will have +subcommands (type methods) as usual. If false, the type command +will serve only to create instances of the type; the first argument +is the instance name.

+

This pragma and -hasinstances cannot both be set false.

+
-hasinstances flag
+

If true (the default), the generated type will have a type method +called create that is used to create instances of the type, +along with a variety of instance-related features. If false, it will +not.

+

This pragma and -hastypemethods cannot both be set false.

+
-hasinfo flag
+

If true (the default), instances of the generated type will have +an instance method called info that is used for +instance introspection; the info +method is documented below. If false, it will not.

+
-simpledispatch flag
+

This pragma is intended to make simple, heavily-used abstract +data types (e.g., stacks and queues) more efficient.

+

If false (the default), instance methods are dispatched normally. If +true, a faster dispatching scheme is used instead. +The speed comes at a price; with -simpledispatch yes you +get the following limitations:

+
    +

  • Methods cannot be delegated.

    • +

  • uplevel and upvar do not work as expected: the +caller's scope is two levels up rather than one.

    • +

  • The option-handling methods +(cget, configure, and configurelist) are very +slightly slower.

    • +
+
+
expose comp
+
+
expose comp as method
+

Deprecated. To expose component comp publicly, use +component's -public option.

+
onconfigure name arglist body
+

Deprecated. Define option's -configuremethod +option instead.

+

As of version 0.95, the following definitions,

+
    option -myoption
+    onconfigure -myoption {value} {
+        # Code to save the option's value
+    }
+
+

are implemented as follows:

+
    option -myoption -configuremethod _configure-myoption
+    method _configure-myoption {_option value} {
+        # Code to save the option's value
+    }
+
+
+
oncget name body
+

Deprecated. Define option's -cgetmethod +option instead.

+

As of version 0.95, the following definitions,

+
    option -myoption
+    oncget -myoption {
+        # Code to return the option's value
+    }
+
+

are implemented as follows:

+
    option -myoption -cgetmethod _cget-myoption
+    method _cget-myoption {_option} {
+        # Code to return the option's value
+    }
+
+
+
+
snit::widget name definition
+

This command defines a Snit megawidget type with the specified +name. The definition is defined as for snit::type. + A snit::widget differs from a snit::type +in these ways:

+
    +

  • Every instance of a snit::widget has an automatically-created +component called hull, which is normally a Tk frame widget. +Other widgets created as part of the megawidget will be created within +this widget.

    +

    The hull component is initially created with the requested widget +name; then Snit does some magic, renaming the hull component and +installing its own instance command in its place. +The hull component's new name is saved in an instance variable called +hull.

    • +

  • The name of an instance must be valid Tk window name, and the parent +window must exist.

    • +
+

A snit::widget definition can include any of statements allowed +in a snit::type definition, and may also include the following:

+
+
widgetclass name
+

Sets the snit::widget's widget class to name, overriding +the default. See The Tk Option Database for more +information.

+
hulltype type
+

Determines the kind of widget used as the snit::widget's hull. +The type may be frame (the default), toplevel, +labelframe; the qualified equivalents of these, +tk::frame, tk::toplevel, and tk::labelframe; +or, if available, the equivalent Tile widgets: +ttk::frame, ttk::toplevel, and +ttk::labelframe. In practice, any widget that supports the +-class option can be used as a hull widget by +lappend'ing its name to the variable snit::hulltypes.

+
+
snit::widgetadaptor name definition
+

This command defines a Snit megawidget type with the specified name. +It differs from snit::widget in that the instance's hull +component is not created automatically, but is created in the +constructor and installed using the installhull command. Once +the hull is installed, its instance command is renamed and replaced as +with normal snit::widgets. The original command is again +accessible in the instance variable hull.

+

Note that in general it is not possible to change the +widget class of a snit::widgetadaptor's hull widget.

+

See The Tk Option Database for information on how +snit::widgetadaptors interact with the option database.

+
snit::typemethod type name arglist body
+

Defines a new type method (or redefines an existing type method) +for a previously existing type.

+
snit::method type name arglist body
+

Defines a new instance method (or redefines an existing instance +method) for a previously existing type. Note that delegated +instance methods can't be redefined.

+
snit::macro name arglist body
+

Defines a Snit macro with the specified name, arglist, and +body. Macros are used to define new type and widget +definition statements in terms of the statements defined in this man +page.

+

A macro is simply a Tcl proc that is defined in the slave interpreter +used to compile type and widget definitions. Thus, macros have +access to all of the type and widget definition statements. See +Macros and Meta-programming for more details.

+

The macro name cannot be the same as any standard Tcl command, +or any Snit type or widget definition statement, e.g., you can't +redefine the method or delegate statements, or the +standard set, list, or string commands.

+
snit::compile which type body
+

Snit defines a type, widget, or widgetadaptor by "compiling" the +definition into a Tcl script; this script is then evaluated in the +Tcl interpreter, which actually defines the new type.

+

This command exposes the "compiler". Given a definition body +for the named type, where which is type, +widget, or widgetadaptor, snit::compile returns a list +of two elements. The first element is the fully qualified type name; +the second element is the definition script.

+

snit::compile is useful when additional processing +must be done on the Snit-generated code--if it must be instrumented, +for example, or run through the TclDevKit compiler. In addition, the +returned script could be saved in a ".tcl" file and used to define the +type as part of an application or library, thus saving the compilation +overhead at application start-up. Note that the +same version of Snit must be used at run-time as at compile-time.

+
+
+

The Type Command

+

A type or widget definition creates a type command, which is used to +create instances of the type. The type command has this form:

+
+
$type typemethod args...
+

The typemethod can be any of the +Standard Type Methods (e.g., create), +or any type method defined in the type +definition. +The subsequent args depend on the specific typemethod +chosen.

+

The type command is most often used to create new instances of the +type; hence, the create method is assumed if the first +argument to the type command doesn't name a valid type method, unless +the type definition includes delegate typemethod * or the +-hasinstances pragma is set to false.

+

Furthermore, if the -hastypemethods pragma is false, then +Snit type commands can be called with no arguments at +all; in this case, the type command creates an instance with an +automatically generated name. In other words, provided that the +-hastypemethods pragma is false and the type +has instances, the following commands are equivalent:

+
snit::type dog { ... }
+set mydog [dog create %AUTO%]
+set mydog [dog %AUTO%]
+set mydog [dog]
+
+

This doesn't work for Snit widgets, for obvious reasons.

+

Snit 1.x Incompatibility: In Snit 1.x, the above behavior is +available whether -hastypemethods is true (the default) or false.

+
+
+

Standard Type Methods

+

In addition to any type methods in the type's definition, all type and +widget commands will usually have at least the following subcommands:

+
+
$type create name ?option value ...?
+

Creates a new instance of the type, giving it the specified name +and calling the type's constructor.

+

For snit::types, if name is not a fully-qualified command +name, it is assumed to be a name in the namespace in which the call to +snit::type appears. The method returns the fully-qualified +instance name.

+

For snit::widgets and snit::widgetadaptors, name +must be a valid widget name; the method returns the widget name.

+

So long as name does not conflict with any defined type method +name the create keyword may be omitted, unless +the type definition includes delegate typemethod * or the +-hasinstances pragma is set to false.

+

If the name includes the string %AUTO%, it will be +replaced with the string $type$counter where $type is +the type name and $counter is a counter that increments each +time %AUTO% is used for this type.

+

By default, any arguments following the name will be a list of +option names and their values; however, a type's +constructor can specify a different argument list.

+

As of Snit V0.95, create will throw an error if the name +is the same as any existing command--note that this was always true +for snit::widgets and snit::widgetadaptors. You can +restore the previous behavior using the -canreplace pragma.

+
$type info typevars ?pattern?
+

Returns a list of the type's type variables (excluding Snit internal +variables); all variable names are fully-qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$type info typemethods ?pattern?
+

Returns a list of the names of the type's type methods. +If the type has hierarchical +type methods, whether locally-defined or delegated, only the first +word of each will be included in the list.

+

If the type +definition includes delegate typemethod *, the list will +include only the names of those implicitly delegated type methods +that have been called at least once and are still in the type method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$type info args method
+

Returns a list containing the names of the arguments to the type's +method, in order. This method cannot be applied to delegated +type methods.

+
$type info body method
+

Returns the body of typemethod method. This method cannot be +applied to delegated type methods.

+
$type info default method aname varname
+

Returns a boolean value indicating whether the argument aname of +the type's method has a default value (true) or not +(false). If the argument has a default its value is placed into +the variable varname.

+
$type info instances ?pattern?
+

Returns a list of the type's instances. For snit::types, it +will be a list of fully-qualified instance names; +for snit::widgets, it will be a list of Tk widget names.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$type destroy
+

Destroys the type's instances, the type's namespace, and the type +command itself.

+
+
+

The Instance Command

+

A Snit type or widget's create type method creates objects of +the type; each object has a unique name that is also a Tcl command. +This command is used to access the object's methods and data, and has +this form:

+
+
$object method args...
+

The method can be any of the +Standard Instance Methods, or any instance method +defined in the type definition. +The subsequent args depend on the specific method chosen.

+
+
+

Standard Instance Methods

+

In addition to any delegated or locally-defined instance methods in +the type's definition, all Snit objects will have at least the +following subcommands:

+
+
$object configure ?option? ?value? ...
+

Assigns new values to one or more options. If called with one +argument, an option name, returns a list describing the option, +as Tk widgets do; if called with no arguments, returns a list of lists +describing all options, as Tk widgets do.

+

Warning: This information will be available for delegated options only +if the component to which they are delegated has a configure +method that returns this same kind of information.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object configurelist optionlist
+

Like configure, but takes one argument, a list of options and +their values. It's mostly useful in the type constructor, but can be +used anywhere.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object cget option
+

Returns the option's value.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object destroy
+

Destroys the object, calling the destructor and freeing all +related memory.

+

Note: +The destroy method isn't defined for snit::widget or +snit::widgetadaptor objects; instances of these are destroyed by +calling Tk's destroy command, just as normal +widgets are.

+
$object info type
+

Returns the instance's type.

+
$object info vars ?pattern?
+

Returns a list of the object's instance variables (excluding Snit +internal variables). The names are fully qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$object info typevars ?pattern?
+

Returns a list of the object's type's type variables (excluding Snit +internal variables). The names are fully qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$object info typemethods ?pattern?
+

Returns a list of the names of the type's type methods. +If the type has hierarchical +type methods, whether locally-defined or delegated, only the first +word of each will be included in the list.

+

If the type +definition includes delegate typemethod *, the list will +include only the names of those implicitly delegated type methods +that have been called at least once and are still in the type method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$object info options ?pattern?
+

Returns a list of the object's option names. This always includes +local options and explicitly delegated options. If unknown options +are delegated as well, and if the component to which they are +delegated responds to $object configure like Tk widgets do, +then the result will include all possible unknown options that can +be delegated to the component.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Note that the return value might be different for different instances +of the same type, if component object types can vary from one instance +to another.

+
$object info methods ?pattern?
+

Returns a list of the names of the instance's methods. +If the type has hierarchical methods, whether locally-defined or +delegated, only the first word of each will be included in the list.

+

If the type +definition includes delegate method *, the list will +include only the names of those implicitly delegated methods that have +been called at least once and are still in the method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$object info args method
+

Returns a list containing the names of the arguments to the instance's +method, in order. This method cannot be applied to delegated methods.

+
$object info body method
+

Returns the body of the instance's method method. This method +cannot be applied to delegated methods.

+
$object info default method aname varname
+

Returns a boolean value indicating whether the argument aname of +the instance's method has a default value (true) or not +(false). If the argument has a default its value is placed into +the variable varname.

+
+
+

Commands for use in Object Code

+

Snit defines the following commands for use in your object code: +that is, for use in type methods, instance methods, constructors, +destructors, onconfigure handlers, oncget handlers, and procs. +They do not reside in the ::snit:: namespace; instead, they are +created with the type, and can be used without qualification.

+
+
mymethod name ?args...?
+

The mymethod command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke method name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's +dosomething method to be called when the $button is pressed:

+
    $button configure -command [list $self dosomething myargument]
+       
+    $button configure -command [mymethod dosomething myargument]
+
+

The chief distinction between the two is that the latter form will not +break if the object's command is renamed.

+
mytypemethod name ?args...?
+

The mytypemethod command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke type method name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's dosomething type method +to be called when $button is pressed:

+
    $button configure -command [list $type dosomething myargument]
+       
+    $button configure -command [mytypemethod dosomething myargument]
+
+

Type commands cannot be renamed, so in practice there's little +difference between the two forms. mytypemethod is provided for +parallelism with mymethod.

+
myproc name ?args...?
+

The myproc command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke the type proc name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's dosomething proc +to be called when $button is pressed:

+
    $button configure -command [list ${type}::dosomething myargument]
+       
+    $button configure -command [myproc dosomething myargument]
+
+
+
myvar name
+

Given an instance variable name, returns the fully qualified name. +Use this if you're passing the variable to some other object, e.g., as +a -textvariable to a Tk label widget.

+
mytypevar name
+

Given an type variable name, returns the fully qualified name. Use +this if you're passing the variable to some other object, e.g., as a +-textvariable to a Tk label widget.

+
from argvName option ?defvalue?
+

The from command plucks an option value from a list of options +and their values, such as is passed into a type's constructor. +argvName must be the name of a variable containing such a list; +option is the name of the specific option.

+

from looks for option in the option list. If it is found, +it and its value are removed from the list, and the value is returned. +If option doesn't appear in the list, then the defvalue is +returned. +If the option is locally-defined option, and defvalue is +not specified, then the option's default value as specified in the +type definition will be returned instead.

+
install compName using objType objName args...
+

Creates a new object of type objType called objName +and installs it as component compName, +as described in Components and Delegation. Any additional +args... are passed along with the name to the objType +command. +If this is a snit::type, then the following two commands are +equivalent:

+
    install myComp using myObjType $self.myComp args...
+    set myComp [myObjType $self.myComp args...]
+
+

Note that whichever method is used, compName must still be +declared in the type definition using component, or must be +referenced in at least one delegate statement.

+

If this is a snit::widget or snit::widgetadaptor, and if +options have been delegated to component compName, then those +options will receive default values from the Tk option database. Note +that it doesn't matter whether the component to be installed is a +widget or not. See The Tk Option Database for more +information.

+

install cannot be used to install type components; just assign +the type component's command name to the type component's variable +instead.

+
installhull using widgetType args...
+
+
installhull name
+

The constructor of a snit::widgetadaptor must create a widget to +be the object's hull component; the widget is installed as the hull +component using this command. Note that the installed widget's name +must be $win. +This command has two forms.

+

The first form specifies the widgetType and the args... +(that is, the hardcoded option list) to use in creating the hull. +Given this form, installhull creates the hull widget, and +initializes any options delegated to the hull from the Tk option +database.

+

In the second form, the hull widget has already been created; note +that its name must be "$win". In this case, the Tk option database is +not queried for any options delegated to the hull. +The longer form is preferred; however, the shorter form allows the +programmer to adapt a widget created elsewhere, which is sometimes +useful. For example, it can be used to adapt a "page" widget created +by a BWidgets tabbed notebook or pages manager widget.

+

See The Tk Option Database for more information +about snit::widgetadaptors and the option database.

+
variable name
+

Normally, instance variables are defined in the type definition along +with the options, methods, and so forth; such instance variables are +automatically visible in all instance code (e.g., method bodies). However, +instance code can use the variable command to declare instance variables +that don't appear in the type definition, and also to bring variables +from other namespaces into scope in the usual way.

+

It's generally clearest to define all instance variables in the type +definition, and omit declaring them in methods and so forth.

+

Note that this is an instance-specific version of the standard Tcl +::variable command.

+
typevariable name
+

Normally, type variables are defined in the type definition, along +with the instance variables; such type variables are automatically +visible in all of the type's code. However, type methods, instance +methods and so forth can use typevariable to declare type +variables that don't appear in the type definition.

+

It's generally clearest to declare all type variables in the type +definition, and omit declaring them in methods, type methods, etc.

+
varname name
+

Deprecated. Use myvar instead.

+

Given an instance variable name, returns the fully qualified name. +Use this if you're passing the variable to some other object, e.g., as +a -textvariable to a Tk label widget.

+
typevarname name
+

Deprecated. Use mytypevar instead.

+

Given a type variable name, returns the fully qualified name. Use +this if you're passing the type variable to some other object, e.g., as a +-textvariable to a Tk label widget.

+
codename name
+

Deprecated. Use myproc instead. +Given the name of a proc (but not a type or instance method), returns +the fully-qualified command name, suitable for passing as a callback.

+
+
+

Components and Delegation

+

When an object includes other objects, as when a toolbar contains +buttons or a GUI object contains an object that references a database, +the included object is called a component. The standard way to handle +component objects owned by a Snit object is to declare them using +component, which creates a component instance variable. +In the following example, a dog object has a +tail object:

+
    snit::type dog {
+        component mytail
+    
+        constructor {args} {
+            set mytail [tail %AUTO% -partof $self]
+            $self configurelist $args
+        }
+    
+        method wag {} {
+            $mytail wag
+        }
+    }
+    
+    snit::type tail {
+        option -length 5
+        option -partof
+        method wag {} { return "Wag, wag, wag."}
+    }
+
+

Because the tail object's name is stored in an instance +variable, it's easily accessible in any method.

+

The install command provides an alternate way +to create and install the component:

+
    snit::type dog {
+        component mytail
+        constructor {args} {
+            install mytail using tail %AUTO% -partof $self
+            $self configurelist $args
+        }
+        method wag {} {
+            $mytail wag
+        }
+    }
+
+

For snit::types, the two methods are equivalent; for +snit::widgets and snit::widgetadaptors, the install +command properly initializes the widget's options by querying +The Tk Option Database.

+

In the above examples, the dog object's wag method +simply calls the tail component's wag method. In OO +jargon, this is called delegation. Snit provides an easier way to do +this:

+
    snit::type dog {
+        delegate method wag to mytail
+    
+        constructor {args} {
+            install mytail using tail %AUTO% -partof $self
+            $self configurelist $args
+        }
+    }
+
+

The delegate statement in the type definition implicitly defines +the instance variable mytail to hold the component's name +(though it's good form to use component to declare it explicitly); it +also defines the dog object's wag method, delegating it +to the mytail component.

+

If desired, all otherwise unknown methods can be delegated to a +specific component:

+
+    snit::type dog {
+	delegate method * to mytail
+	constructor {args} {
+	    set mytail [tail %AUTO% -partof $self]
+	    $self configurelist $args
+	}
+	method bark { return "Bark, bark, bark!" }
+    }
+
+

In this case, a dog object will handle its own bark +method; but wag will be passed along to mytail. Any +other method, being recognized by neither dog nor tail, +will simply raise an error.

+

Option delegation is similar to method delegation, except for the +interactions with the Tk option database; this is described in +The Tk Option Database.

+
+

Type Components and Delegation

+

The relationship between type components and instance components is +identical to that between type variables and instance variables, and +that between type methods and instance methods. Just as an instance +component is an instance variable that holds the name of a command, so +a type component is a type variable that holds the name of a command. +In essence, a type component is a component that's shared by every +instance of the type.

+

Just as delegate method can be used to delegate methods to +instance components, as described in +Components and Delegation, so delegate typemethod +can be used to delegate type methods to type components.

+

Note also that as of Snit 0.95 delegate method can delegate +methods to both instance components and type components.

+
+

The Tk Option Database

+

This section describes how Snit interacts with the Tk option database, +and assumes the reader has a working knowledge of the option database +and its uses. The book Practical Programming in Tcl and Tk +by Welch et al has a good introduction to the option database, as does +Effective Tcl/Tk Programming.

+

Snit is implemented so that most of the time it will simply do the +right thing with respect to the option database, provided that the +widget developer does the right thing by Snit. The body of this +section goes into great deal about what Snit requires. The following +is a brief statement of the requirements, for reference.

+
    +

  • If the snit::widget's default widget class is not what is desired, set it +explicitly using widgetclass in the widget definition.

    • +

  • When defining or delegating options, specify the resource and class +names explicitly when if the defaults aren't what you want.

    • +

  • Use installhull using to install the hull for +snit::widgetadaptors.

    • +

  • Use install to install all other components.

    • +
+

The interaction of Tk widgets with the option database is a complex +thing; the interaction of Snit with the option database is even more +so, and repays attention to detail.

+

Setting the widget class: Every Tk widget has a widget class. +For Tk widgets, the widget class name is the just the widget type name +with an initial capital letter, e.g., the widget class for +button widgets is "Button".

+

Similarly, the widget class of a snit::widget defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of

+
    snit::widget ::mylibrary::scrolledText { ... }
+

is "ScrolledText". The widget class can also be set explicitly using +the widgetclass statement within the snit::widget +definition.

+

Any widget can be used as the hulltype provided that it supports +the -class option for changing its widget class name. See +the discussion of the hulltype command, above. The user may pass +-class to the widget at instantion.

+

The widget class of a snit::widgetadaptor is just the widget +class of its hull widget; this cannot be changed unless the hull +widget supports -class, in which case it will +usually make more sense to use snit::widget rather than +snit::widgetadaptor.

+

Setting option resource names and classes: In Tk, every +option has three names: the option name, the resource name, and the +class name. The option name begins with a hyphen and is all lowercase; +it's used when creating widgets, and with the configure and +cget commands.

+

The resource and class names are used to initialize option default +values by querying the Tk option database. The resource name is +usually just the option name minus the hyphen, but may contain +uppercase letters at word boundaries; the class name is usually just +the resource name with an initial capital, but not always. For +example, here are the option, resource, and class names for several +text widget options:

+
    -background         background         Background 
+    -borderwidth        borderWidth        BorderWidth 
+    -insertborderwidth  insertBorderWidth  BorderWidth 
+    -padx               padX               Pad 
+
+

As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always.

+

Snit options also have a resource name and a class name. By default, +these names follow the rule given above: the resource name is the +option name without the hyphen, and the class name is the resource +name with an initial capital. This is true for both locally-defined +options and explicitly delegated options:

+
    snit::widget mywidget {
+        option -background
+        delegate option -borderwidth to hull
+        delegate option * to text
+	# ...
+    }
+
+

In this case, the widget class name is "Mywidget". The widget has the +following options: -background, which is locally defined, and +-borderwidth, which is explicitly delegated; all other widgets are +delegated to a component called "text", which is probably a Tk +text widget. If so, mywidget has all the same options as +a text widget. The option, resource, and class names are as +follows:

+
    -background  background  Background
+    -borderwidth borderwidth Borderwidth
+    -padx        padX        Pad
+
+

Note that the locally defined option, -background, happens to have +the same three names as the standard Tk -background option; and +-pad, which is delegated implicitly to the text +component, has the +same three names for mywidget as it does for the text +widget. -borderwidth, on the other hand, has different resource and +class names than usual, because the internal word "width" isn't +capitalized. For consistency, it should be; this is done as follows:

+
    snit::widget mywidget {
+	option -background
+	delegate option {-borderwidth borderWidth} to hull
+	delegate option * to text
+	# ...
+    }
+
+

The class name will default to "BorderWidth", as expected.

+

Suppose, however, that mywidget also delegated +-padx and +-pady to the hull. In this case, both the resource name and the +class name must be specified explicitly:

+
    snit::widget mywidget {
+	option -background
+	delegate option {-borderwidth borderWidth} to hull
+	delegate option {-padx padX Pad} to hull
+	delegate option {-pady padY Pad} to hull
+	delegate option * to text
+	# ...
+    }
+
+

Querying the option database: If you set your widgetclass and +option names as described above, Snit will query the option database +when each instance is created, and will generally do the right thing +when it comes to querying the option database. The remainder of this +section goes into the gory details.

+

Initializing locally defined options: +When an instance of a snit::widget is created, its locally defined +options are initialized as follows: each option's resource and class +names are used to query the Tk option database. If the result is +non-empty, it is used as the option's default; otherwise, the default +hardcoded in the type definition is used. In either case, the default +can be overridden by the caller. For example,

+
    option add *Mywidget.texture pebbled
+    snit::widget mywidget {
+	option -texture smooth
+	# ...
+    }
+    mywidget .mywidget -texture greasy
+
+

Here, -texture would normally default to "smooth", but because of +the entry added to the option database it defaults to "pebbled". +However, the caller has explicitly overridden the default, and so the +new widget will be "greasy".

+

Initializing options delegated to the hull: +A snit::widget's hull is a widget, and given that its class has +been set it is expected to query the option database for itself. The +only exception concerns options that are delegated to it with a +different name. Consider the following code:

+
    option add *Mywidget.borderWidth 5
+    option add *Mywidget.relief sunken
+    option add *Mywidget.hullbackground red
+    option add *Mywidget.background green
+    snit::widget mywidget {
+	delegate option -borderwidth to hull
+	delegate option -hullbackground to hull as -background
+	delegate option * to hull
+	# ...
+    }
+    mywidget .mywidget
+    set A [.mywidget cget -relief]
+    set B [.mywidget cget -hullbackground]
+    set C [.mywidget cget -background]
+    set D [.mywidget cget -borderwidth]
+
+

The question is, what are the values of variables A, B, C and D?

+

The value of A is "sunken". The hull is a Tk frame that has been +given the widget class "Mywidget"; it will automatically query the +option database and pick up this value. Since the -relief +option is implicitly delegated to the hull, Snit takes no action.

+

The value of B is "red". The hull will automatically pick up the +value "green" for its -background option, just as it picked up the +-relief value. However, Snit knows that +-hullbackground is mapped to +the hull's -background option; hence, it queries the option database +for -hullbackground and gets "red" and updates the hull +accordingly.

+

The value of C is also "red", because -background is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +-hullbackground. Note that this case is unusual; in practice, +-background would probably be explicitly delegated to some other +component.

+

The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for -borderwidth +defaults to "borderwidth", whereas the option database entry is +"borderWidth". As with -relief, the hull picks up its +own -borderwidth option before Snit does anything. Because the +option is delegated under its own name, Snit assumes that the correct +thing has happened, and doesn't worry about it any further.

+

For snit::widgetadaptors, the case is somewhat altered. Widget +adaptors retain the widget class of their hull, and the hull is not +created automatically by Snit. Instead, the snit::widgetadaptor +must call installhull in its constructor. The normal way to do +this is as follows:

+
    snit::widgetadaptor mywidget {
+	# ...
+	constructor {args} {
+	    # ...
+	    installhull using text -foreground white
+	    #
+	}
+	#...
+    }
+
+

In this case, the installhull command will create the hull using +a command like this:

+
    set hull [text $win -foreground white]
+
+

The hull is a text widget, so its widget class is "Text". Just +as with snit::widget hulls, Snit assumes that it will pick up +all of its normal option values automatically; options delegated from +a different name are initialized from the option database in the same +way.

+

Initializing options delegated to other components: +Non-hull components are matched against the option database in two +ways. First, a component widget remains a widget still, and therefore +is initialized from the option database in the usual way. +Second, the option database is queried for all options delegated to +the component, and the component is initialized accordingly--provided +that the install command is used to create it.

+

Before option database support was added to Snit, the usual way to +create a component was to simply create it in the constructor and +assign its command name to the component variable:

+
    snit::widget mywidget {
+	delegate option -background to myComp
+	constructor {args} {
+	    set myComp [text $win.text -foreground black]
+	}
+    }
+
+

The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used:

+
    snit::widget mywidget {
+	delegate option -background to myComp
+	constructor {args} {
+	    install myComp using text $win.text -foreground black
+	}
+    }
+
+

The install command does the following:

+
    +

  • Builds a list of the options explicitly included in the install +command -- in this case, -foreground.

    • +

  • Queries the option database for all options delegated explicitly to +the named component.

    • +

  • Creates the component using the specified command, after inserting +into it a list of options and values read from the option database. +Thus, the explicitly included options (-foreground) will override +anything read from the option database.

    • +

  • If the widget definition implicitly delegated options to the component +using delegate option *, then Snit calls the newly created +component's configure method to receive a list of all of the +component's options. From this Snit builds a list of options +implicitly delegated to the component that were not explicitly +included in the install command. For all such options, Snit +queries the option database and configures the component accordingly.

    • +
+

Non-widget components: The option database is never queried +for snit::types, since it can only be queried given a Tk widget +name. +However, snit::widgets can have non-widget components. And if +options are delegated to those components, and if the install +command is used to install those components, then they will be +initialized from the option database just as widget components are.

+
+

Macros and Meta-programming

+

The snit::macro command enables a certain amount of +meta-programming with Snit classes. For example, suppose you like to +define properties: instance variables that have set/get methods. Your +code might look like this:

+
    snit::type dog {
+        variable mood happy
+        method getmood {} {
+            return $mood
+        }
+        method setmood {newmood} {
+            set mood $newmood
+        }
+    }
+
+

That's nine lines of text per property. Or, you could define the +following snit::macro:

+
    snit::macro property {name initValue} {
+        variable $name $initValue
+        method get$name {} "return $name"
+        method set$name {value} "set $name \$value"
+    }
+
+

Note that a snit::macro is just a normal Tcl proc defined in +the slave interpreter used to compile type and widget definitions; as +a result, it has access to all the commands used to define types and +widgets.

+

Given this new macro, you can define a property in one line of code:

+
    snit::type dog {
+        property mood happy
+    }
+
+

Within a macro, the commands variable and proc refer to +the Snit type-definition commands, not the standard Tcl commands. To +get the standard Tcl commands, use _variable and _proc.

+

Because a single slave interpreter is used for compiling all Snit +types and widgets in the application, there's the possibility of macro +name collisions. If you're writing a reuseable package using Snit, +and you use some snit::macros, define them in your package +namespace:

+
    snit::macro mypkg::property {name initValue} { ... }
+    snit::type dog {
+        mypkg::property mood happy
+    }
+
+

This leaves the global namespace open for application authors.

+
+

Validation Types

+

A validation type is an object that can be used to validate +Tcl values of a particular kind. For example, +snit::integer is used to validate that a Tcl value is +an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
    snit::integer validate 5     ;# Does nothing
+    snit::integer validate 5.0   ;# Throws an error (not an integer!)
+
+

The validate method will always return the validated value on success, +and throw the -errorcode INVALID on error.

+

Snit defines a family of validation types, all of which are +implemented as snit::type's. They can be used as is; +in addition, their instances serve as parameterized +subtypes. For example, a probability is a number between 0.0 and 1.0 +inclusive:

+
    snit::double probability -min 0.0 -max 1.0
+
+

The example above creates an instance of snit::double--a +validation subtype--called +probability, which can be used to validate probability values:

+
    probability validate 0.5   ;# Does nothing
+    probability validate 7.9   ;# Throws an error
+
+

Validation subtypes can be defined explicitly, as in the above +example; when a locally-defined option's -type is specified, +they may also be created on the fly:

+
    snit::enum ::dog::breed -values {mutt retriever sheepdog}
+    snit::type dog {
+        # Define subtypes on the fly...
+        option -breed -type {
+            snit::enum -values {mutt retriever sheepdog}
+        }
+        # Or use predefined subtypes...
+        option -breed -type ::dog::breed 
+    }
+
+

Any object that has a validate method with the semantics +described above can be used as a validation type; see +Defining Validation Types for information on how to define +new ones.

+

Snit defines the following validation types:

+
+
snit::boolean validate ?value?
+
+
snit::boolean name
+

Validates Tcl boolean values: 1, 0, on, off, +yes, no, true, false. +It's possible to define subtypes--that is, instances--of +snit::boolean, but as it has no options there's no reason to do +so.

+
snit::double validate ?value?
+
+
snit::double name ?option value...?
+

Validates floating-point values. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a floating-point minimum bound; a value is invalid if it is strictly +less than min.

+
-max max
+

Specifies a floating-point maximum bound; a value is invalid if it is strictly +greater than max.

+
+
snit::enum validate ?value?
+
+
snit::enum name ?option value...?
+

Validates that a value comes from an enumerated list. The base +type is of little use by itself, as only subtypes actually have +an enumerated list to validate against. Subtypes may be created +with the following options:

+
+
-values list
+

Specifies a list of valid values. A value is valid if and only if +it's included in the list.

+
+
snit::fpixels validate ?value?
+
+
snit::fpixels name ?option value...?
+

Tk programs only. Validates screen distances, in any of the +forms accepted by winfo fpixels. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a minimum bound; a value is invalid if it is strictly +less than min. The bound may be expressed in any of the +forms accepted by winfo fpixels.

+
-max max
+

Specifies a maximum bound; a value is invalid if it is strictly +greater than max. The bound may be expressed in any of the +forms accepted by winfo fpixels.

+
+
snit::integer validate ?value?
+
+
snit::integer name ?option value...?
+

Validates integer values. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies an integer minimum bound; a value is invalid if it is strictly +less than min.

+
-max max
+

Specifies an integer maximum bound; a value is invalid if it is strictly +greater than max.

+
+
snit::listtype validate ?value?
+
+
snit::listtype name ?option value...?
+

Validates Tcl lists. Subtypes may be created with the +following options:

+
+
-minlen min
+

Specifies a minimum list length; the value is invalid if it has +fewer than min elements. Defaults to 0.

+
-maxlen max
+

Specifies a maximum list length; the value is invalid if it +more than max elements.

+
-type type
+

Specifies the type of the list elements; type must be +the name of a validation type or subtype. In the +following example, the value of -numbers must be a list +of integers.

+
    option -numbers -type {snit::listtype -type snit::integer}
+
+

Note that this option doesn't support defining new validation subtypes +on the fly; that is, the following code will not work (yet, anyway):

+
    option -numbers -type {
+        snit::listtype -type {snit::integer -min 5}
+    }
+
+

Instead, define the subtype explicitly:

+
    snit::integer gt4 -min 5
+    snit::type mytype {
+        option -numbers -type {snit::listtype -type gt4}
+    }
+
+
+
+
snit::pixels validate ?value?
+
+
snit::pixels name ?option value...?
+

Tk programs only. Validates screen distances, in any of the +forms accepted by winfo pixels. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a minimum bound; a value is invalid if it is strictly +less than min. The bound may be expressed in any of the +forms accepted by winfo pixels.

+
-max max
+

Specifies a maximum bound; a value is invalid if it is strictly +greater than max. The bound may be expressed in any of the +forms accepted by winfo pixels.

+
+
snit::stringtype validate ?value?
+
+
snit::stringtype name ?option value...?
+

Validates Tcl strings. The base type is of little use by itself, +since very Tcl value is also a valid string. Subtypes may be created with the +following options:

+
+
-minlen min
+

Specifies a minimum string length; the value is invalid if it has +fewer than min characters. Defaults to 0.

+
-maxlen max
+

Specifies a maximum string length; the value is invalid if it has +more than max characters.

+
-glob pattern
+

Specifies a string match pattern; the value is invalid +if it doesn't match the pattern.

+
-regexp regexp
+

Specifies a regular expression; the value is invalid if it doesn't +match the regular expression.

+
-nocase flag
+

By default, both -glob and -regexp matches are +case-sensitive. If -nocase is set to true, then both +-glob and -regexp matches are case-insensitive.

+
+
snit::window validate ?value?
+
+
snit::window name
+

Tk programs only. Validates Tk window names. The value must +cause winfo exists to return true; otherwise, the value is +invalid. It's possible to define subtypes--that is, instances--of +snit::window, but as it has no options at present there's no +reason to do so.

+
+
+

Defining Validation Types

+

There are three ways to define a new validation type: as a subtype of +one of Snit's validation types, as a validation type command, and as +a full-fledged validation type similar to those provided by Snit. +Defining subtypes of Snit's validation types is described above, +under Validation Types.

+

The next simplest way to create a new validation type is as a +validation type command. A validation type is simply an +object that has a validate method; the validate +method must take one argument, a value, return the value if it is +valid, and throw an error with -errorcode INVALID if the +value is invalid. This can be done with a simple proc. For +example, the snit::boolean validate type could have been +implemented like this:

+
    proc ::snit::boolean {"validate" value} {
+        if {![string is boolean -strict $value]} {
+            return -code error -errorcode INVALID \ 
+                "invalid boolean \"$value\", should be one of: 1, 0, ..."
+        }
+        return $value
+    }
+
+

A validation type defined in this way cannot be subtyped, of course; +but for many applications this will be sufficient.

+

Finally, one can define a full-fledged, subtype-able validation type +as a snit::type. Here's a skeleton to get you started:

+
    snit::type myinteger {
+        # First, define any options you'd like to use to define
+        # subtypes.  Give them defaults such that they won't take
+        # effect if they aren't used, and marked them "read-only".
+        # After all, you shouldn't be changing their values after
+        # a subtype is defined.
+        #
+        # For example:
+        option -min -default "" -readonly 1
+        option -max -default "" -readonly 1
+        # Next, define a "validate" type method which should do the
+        # validation in the basic case.  This will allow the
+        # type command to be used as a validation type.  
+        typemethod validate {value} {
+            if {![string is integer -strict $value]} {
+                return -code error -errorcode INVALID \ 
+                    "invalid value \"$value\", expected integer"
+            }
+            return $value
+        }
+        # Next, the constructor should validate the subtype options,
+        # if any.  Since they are all readonly, we don't need to worry
+        # about validating the options on change.
+        constructor {args} {
+            # FIRST, get the options
+            $self configurelist $args
+            # NEXT, validate them.
+            # I'll leave this to your imagination.
+        }
+        # Next, define a "validate" instance method; its job is to
+        # validate values for subtypes.
+        method validate {value} {
+            # First, call the type method to do the basic validation.
+            $type validate $value
+            # Now we know it's a valid integer.
+            if {("" != $options(-min) && $value < $options(-min))  ||
+                ("" != $options(-max) && $value > $options(-max))} {
+                # It's out of range; format a detailed message about
+                # the error, and throw it.
+                set msg "...."
+                
+                return -code error -errorcode INVALID $msg
+            }
+            # Otherwise, if it's valid just return it.
+            return $valid
+        }
+    }
+
+

And now you have a type that can be subtyped.

+

The file "validate.tcl" in the Snit distribution defines all of Snit's +validation types; you can find the complete implementation for +snit::integer and the other types there, to use as examples for +your own types.

+
+
+

CAVEATS

+

If you have problems, find bugs, or new ideas you are hereby cordially +invited to submit a report of your problem, bug, or idea at the +SourceForge trackers for tcllib, which can be found at +http://sourceforge.net/projects/tcllib/. +The relevant category is snit.

+

Additionally, you might wish to join the Snit mailing list; +see http://www.wjduquette.com/snit for details.

+

One particular area to watch is using snit::widgetadaptor to +adapt megawidgets created by other megawidget packages; correct +widget destruction depends on the order of the <Destroy> bindings. +The wisest course is simply not to do this.

+
+

KNOWN BUGS

+
    +

  • Error stack traces returned by Snit 1.x are extremely ugly and typically +contain far too much information about Snit internals. The error +messages are much improved in Snit 2.2.

    • +

  • Also see the SourceForge Trackers at +http://sourceforge.net/projects/tcllib/, category snit.

    • +
+
+

HISTORY

+

During the course of developing Notebook +(See http://www.wjduquette.com/notebook), my Tcl-based personal +notebook application, I found I was writing it as a collection of +objects. I wasn't using any particular object-oriented framework; I +was just writing objects in pure Tcl following the guidelines in my +Guide to Object Commands +(see http://www.wjduquette.com/tcl/objects.html), along with a +few other tricks I'd picked up since. And though it was working well, +it quickly became tiresome because of the amount of boilerplate +code associated with each new object type.

+

So that was one thing--tedium is a powerful motivator. But the other +thing I noticed is that I wasn't using inheritance at all, and I +wasn't missing it. Instead, I was using delegation: objects that +created other objects and delegated methods to them.

+

And I said to myself, "This is getting tedious...there has got to be a +better way." And one afternoon, on a whim, I started working on Snit, +an object system that works the way Tcl works. Snit doesn't support +inheritance, but it's great at delegation, and it makes creating +megawidgets easy.

+

If you have any comments or suggestions (or bug reports!) don't +hesitate to send me e-mail at will@wjduquette.com. In addition, +there's a Snit mailing list; you can find out more about it at the +Snit home page (see http://www.wjduquette.com/snit).

+
+

CREDITS

+

Snit has been designed and implemented from the very beginning by +William H. Duquette. However, much credit belongs to the following +people for using Snit and providing me with valuable feedback: Rolf +Ade, Colin McCormack, Jose Nazario, Jeff Godfrey, Maurice Diamanti, +Egon Pasztor, David S. Cargo, Tom Krehbiel, Michael Cleverly, +Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian +Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, +and Anton Kovalenko. +If I've forgotten anyone, my apologies; let me know and I'll add +your name to the list.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category snit of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/snit/snitfaq.html Index: embedded/www/tcllib/files/modules/snit/snitfaq.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/snit/snitfaq.html @@ -0,0 +1,3254 @@ + + +snitfaq - Snit's Not Incr Tcl, OO system + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

snitfaq(n) 2.2 tcllib "Snit's Not Incr Tcl, OO system"

+

Name

+

snitfaq - Snit Frequently Asked Questions

+
+

Table Of Contents

+ +
+ +

OVERVIEW

+

What is this document?

+

This is an atypical FAQ list, in that few of the questions are +frequently asked. Rather, these are the questions I think a newcomer +to Snit should be asking. This file is not a complete reference to +Snit, however; that information is in the snit man page.

+
+

What is Snit?

+

Snit is a framework for defining abstract data types and megawidgets +in pure Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", +signifying that Snit takes a different approach to defining objects +than does Incr Tcl, the best known object framework for Tcl. Had +I realized that Snit would become at all popular, I'd probably have +chosen something else.

+

The primary purpose of Snit is to be object glue--to help you +compose diverse objects from diverse sources into types and +megawidgets with clean, convenient interfaces so that you can more +easily build your application.

+

Snit isn't about theoretical purity or minimalist design; it's about +being able to do powerful things easily and consistently without +having to think about them--so that you can concentrate on building +your application.

+

Snit isn't about implementing thousands of nearly identical +carefully-specified lightweight thingamajigs--not as individual Snit +objects. Traditional Tcl methods will be much faster, and not much +more complicated. But Snit is about implementing a clean interface +to manage a collection of thousands of nearly identical +carefully-specified lightweight thingamajigs (e.g., think of the text +widget and text tags, or the canvas widget and canvas objects). Snit +lets you hide the details of just how those thingamajigs are +stored--so that you can ignore it, and concentrate on building your +application.

+

Snit isn't a way of life, a silver bullet, or the Fountain of +Youth. It's just a way of managing complexity--and of managing some of +the complexity of managing complexity--so that you can concentrate on +building your application.

+
+

What version of Tcl does Snit require?

+

Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or +later. See SNIT VERSIONS for the differences between Snit +1.3 and Snit 2.2.

+
+

Where can I download Snit?

+

Snit is part of Tcllib, the standard Tcl library, so you might already +have it. It's also available at the Snit Home Page, +http://www.wjduquette.com/snit.

+
+

What are Snit's goals?

+
    +

  • A Snit object should be at least as efficient as a hand-coded Tcl +object (see http://www.wjduquette.com/tcl/objects.html).

    • +

  • The fact that Snit was used in an object's implementation should be +transparent (and irrelevant) to clients of that object.

    • +

  • Snit should be able to encapsulate objects from other sources, +particularly Tk widgets.

    • +

  • Snit megawidgets should be (to the extent possible) indistinguishable +in interface from Tk widgets.

    • +

  • Snit should be Tclish--that is, rather than trying to emulate C++, +Smalltalk, or anything else, it should try to emulate Tcl itself.

    • +

  • It should have a simple, easy-to-use, easy-to-remember syntax.

    • +
+
+

How is Snit different from other OO frameworks?

+

Snit is unique among Tcl object systems in that +it is based not on inheritance but on delegation. Object +systems based on inheritance only allow you to inherit from classes +defined using the same system, and that's a shame. In Tcl, an object +is anything that acts like an object; it shouldn't matter how the +object was implemented. I designed Snit to help me build applications +out of the materials at hand; thus, Snit is designed to be able to +incorporate and build on any object, whether it's a hand-coded object, +a Tk widget, an Incr Tcl object, a BWidget or almost anything else.

+

Note that you can achieve the effect of inheritance using +COMPONENTS and DELEGATION--and you can inherit +from anything that looks like a Tcl object.

+
+

What can I do with Snit?

+

Using Snit, a programmer can:

+
    +

  • Create abstract data types and Tk megawidgets.

    • +

  • Define instance variables, type variables, and Tk-style options.

    • +

  • Define constructors, destructors, instance methods, type methods, procs.

    • +

  • Assemble a type out of component types. Instance methods and options +can be delegated to the component types automatically.

    • +
+
+
+

SNIT VERSIONS

+

Which version of Snit should I use?

+

The current Snit distribution includes two versions, Snit 1.3 and Snit +2.2. The reason that both are included is that Snit 2.2 takes +advantage of a number of new features of Tcl 8.5 to improve run-time +efficiency; as a side-effect, the ugliness of Snit's error messages +and stack traces has been reduced considerably. The cost of using +Snit 2.2, of course, is that you must target Tcl 8.5.

+

Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but +requires only Tcl 8.3 and later.

+

In short, if you're targetting Tcl 8.3 or 8.4 you should use Snit 1.3. If +you can afford to target Tcl 8.5, you should definitely use Snit 2.2. +If you will be targetting both, you can use Snit 1.3 exclusively, or +(if your code is unaffected by the minor incompatibilities between the +two versions) you can use Snit 1.3 for Tcl 8.4 and Snit 2.2 for Tcl +8.5.

+
+

How do I select the version of Snit I want to use?

+

To always use Snit 1.3 (or a later version of Snit 1.x), invoke Snit +as follows:

+
package require snit 1.3
+
+

To always use Snit 2.2 (or a later version of Snit 2.x), say this +instead:

+
package require snit 2.2
+
+

Note that if you request Snit 2.2 explicitly, your application will +halt with Tcl 8.4, since Snit 2.2 is unavailable for Tcl 8.4.

+

If you wish your application to always use the latest available +version of Snit, don't specify a version number:

+
package require snit
+
+

Tcl will find and load the latest version that's available relative to +the version of Tcl being used. In this case, be careful to avoid +using any incompatible features.

+
+

How are Snit 1.3 and Snit 2.2 incompatible?

+

To the extent possible, Snit 2.2 is intended to be a drop-in +replacement for Snit 1.3. Unfortunately, some incompatibilities were +inevitable because Snit 2.2 uses Tcl 8.5's new +namespace ensemble mechanism to implement subcommand dispatch. +This approach is much faster than the mechanism used in Snit 1.3, and +also results in much better error messages; however, it also places +new constraints on the implementation.

+

There are four specific incompatibilities between Snit 1.3 and Snit 2.2.

+
    +

  • Snit 1.3 supports implicit naming of objects. Suppose you define a +new snit::type called dog. You can create instances of +dog in three ways:

    +
    dog spot               ;# Explicit naming
+set obj1 [dog %AUTO%]  ;# Automatic naming
+set obj2 [dog]         ;# Implicit naming
+
    +

    In Snit 2.2, type commands are defined using the namespace ensemble +mechanism; and namespace ensemble doesn't allow an ensemble command +to be called without a subcommand. In short, using +namespace ensemble there's no way to support implicit naming.

    +

    All is not lost, however. If the type has no type methods, then the +type command is a simple command rather than an ensemble, and +namespace ensemble is not used. In this case, implicit naming +is still possible.

    +

    In short, you can have implicit naming if you're willing to do without +type methods (including the standard type methods, like +$type info). To do so, use the -hastypemethods pragma:

    +
    pragma -hastypemethods 0
    +
    • +

  • Hierarchical methods and type methods are implemented differently in +Snit 2.2.

    +

    A hierarchical method is an instance method which has +subcommands; these subcommands are themselves methods. The Tk text +widget's tag command and its subcommands are examples of +hierarchical methods. You can implement such subcommands in Snit +simply by including multiple words in the method names:

    +
    method {tag configure} {tag args} { ... }
+method {tag cget} {tag option} {...}
+
    +

    Here we've implicitly defined a tag method which has two +subcommands, configure and cget.

    +

    In Snit 1.3, hierarchical methods could be called in two ways:

    +
    $obj tag cget -myoption      ;# The good way
+$obj {tag cget} -myoption    ;# The weird way
+
    +

    In the second call, we see that a hierarchical method or type method +is simply one whose name contains multiple words.

    +

    In Snit 2.2 this is no longer the case, and the "weird" way of calling +hierarchical methods and type methods no longer works.

    • +

  • The third incompatibility derives from the second. In Snit 1.3, +hierarchical methods were also simply methods whose name contains +multiple words. As a result, $obj info methods returned the +full names of all hierarchical methods. In the example above, +the list returned by $obj info methods would include +tag configure and tag cget but not tag, since +tag is defined only implicitly.

    +

    In Snit 2.2, hierarchical methods and type methods are no longer +simply ones whose +name contains multiple words; in the above example, the list returned +by $obj info methods would include tag but not +tag configure or tag cget.

    • +

  • The fourth incompatibility is due to a new feature. Snit 2.2 uses +the new namespace path command so that a type's code can +call any command defined in the type's parent namespace without +qualification or importation. For example, suppose you have a +package called mypackage which defines a number of commands +including a type, ::mypackage::mytype. Thanks to +namespace path, the type's code can call any of the other +commands defined in ::mypackage::.

    +

    This is extremely convenient. However, it also means that commands +defined in the parent namespace, ::mypackage:: can block the +type's access to identically named commands in the global namespace. +This can lead to bugs. For example, Tcllib includes a type called +::tie::std::file. This type's code calls the standard +file command. When run with Snit 2.2, the code broke-- +the type's command, ::tie::std::file, is itself a command +in the type's parent namespace, and so instead of calling +the standard file command, the type found itself calling +itself.

    • +
+
+

Are there other differences between Snit 1.x and Snit 2.2?

+

Yes.

+
    +

  • Method dispatch is considerably faster.

    • +

  • Many error messages and stack traces are cleaner.

    • +

  • The -simpledispatch pragma is obsolete, and ignored if +present. In Snit 1.x, -simpledispatch substitutes a faster +mechanism for method dispatch, at the cost of losing certain features. +Snit 2.2 method dispatch is faster still in all cases, so +-simpledispatch is no longer needed.

    • +

  • In Snit 2.2, a type's code (methods, type methods, etc.) can call commands +from the type's parent namespace without qualifying or importing +them, i.e., type ::parentns::mytype's code can call +::parentns::someproc as just someproc.

    +

    This is extremely useful when a type is defined as part of a larger +package, and shares a parent namespace with the rest of the package; +it means that the type can call other commands defined by the +package without any extra work.

    +

    This feature depends on the new Tcl 8.5 namespace path command, +which is why it hasn't been implemented for V1.x. V1.x code can +achieve something similar by placing

    +
    namespace import [namespace parent]::*
    +

    in a type constructor. This is less useful, however, as it picks up +only those commands which have already been exported by the parent +namespace at the time the type is defined.

    • +
+
+
+

OBJECTS

+

What is an object?

+

A full description of object-oriented programming is beyond +the scope of this FAQ, obviously. In simple terms, an object is an instance of +an abstract data type--a coherent bundle of code and data. +There are many ways to represent objects in Tcl/Tk; the best known +examples are the Tk widgets.

+

A Tk widget is an object; it is represented by a Tcl command. +The object's methods are subcommands of the Tcl command. The object's +properties are options accessed using the configure and +cget methods. Snit uses the same conventions as Tk widgets do.

+
+

What is an abstract data type?

+

In computer science terms, an abstract data type is a complex data +structure along with a set of operations--a stack, a queue, a +binary tree, etc--that is to say, in modern terms, an object. In systems +that include some form of inheritance the word class is +usually used instead of abstract data type, but as Snit +doesn't implement inheritance as it's ordinarily understood +the older term seems more appropriate. Sometimes this is called +object-based programming as opposed to object-oriented +programming. Note that you can easily create the effect of +inheritance using COMPONENTS and DELEGATION.

+

In Snit, as in Tk, a type is a command that creates instances +-- objects -- which belong to the type. Most types define some number +of options which can be set at creation time, and usually can be +changed later.

+

Further, an instance is also a Tcl command--a command that +gives access to the operations which are defined for that abstract +data type. Conventionally, the operations are defined as subcommands +of the instance command. For example, to insert +text into a Tk text widget, you use the text widget's insert +subcommand:

+
    # Create a text widget and insert some text in it.
+    text .mytext -width 80 -height 24
+    .mytext insert end "Howdy!"
+
+

In this example, text is the type command and +.mytext is the instance command.

+

In Snit, object subcommands are generally called +INSTANCE METHODS.

+
+

What kinds of abstract data types does Snit provide?

+

Snit allows you to define three kinds of abstract data type:

+
    +

  • snit::type

    • +

  • snit::widget

    • +

  • snit::widgetadaptor

    • +
+
+

What is a snit::type?

+

A snit::type is a non-GUI abstract data type, e.g., a stack or a +queue. snit::types are defined using the snit::type +command. For example, if you were designing a kennel management +system for a dog breeder, you'd need a dog type.

+
% snit::type dog {
+    # ...
+}
+::dog
+%
+
+

This definition defines a new command (::dog, in this case) +that can be used to define dog objects.

+

An instance of a snit::type can have INSTANCE METHODS, +INSTANCE VARIABLES, OPTIONS, and COMPONENTS. +The type itself can have TYPE METHODS, +TYPE VARIABLES, TYPE COMPONENTS, and +PROCS.

+
+

What is a snit::widget?, the short story

+

A snit::widget is a Tk megawidget built using Snit; it is very +similar to a snit::type. See WIDGETS.

+
+

What is a snit::widgetadaptor?, the short story

+

A snit::widgetadaptor uses Snit to wrap an existing widget type +(e.g., a Tk label), modifying its interface to a lesser or greater +extent. It is very similar to a snit::widget. +See WIDGET ADAPTORS.

+
+

How do I create an instance of a snit::type?

+

You create an instance of a snit::type by passing the new +instance's name to the type's create method. In the following +example, we create a dog object called spot.

+
% snit::type dog {
+    # ....
+}
+::dog
+% dog create spot
+::spot
+%
+
+

In general, the create method name can be omitted so long as +the instance name doesn't conflict with any defined +TYPE METHODS. (See TYPE COMPONENTS for the +special case in which this doesn't work.) +So the following example is identical to the +previous example:

+
% snit::type dog {
+    # ....
+}
+::dog
+% dog spot
+::spot
+%
+
+

This document generally uses the shorter form.

+

If the dog type defines OPTIONS, these can usually be +given defaults at creation time:

+
% snit::type dog {
+    option -breed mongrel
+    option -color brown
+    method bark {} { return "$self barks." }
+}
+::dog
+% dog create spot -breed dalmation -color spotted
+::spot
+% spot cget -breed
+dalmation
+% spot cget -color
+spotted
+%
+
+

Once created, the instance name now names a new Tcl command that is used +to manipulate the object. For example, the following code makes the +dog bark:

+
% spot bark
+::spot barks.
+%
+
+
+

How do I refer to an object indirectly?

+

Some programmers prefer to save the object name in a variable, and +reference it that way. For example,

+
% snit::type dog { ... }
+::dog
+% set d [dog spot -breed dalmation -color spotted]
+::spot
+% $d cget -breed
+dalmation
+% $d bark
+::spot barks.
+%
+
+

If you prefer this style, you might prefer to have Snit +generate the instance's name automatically.

+
+

How can I generate the object name automatically?

+

If you'd like Snit to generate an object name for you, +use the %AUTO% keyword as the requested name:

+
% snit::type dog { ... }
+::dog
+% set d [dog %AUTO%]
+::dog2
+% $d bark
+::dog2 barks.
+%
+
+

The %AUTO% keyword can be embedded in a longer string:

+
% set d [dog obj_%AUTO%]
+::obj_dog4
+% $d bark
+::obj_dog4 barks.
+%
+
+
+

Can types be renamed?

+

Tcl's rename command renames other commands. It's a common +technique in Tcl to modify an existing command by renaming it and +defining a new command with the original name; the new command usually +calls the renamed command.

+

snit::type commands, however, should never be renamed; to do so breaks +the connection between the type and its objects.

+
+

Can objects be renamed?

+

Tcl's rename command renames other commands. It's a common +technique in Tcl to modify an existing command by renaming it and +defining a new command with the original name; the new command usually +calls the renamed command.

+

All Snit objects (including widgets and widgetadaptors) +can be renamed, though this flexibility has some consequences:

+
    +

  • In an instance method, the implicit argument self will always +contain the object's current name, so instance methods can always call +other instance methods using $self.

    • +

  • If the object is renamed, however, then $self's value will change. +Therefore, don't use $self for anything that will break if +$self changes. For example, don't pass a callback command to +another object like this:

    +
    +    .btn configure -command [list $self ButtonPress]
+
    +

    You'll get an error if .btn calls your command after your object is +renamed.

    • +

  • Instead, your object should define its callback command like this:

    +
    +    .btn configure -command [mymethod ButtonPress]
+
    +

    The mymethod command returns code that will call the desired +method safely; the caller of the callback can add additional +arguments to the end of the command as usual.

    • +

  • Every object has a private namespace; the name of this namespace is +available in method bodies, etc., as the value of the implicit +argument selfns. This value is constant for the life of the +object. Use $selfns instead of $self if you need a +unique token to identify the object.

    • +

  • When a snit::widget's instance command is renamed, its Tk window +name remains the same -- and is still extremely +important. Consequently, the Tk window name is available in +method bodies as the value of the implicit argument win. +This value is constant for the +life of the object. When creating child windows, it's best to use +$win.child rather than $self.child as the name of the +child window.

    • +
+
+

How do I destroy a Snit object?

+

Any Snit object of any type can be destroyed by renaming +it to the empty string using the Tcl rename command.

+

Snit megawidgets (i.e., instances of snit::widget and +snit::widgetadaptor) can be destroyed like any other widget: by +using the Tk destroy command on the widget or on one of its +ancestors in the window hierarchy.

+

Every instance of a snit::type has a destroy method:

+
% snit::type dog { ... }
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot destroy
+% spot barks
+invalid command name "spot"
+%
+
+

Finally, every Snit type has a type method called destroy; calling it +destroys the type and all of its instances:

+
% snit::type dog { ... }
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% dog destroy
+% spot bark
+invalid command name "spot"
+% dog fido
+invalid command name "dog"
+%
+
+
+
+

INSTANCE METHODS

+

What is an instance method?

+

An instance method is a procedure associated with a specific object +and called as a subcommand of the object's command. It is given free +access to all of the object's type variables, instance variables, and +so forth.

+
+

How do I define an instance method?

+

Instance methods are defined in the type definition using +the method statement. Consider the following code that might be +used to add dogs to a computer simulation:

+
% snit::type dog {
+    method bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing."
+    }
+}
+::dog
+%
+
+

A dog can bark, and it can chase things.

+

The method statement looks just like a normal Tcl proc, +except that it appears in a snit::type definition. Notice that +every instance method gets an implicit argument called self; +this argument contains the object's name. (There's more on +implicit method arguments below.)

+
+

How does a client call an instance method?

+

The method name becomes a subcommand of the object. For example, +let's put a simulated dog through its paces:

+
% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot chase cat
+::spot chases cat.
+%
+
+
+

How does an instance method call another instance method?

+

If method A needs to call method B on the same object, it does so just +as a client does: it calls method B as a subcommand of the object +itself, using the object name stored in the implicit argument self.

+

Suppose, for example, that our dogs never chase anything without +barking at them:

+
% snit::type dog {
+    method bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing.  [$self bark]"
+    }
+}
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot chase cat
+::spot chases cat.  ::spot barks.
+%
+
+
+

Are there any limitations on instance method names?

+

Not really, so long as you avoid the standard instance method names: +configure, configurelist, cget, +destroy, and info. Also, method names consisting of +multiple words define hierarchical methods.

+
+

What is a hierarchical method?

+

An object's methods are subcommands of the object's instance command. +Hierarchical methods allow an object's methods to have subcommands of +their own; and these can in turn have subcommands, and so on. This +allows the programmer to define a tree-shaped command structure, such +as is used by many of the Tk widgets--the subcommands of the +Tk text widget's tag method are hierarchical methods.

+
+

How do I define a hierarchical method?

+

Define methods whose names consist of multiple words. These words +define the hierarchy implicitly. For example, the following code +defines a tag method with subcommands cget and +configure:

+
snit::widget mytext {
+    method {tag configure} {tag args} { ... }
+    method {tag cget} {tag option} {...}
+}
+
+

Note that there is no explicit definition for the tag method; +it is implicit in the definition of tag configure and +tag cget. If you tried to define tag explicitly in this +example, you'd get an error.

+
+

How do I call hierarchical methods?

+

As subcommands of subcommands.

+
% mytext .text
+.text
+% .text tag configure redtext -foreground red -background black
+% .text tag cget redtext -foreground
+red
+%
+
+
+

How do I make an instance method private?

+

It's often useful to define private methods, that is, instance methods +intended to be called only by other methods of the same object.

+

Snit doesn't implement any access control on instance methods, so all +methods are de facto public. Conventionally, though, the +names of public methods begin with a lower-case letter, and the names +of private methods begin with an upper-case letter.

+

For example, suppose our simulated dogs only bark in response to other +stimuli; they never bark just for fun. So the bark method +becomes Bark to indicate that it is private:

+
% snit::type dog {
+    # Private by convention: begins with uppercase letter.
+    method Bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing. [$self Bark]"
+    }
+}
+::dog
+% dog fido
+::fido
+% fido chase cat
+::fido chases cat. ::fido barks.
+%
+
+
+

Are there any limitations on instance method arguments?

+

Method argument lists are defined just like normal Tcl proc argument +lists; in particular, they can include arguments with default values + and the args argument.

+

However, every method also has a number of implicit arguments +provided by Snit in addition to those explicitly defined. The names +of these implicit arguments may not used to name explicit arguments.

+
+

What implicit arguments are passed to each instance method?

+

The arguments implicitly passed to every method are type, +selfns, win, and self.

+
+

What is $type?

+

The implicit argument type contains the fully qualified name of +the object's type:

+
% snit::type thing {
+    method mytype {} {
+        return $type
+    }
+}
+::thing
+% thing something
+::something
+% something mytype
+::thing
+%
+
+
+

What is $self?

+

The implicit argument self contains the object's fully +qualified name.

+

If the object's command is renamed, then $self will change to +match in subsequent calls. Thus, your code should not assume that +$self is constant unless you know for sure that the object +will never be renamed.

+
% snit::type thing {
+    method myself {} {
+        return $self
+    }
+}
+::thing
+% thing mutt
+::mutt
+% mutt myself
+::mutt
+% rename mutt jeff
+% jeff myself
+::jeff
+%
+
+
+

What is $selfns?

+

Each Snit object has a private namespace in which to store its +INSTANCE VARIABLES and OPTIONS. The implicit argument +selfns contains the name of this namespace; its value never changes, and +is constant for the life of the object, even if the object's name +changes:

+
% snit::type thing {
+    method myNameSpace {} {
+        return $selfns
+    }
+}
+::thing
+% thing jeff
+::jeff
+% jeff myNameSpace
+::thing::Snit_inst3
+% rename jeff mutt
+% mutt myNameSpace
+::thing::Snit_inst3
+%
+
+

The above example reveals how Snit names an instance's private +namespace; however, you should not write code that depends on the +specific naming convention, as it might change in future releases.

+
+

What is $win?

+

The implicit argument win is defined for all Snit methods, +though it really makes sense only for those of +WIDGETS and WIDGET ADAPTORS. $win is simply +the original name of the object, whether it's been renamed or not. +For widgets and widgetadaptors, it is also therefore the name of a Tk +window.

+

When a snit::widgetadaptor is used to modify the interface of a +widget or megawidget, it must rename the widget's original command and +replace it with its own.

+

Thus, using win whenever the Tk window name is called for +means that a snit::widget or snit::widgetadaptor can be +adapted by a snit::widgetadaptor. See WIDGETS for +more information.

+
+

How do I pass an instance method as a callback?

+

It depends on the context.

+

Suppose in my application I have a dog object named fido, +and I want fido to bark when a Tk button called .bark is +pressed. In this case, I create the callback command in the usual +way, using list:

+
    button .bark -text "Bark!" -command [list fido bark]
+
+

In typical Tcl style, we use a callback to hook two independent +components together. But suppose that the dog object has +a graphical interface and owns the button itself? In this case, +the dog must pass one of its own instance methods to the +button it owns. The obvious thing to do is this:

+
% snit::widget dog {
+    constructor {args} {
+        #...
+        button $win.barkbtn -text "Bark!" -command [list $self bark]
+        #...
+    }
+}
+::dog
+%
+
+

(Note that in this example, our dog +becomes a snit::widget, because it has GUI behavior. See +WIDGETS for more.) Thus, if we create a dog called +.spot, it will create a Tk button called .spot.barkbtn; +when pressed, the button will call $self bark.

+

Now, this will work--provided that .spot is never renamed to +something else. But surely renaming widgets is +abnormal? And so it is--unless .spot is the hull component of a +snit::widgetadaptor. If it is, then it will be renamed, and +.spot will become the name of the snit::widgetadaptor +object. When the button is pressed, the command $self bark +will be handled by the snit::widgetadaptor, which might or might +not do the right thing.

+

There's a safer way to do it, and it looks like this:

+
% snit::widget dog {
+    constructor {args} {
+        #...
+        button $win.barkbtn -text "Bark!" -command [mymethod bark]
+        #...
+    }
+}
+::dog
+%
+
+

The command mymethod takes any number of arguments, and can be +used like list to build up a callback command; the only +difference is that mymethod returns a +form of the command that won't change even if the instance's name +changes.

+

On the other hand, you might prefer to allow a widgetadaptor to +override a method such that your renamed widget will call the +widgetadaptor's method instead of its own. In this case, +using [list $self bark] will do what you want...but +this is a technique which should be used only in carefully controlled +circumstances.

+
+ +
+

INSTANCE VARIABLES

+

What is an instance variable?

+

An instance variable is a private variable associated with some +particular Snit object. Instance variables can be scalars or arrays.

+
+

How is a scalar instance variable defined?

+

Scalar instance variables are defined in the type definition using the +variable statement. You can simply name it, or you can +initialize it with a value:

+
snit::type mytype {
+    # Define variable "greeting" and initialize it with "Howdy!"
+    variable greeting "Howdy!"
+}
+
+
+

How is an array instance variable defined?

+

Array instance variables are also defined in the type definition +using the variable command. You can initialize them at the same +time by specifying the -array option:

+
snit::type mytype {
+    # Define array variable "greetings"
+    variable greetings -array {
+        formal "Good Evening"
+        casual "Howdy!"
+    }
+}
+
+
+

What happens if I don't initialize an instance variable?

+

Variables do not really exist until they are given values. If you +do not initialize a variable when you define it, then you must be +sure to assign a value to it (in the constructor, say, or in some +method) before you reference it.

+
+

Are there any limitations on instance variable names?

+

Just a few.

+

First, every Snit object has a built-in instance variable called +options, which should never be redefined.

+

Second, all names beginning with "Snit_" are reserved for +use by Snit internal code.

+

Third, instance variable names containing the namespace delimiter +(::) are likely to cause great confusion.

+
+

Do I need to declare my instance variables in my methods?

+

No. Once you've defined an instance variable in the type definition, +it can be used in any instance code (instance methods, the +constructor, and the destructor) without declaration. This differs +from normal Tcl practice, in which all non-local variables in a proc +need to be declared.

+

There is a speed penalty to having all instance variables implicitly +available in all instance code. Even though your code need not +declare the variables explicitly, Snit must still declare them, +and that takes time. If you have ten instance variables, a method +that uses none of them must still pay the declaration penalty for +all ten. In most cases, the additional runtime cost is negligible. +If extreme cases, you might wish to avoid it; there are two methods +for doing so.

+

The first is to define a single instance variable, an array, and store +all of your instance data in the array. This way, you're only paying +the declaration penalty for one variable--and you probably need the +variable most of the time anyway. This method breaks down if your +instance variables include multiple arrays; in Tcl 8.5, however, +the dict command might come to your rescue.

+

The second method is to declare your instance variables explicitly +in your instance code, while not including them in the type +definition:

+
snit::type dog {
+    constructor {} {
+        variable mood
+        set mood happy
+    }
+    method setmood {newMood} {
+        variable mood
+        set mood $newMood
+    }
+    method getmood {} {
+        variable mood
+        return $mood
+    }
+}
+
+

This allows you to ensure that only the required variables are +included in each method, at the cost of longer code and run-time +errors when you forget to declare a variable you need.

+
+

How do I pass an instance variable's name to another object?

+

In Tk, it's common to pass a widget a variable name; for example, Tk +label widgets have a -textvariable option which names the +variable which will contain the widget's text. This allows the +program to update the label's value just by assigning a new value to +the variable.

+

If you naively pass the instance variable name to the label widget, +you'll be confused by the result; Tk will assume that the name names a +global variable. Instead, you need to provide a fully-qualified +variable name. From within an instance method or a constructor, you +can fully qualify the variable's name using the myvar command:

+
snit::widget mywidget {
+    variable labeltext ""
+    constructor {args} {
+        # ...
+        label $win.label -textvariable [myvar labeltext]
+        # ...
+    }
+}
+
+
+

How do I make an instance variable public?

+

Practically speaking, you don't. Instead, you'll implement public +variables as OPTIONS. +Alternatively, you can write INSTANCE METHODS to set and get +the variable's value.

+
+
+

OPTIONS

+

What is an option?

+

A type's options are the equivalent of what other object-oriented +languages would call public member variables or properties: they are +data values which can be retrieved and (usually) set by the clients of +an object.

+

Snit's implementation of options follows the Tk model fairly exactly, +except that snit::type objects usually don't interact with +THE TK OPTION DATABASE; snit::widget and +snit::widgetadaptor objects, on the other hand, always do.

+
+

How do I define an option?

+

Options are defined in the type definition using the option +statement. Consider the following type, to be used in an application +that manages a list of dogs for a pet store:

+
snit::type dog {
+    option -breed -default mongrel
+    option -color -default brown
+    option -akc   -default 0
+    option -shots -default 0
+}
+
+

According to this, a dog has four notable properties: a +breed, a color, a flag that says whether it's pedigreed with the +American Kennel Club, and another flag that says whether it has had +its shots. The default dog, evidently, is a brown mutt.

+

There are a number of options you can specify when defining an option; +if -default is the only one, you can omit the word +-default as follows:

+
snit::type dog {
+    option -breed mongrel
+    option -color brown
+    option -akc   0
+    option -shots 0
+}
+
+

If no -default value is specified, the option's default value +will be the empty string (but see THE TK OPTION DATABASE).

+

The Snit man page refers to options like these as "locally defined" options.

+
+

How can a client set options at object creation?

+

The normal convention is that the client may pass any number of +options and their values after the object's name at object creation. +For example, the ::dog command defined in the previous answer can now +be used to create individual dogs. Any or all of the options may be +set at creation time.

+
% dog spot -breed beagle -color "mottled" -akc 1 -shots 1
+::spot
+% dog fido -shots 1
+::fido
+%
+
+

So ::spot is a pedigreed beagle; ::fido is a typical mutt, +but his owners evidently take care of him, because he's had his shots.

+

Note: If the type defines a constructor, it can specify a +different object-creation syntax. See CONSTRUCTORS for more +information.

+
+

How can a client retrieve an option's value?

+

Retrieve option values using the cget method:

+
% spot cget -color
+mottled
+% fido cget -breed
+mongrel
+%
+
+
+

How can a client set options after object creation?

+

Any number of options may be set at one time using the +configure instance method. Suppose that closer inspection +shows that ::fido is not a brown mongrel, but rather a rare Arctic Boar +Hound of a lovely dun color:

+
% fido configure -color dun -breed "Arctic Boar Hound"
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+
+

Alternatively, the configurelist method takes a list of +options and values; occasionally this is more convenient:

+
% set features [list -color dun -breed "Arctic Boar Hound"]
+-color dun -breed {Arctic Boar Hound}
+% fido configurelist $features
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+%
+
+

In Tcl 8.5, the * keyword can be used with +configure in this case:

+
% set features [list -color dun -breed "Arctic Boar Hound"]
+-color dun -breed {Arctic Boar Hound}
+% fido configure {*}$features
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+%
+
+

The results are the same.

+
+

How should an instance method access an option value?

+

There are two ways an instance method can set and retrieve an option's +value. One is to use the configure and cget +methods, as shown below.

+
% snit::type dog {
+    option -weight 10
+    method gainWeight {} {
+        set wt [$self cget -weight]
+        incr wt
+        $self configure -weight $wt
+    }
+}
+::dog
+% dog fido
+::fido
+% fido cget -weight
+10
+% fido gainWeight
+% fido cget -weight
+11
+%
+
+

Alternatively, Snit provides a built-in array instance variable called +options. The indices are the option names; the values are the +option values. The method gainWeight can thus be rewritten as +follows:

+
+    method gainWeight {} {
+        incr options(-weight)
+    }
+
+

As you can see, using the options variable involves considerably +less typing and is the usual way to do it. But if you use +-configuremethod or -cgetmethod (described in the following +answers), you might wish to use the configure and +cget methods anyway, just so that any special processing you've +implemented is sure to get done. Also, if the option is delegated to +a component then configure and cget are the only way +to access it without accessing the component directly. See +DELEGATION for more information.

+
+

How can I make an option read-only?

+

Define the option with -readonly yes.

+

Suppose you've got an option that determines how +instances of your type are constructed; it must be set at creation +time, after which it's constant. For example, a dog never changes its +breed; it might or might not have had its shots, and if not can have +them at a later time. -breed should be read-only, but +-shots should not be.

+
% snit::type dog {
+    option -breed -default mongrel -readonly yes
+    option -shots -default no
+}
+::dog
+% dog fido -breed retriever
+::fido
+% fido configure -shots yes
+% fido configure -breed terrier
+option -breed can only be set at instance creation
+%
+
+
+

How can I catch accesses to an option's value?

+

Define a -cgetmethod for the option.

+
+

What is a -cgetmethod?

+

A -cgetmethod is a method that's called whenever the related +option's value is queried via the +cget instance method. The handler can compute the option's +value, retrieve it from a database, or do anything else you'd like it to do.

+

Here's what the default behavior would look like if +written using a -cgetmethod:

+
snit::type dog {
+    option -color -default brown -cgetmethod GetOption
+    method GetOption {option} {
+        return $options($option)
+    }
+}
+
+

Any instance method can be used, provided that it takes one argument, +the name of the option whose value is to be retrieved.

+
+

How can I catch changes to an option's value?

+

Define a -configuremethod for the option.

+
+

What is a -configuremethod?

+

A -configuremethod is a method that's called whenever the +related option is given a new value via the configure or +configurelist instance methods. The method can +pass the value on to some other object, store it in a database, or do +anything else you'd like it to do.

+

Here's what the default configuration behavior would look like if +written using a -configuremethod:

+
snit::type dog {
+    option -color -default brown -configuremethod SetOption
+    method SetOption {option value} {
+        set options($option) $value
+    }
+}
+
+

Any instance method can be used, provided that it takes two arguments, +the name of the option and the new value.

+

Note that if your method doesn't store the value in the options +array, the options array won't get updated.

+
+

How can I validate an option's value?

+

Define a -validatemethod.

+
+

What is a -validatemethod?

+

A -validatemethod is a method that's called whenever the +related option is given a new value via the configure or +configurelist instance methods. It's the method's +responsibility to determine whether the new value is valid, and throw +an error if it isn't. The -validatemethod, if any, is called +before the value is stored in the options array; in particular, +it's called before the -configuremethod, if any.

+

For example, suppose an option always takes a Boolean value. You can +ensure that the value is in fact a valid Boolean like this:

+
% snit::type dog {
+    option -shots -default no -validatemethod BooleanOption
+    method BooleanOption {option value} {
+        if {![string is boolean -strict $value]} {
+            error "expected a boolean value, got \"$value\""
+        }
+    }
+}
+::dog
+% dog fido
+% fido configure -shots yes
+% fido configure -shots NotABooleanValue
+expected a boolean value, got "NotABooleanValue"
+%
+
+

Note that the same -validatemethod can be used to validate any number +of boolean options.

+

Any method can be a -validatemethod provided that it takes +two arguments, the option name and the new option value.

+
+
+

TYPE VARIABLES

+

What is a type variable?

+

A type variable is a private variable associated with a Snit type +rather than with a particular instance of the type. In C++ and Java, +the term static member variable is used for the same notion. +Type variables can be scalars or arrays.

+
+

How is a scalar type variable defined?

+

Scalar type variables are defined in the type definition using the +typevariable statement. You can simply name it, or you can +initialize it with a value:

+
+snit::type mytype {
+    # Define variable "greeting" and initialize it with "Howdy!"
+    typevariable greeting "Howdy!"
+}
+
+

Every object of type mytype now has access to a single variable +called greeting.

+
+

How is an array-valued type variable defined?

+

Array-valued type variables are also defined using the +typevariable command; to initialize them, include the +-array option:

+
snit::type mytype {
+    # Define typearray variable "greetings"
+    typevariable greetings -array {
+        formal "Good Evening"
+        casual "Howdy!"
+    }
+}
+
+
+

What happens if I don't initialize a type variable?

+

Variables do not really exist until they are given values. If you +do not initialize a variable when you define it, then you must be +sure to assign a value to it (in the type constructor, say) +before you reference it.

+
+

Are there any limitations on type variable names?

+

Type variable names have the same restrictions as +the names of INSTANCE VARIABLES do.

+
+

Do I need to declare my type variables in my methods?

+

No. Once you've defined a type variable in the type definition, it can +be used in INSTANCE METHODS or TYPE METHODS without +declaration. This differs from normal Tcl practice, in which all +non-local variables in a proc need to be declared.

+

Type variables are subject to the same speed/readability tradeoffs +as instance variables; see +Do I need to declare my instance variables in my methods?

+
+

How do I pass a type variable's name to another object?

+

In Tk, it's common to pass a widget a variable name; for example, Tk +label widgets have a -textvariable option which names the +variable which will contain the widget's text. This allows the +program to update the label's value just by assigning a new value to +the variable.

+

If you naively pass a type variable name to the label widget, you'll +be confused by the result; Tk will assume that the name names a global +variable. Instead, you need to provide a fully-qualified variable +name. From within an instance method or a constructor, you can fully +qualify the type variable's name using the mytypevar command:

+
snit::widget mywidget {
+    typevariable labeltext ""
+    constructor {args} {
+        # ...
+        label $win.label -textvariable [mytypevar labeltext]
+        # ...
+    }
+}
+
+
+

How do I make a type variable public?

+

There are two ways to do this. The preferred way is to write a pair +of TYPE METHODS to set and query the type variable's value.

+

Type variables are stored in the type's namespace, which has +the same name as the type itself. Thus, you can also +publicize the type variable's name in your +documentation so that clients can access it directly. For example,

+
snit::type mytype {
+    typevariable myvariable
+}
+set ::mytype::myvariable "New Value"
+
+
+
+

TYPE METHODS

+

What is a type method?

+

A type method is a procedure associated with the type itself rather +than with any specific instance of the type, and called as a +subcommand of the type command.

+
+

How do I define a type method?

+

Type methods are defined in the type definition using the +typemethod statement:

+
snit::type dog {
+    # List of pedigreed dogs
+    typevariable pedigreed
+    typemethod pedigreedDogs {} {
+        return $pedigreed
+    }
+}
+
+

Suppose the dog type maintains a list of the names of the dogs +that have pedigrees. The pedigreedDogs type method returns this +list.

+

The typemethod statement looks just like a normal Tcl +proc, except that it appears in a snit::type definition. +Notice that every type method gets an implicit argument called +type, which contains the fully-qualified type name.

+
+

How does a client call a type method?

+

The type method name becomes a subcommand of the type's command. For +example, assuming that the constructor adds each pedigreed dog to the +list of pedigreedDogs,

+
snit::type dog {
+    option -pedigreed 0
+    # List of pedigreed dogs
+    typevariable pedigreed
+    typemethod pedigreedDogs {} {
+        return $pedigreed
+    }
+    # ...
+}
+dog spot -pedigreed 1
+dog fido
+foreach dog [dog pedigreedDogs] { ... }
+
+
+

Are there any limitations on type method names?

+

Not really, so long as you avoid the standard type method names: +create, destroy, and info.

+
+

How do I make a type method private?

+

It's sometimes useful to define private type methods, that is, type +methods intended to be called only by other type or instance methods +of the same object.

+

Snit doesn't implement any access control on type methods; by +convention, the names of public methods begin with a lower-case +letter, and the names of private methods begin with an upper-case +letter.

+

Alternatively, a Snit proc can be used as a private type method; see +PROCS.

+
+

Are there any limitations on type method arguments?

+

Method argument lists are defined just like normal Tcl proc argument +lists; in particular, they can include arguments with default values +and the args argument.

+

However, every type method is called with an implicit argument called +type that contains the name of the type command. In addition, +type methods should by convention avoid using the names of the +arguments implicitly defined for INSTANCE METHODS.

+
+

How does an instance or type method call a type method?

+

If an instance or type method needs to call a type method, it should +use $type to do so:

+
snit::type dog {
+    typemethod pedigreedDogs {} { ... }
+    typemethod printPedigrees {} {
+        foreach obj [$type pedigreedDogs] { ... }
+    }
+}
+
+
+

How do I pass a type method as a callback?

+

It's common in Tcl to pass a snippet of code to another object, for it +to call later. Because types cannot be renamed, you can just +use the type name, or, if the callback is registered from within +a type method, type. For example, suppose we want to print a +list of pedigreed dogs when a Tk button is pushed:

+
+button .btn -text "Pedigrees" -command [list dog printPedigrees]
+pack .btn
+
+

Alternatively, from a method or type method you can use the +mytypemethod command, just as you would use mymethod +to define a callback command for INSTANCE METHODS.

+
+

Can type methods be hierarchical?

+

Yes, you can define hierarchical type methods in just the same way as +you can define hierarchical instance methods. See +INSTANCE METHODS for more.

+
+
+

PROCS

+

What is a proc?

+

A Snit proc is really just a Tcl proc defined within the type's +namespace. You can use procs for private code that isn't related to +any particular instance.

+
+

How do I define a proc?

+

Procs are defined by including a proc statement in the type +definition:

+
snit::type mytype {
+    # Pops and returns the first item from the list stored in the
+    # listvar, updating the listvar
+   proc pop {listvar} { ... }
+   # ...
+}
+
+
+

Are there any limitations on proc names?

+

Any name can be used, so long as it does not begin with Snit_; +names beginning with Snit_ are reserved for Snit's own use. +However, the wise programmer will avoid proc names (set, +list, if, etc.) that would shadow standard Tcl +command names.

+

proc names, being private, should begin with a capital letter according +to convention; however, as there are typically no public procs +in the type's namespace it doesn't matter much either way.

+
+

How does a method call a proc?

+

Just like it calls any Tcl command. For example,

+
snit::type mytype {
+    # Pops and returns the first item from the list stored in the
+    # listvar, updating the listvar
+    proc pop {listvar} { ... }
+    variable requestQueue {}
+    # Get one request from the queue and process it.
+    method processRequest {} {
+        set req [pop requestQueue]
+    }
+}
+
+
+

How can I pass a proc to another object as a callback?

+

The myproc command returns a callback command for the +proc, just as mymethod does for a method.

+
+
+

TYPE CONSTRUCTORS

+

What is a type constructor?

+

A type constructor is a body of code that initializes the type as a +whole, rather like a C++ static initializer. The body of a type +constructor is executed once when the type is defined, and never +again.

+

A type can have at most one type constructor.

+
+

How do I define a type constructor?

+

A type constructor is defined by using the typeconstructor +statement in the type definition. For example, suppose the type uses +an array-valued type variable as a look-up table, and the values in +the array have to be computed at start-up.

+
% snit::type mytype {
+    typevariable lookupTable
+    typeconstructor {
+        array set lookupTable {key value...}
+    }
+}
+
+
+
+

CONSTRUCTORS

+

What is a constructor?

+

In object-oriented programming, an object's constructor is responsible +for initializing the object completely at creation time. The constructor +receives the list of options passed to the snit::type command's +create method and can then do whatever it likes. That might include +computing instance variable values, reading data from files, creating +other objects, updating type and instance variables, and so forth.

+

The constructor's return value is ignored (unless it's an +error, of course).

+
+

How do I define a constructor?

+

A constructor is defined by using the constructor statement in +the type definition. Suppose that it's desired to keep a list of all +pedigreed dogs. The list can be maintained in a +type variable and retrieved by a type method. Whenever a dog is +created, it can add itself to the list--provided that it's registered +with the American Kennel Club.

+
% snit::type dog {
+    option -akc 0
+    typevariable akcList {}
+    constructor {args} {
+        $self configurelist $args
+        if {$options(-akc)} {
+            lappend akcList $self
+        }
+    }
+    typemethod akclist {} {
+        return $akcList
+    }
+}
+::dog
+% dog spot -akc 1
+::spot
+% dog fido
+::fido
+% dog akclist
+::spot
+%
+
+
+

What does the default constructor do?

+

If you don't provide a constructor explicitly, you get the default +constructor, which is identical to the explicitly-defined +constructor shown here:

+
snit::type dog {
+    constructor {args} {
+        $self configurelist $args
+    }
+}
+
+

When the constructor is called, args will be set to the list of +arguments that follow the object's name. The constructor is allowed +to interpret this list any way it chooses; the normal convention is +to assume that it's a list of option names and values, as shown in the +example above. If you simply want to save the option values, you +should use the configurelist method, as shown.

+
+

Can I choose a different set of arguments for the constructor?

+

Yes, you can. For example, suppose we wanted to be sure that the +breed was explicitly stated for every dog at creation time, and +couldn't be changed thereafter. One way to do that is as follows:

+
% snit::type dog {
+    variable breed
+    option -color brown
+    option -akc 0
+    constructor {theBreed args} {
+        set breed $theBreed
+        $self configurelist $args
+    }
+    method breed {} { return $breed }
+}
+::dog
+% dog spot dalmatian -color spotted -akc 1
+::spot
+% spot breed
+dalmatian
+
+

The drawback is that this syntax is non-standard, and may +limit the compatibility of your new type with other people's code. +For example, Snit assumes that it can create +COMPONENTS using the standard creation syntax.

+
+

Are there any limitations on constructor arguments?

+

Constructor argument lists are subject to the same limitations +as those on instance method argument lists. It has the +same implicit arguments, and can contain default values and the +args argument.

+
+

Is there anything special about writing the constructor?

+

Yes. Writing the constructor can be tricky if you're delegating +options to components, and there are specific issues relating to +snit::widgets and snit::widgetadaptors. See +DELEGATION, WIDGETS, +WIDGET ADAPTORS, and THE TK OPTION DATABASE.

+
+
+

DESTRUCTORS

+

What is a destructor?

+

A destructor is a special kind of method that's called when an object +is destroyed. It's responsible for doing any necessary clean-up when +the object goes away: destroying COMPONENTS, closing files, +and so forth.

+
+

How do I define a destructor?

+

Destructors are defined by using the destructor statement in the +type definition.

+

Suppose we're maintaining a list of pedigreed dogs; +then we'll want to remove dogs from it when they are destroyed.

+
snit::type dog {
+    option -akc 0
+    typevariable akcList {}
+    constructor {args} {
+        $self configurelist $args
+        if {$options(-akc)} {
+            lappend akcList $self
+        }
+    }
+    destructor {
+        set ndx [lsearch $akcList $self]
+        if {$ndx != -1} {
+            set akcList [lreplace $akcList $ndx $ndx]
+        }
+    }
+    typemethod akclist {} {
+        return $akcList
+    }
+}
+
+
+

Are there any limitations on destructor arguments?

+

Yes; a destructor has no explicit arguments.

+
+

What implicit arguments are passed to the destructor?

+

The destructor gets the same implicit arguments that are passed to +INSTANCE METHODS: type, selfns, win, and +self.

+
+

Must components be destroyed explicitly?

+

Yes and no.

+

Any Tk widgets created by a snit::widget or +snit::widgetadaptor will be destroyed automatically by Tk +when the megawidget is destroyed, in keeping with normal Tk behavior +(destroying a parent widget destroys the whole tree).

+

Components of normal snit::types, on the other hand, +are never destroyed automatically, nor are non-widget components +of Snit megawidgets. If your object creates them in its +constructor, then it should generally destroy them in its destructor.

+
+

Is there any special about writing a destructor?

+

Yes. If an object's constructor throws an error, the object's +destructor will be called to clean up; this means that the object +might not be completely constructed when the destructor is called. +This can cause the destructor to throw its own error; the result +is usually misleading, confusing, and unhelpful. Consequently, it's +important to write your destructor so that it's fail-safe.

+

For example, a dog might create a tail component; the +component will need to be destroyed. But suppose there's an error +while processing the creation options--the destructor will be called, +and there will be no tail to destroy. The simplest solution is +generally to catch and ignore any errors while destroying components.

+
snit::type dog {
+    component tail
+    constructor {args} {
+        $self configurelist $args
+        set tail [tail %AUTO%]
+    }
+    destructor {
+        catch {$tail destroy}
+    }
+}
+
+
+
+

COMPONENTS

+

What is a component?

+

Often an object will create and manage a number of other objects. A +Snit megawidget, for example, will often create a number of Tk +widgets. These objects are part of the main object; it is composed +of them, so they are called components of the object.

+

But Snit also has a more precise meaning for +COMPONENT. The components of a Snit object are those +objects to which methods or options can be delegated. +(See DELEGATION for more information about delegation.)

+
+

How do I declare a component?

+

First, you must decide what role a component plays within your object, +and give the role a name. Then, you declare the component using its +role name and the component statement. The component +statement declares an instance variable which is used to +store the component's command name when the component is created.

+

For example, suppose your dog object +creates a tail object (the better to wag with, no doubt):

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        # Create and save the component's command
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+    method wag {} {
+        $mytail wag
+    }
+}
+
+

As shown here, it doesn't matter what the tail object's real +name is; the dog object refers to it by its component name.

+

The above example shows one way to delegate the wag method to +the mytail component; see DELEGATION for an easier way.

+
+

How is a component named?

+

A component has two names. The first name is that of the component +variable; this represents the role the component object plays within +the Snit object. This is the component name proper, and is the name +used to refer to the component within Snit code. The second name is +the name of the actual component object created by the Snit object's +constructor. This second name is always a Tcl command name, and is +referred to as the component's object name.

+

In the example in the previous question, the component name is +mytail; the mytail component's object name is chosen +automatically by Snit since %AUTO% was used when the component +object was created.

+
+

Are there any limitations on component names?

+

Yes. snit::widget and snit::widgetadaptor objects have a special +component called the hull component; thus, the name hull +should be used for no other purpose.

+

Otherwise, since component names are in fact instance variable names +they must follow the rules for INSTANCE VARIABLES.

+
+

What is an owned component?

+

An owned component is a component whose object command's +lifetime is controlled by the snit::type or snit::widget.

+

As stated above, a component is an object to +which our object can delegate methods or options. Under this +definition, our object will usually create its component objects, +but not necessarily. Consider the following: a dog object has a tail +component; but tail knows that it's part of the dog:

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+    destructor {
+        catch {$mytail destroy}
+    }
+    delegate method wagtail to mytail as wag
+    method bark {} {
+        return "$self barked."
+    }
+}
+ snit::type tail {
+     component mydog
+     option -partof -readonly yes
+     constructor {args} {
+         $self configurelist $args
+         set mydog $options(-partof)
+     }
+     method wag {} {
+         return "Wag, wag."
+     }
+     method pull {} {
+         $mydog bark
+     }
+ }
+
+

Thus, if you ask a dog to wag its tail, it tells its tail to wag; +and if you pull the dog's tail, the tail tells the dog to bark. In +this scenario, the tail is a component of the dog, and the dog is a +component of the tail, but the dog owns the tail and not the other way +around.

+
+

What does the install command do?

+

The install command creates an owned component using a specified +command, and assigns the result to the component's instance variable. +For example:

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        # set mytail [tail %AUTO% -partof $self]
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+

In a snit::type's code, the install +command shown above is equivalent to the set mytail command +that's commented out. In a snit::widget's or +snit::widgetadaptor's, code, however, the +install command also queries THE TK OPTION DATABASE +and initializes the new component's options accordingly. For consistency, +it's a good idea to get in the habit of using install for all +owned components.

+
+

Must owned components be created in the constructor?

+

No, not necessarily. In fact, there's no reason why an +object can't destroy and recreate a component multiple times over +its own lifetime.

+
+

Are there any limitations on component object names?

+

Yes.

+

Component objects which are Tk widgets or megawidgets must have valid +Tk window names.

+

Component objects which are not widgets or megawidgets must have +fully-qualified command names, i.e., names which include the full +namespace of the command. Note that Snit always creates objects with +fully qualified names.

+

Next, the object names of components and owned by your object +must be unique. This is no problem for widget components, since +widget names are always unique; but consider the following code:

+
snit::type tail { ... }
+snit::type dog {
+    delegate method wag to mytail
+    constructor {} {
+        install mytail using tail mytail
+    }
+}
+
+

This code uses the component name, mytail, as the component object +name. This is not good, and here's why: Snit instance code executes +in the Snit type's namespace. In this case, the mytail component is +created in the ::dog:: namespace, and will thus have the name +::dog::mytail.

+

Now, suppose you create two dogs. Both dogs will attempt to +create a tail called ::dog::mytail. The first will succeed, +and the second will fail, since Snit won't let you create an object if +its name is already a command. Here are two ways to avoid this situation:

+

First, if the component type is a snit::type you can +specify %AUTO% as its name, and be guaranteed to get a unique name. +This is the safest thing to do:

+
+    install mytail using tail %AUTO%
+
+

If the component type isn't a snit::type you can create +the component in the object's instance namespace:

+
+    install mytail using tail ${selfns}::mytail
+
+

Make sure you pick a unique name within the instance namespace.

+
+

Must I destroy the components I own?

+

That depends. When a parent widget is destroyed, all child widgets +are destroyed automatically. Thus, if your object is a snit::widget +or snit::widgetadaptor you don't need to destroy any components +that are widgets, because they will generally be children or +descendants of your megawidget.

+

If your object is an instance of snit::type, though, none of its +owned components will be destroyed automatically, nor will be +non-widget components of a snit::widget be destroyed +automatically. All such owned components must be destroyed +explicitly, or they won't be destroyed at all.

+
+

Can I expose a component's object command as part of my interface?

+

Yes, and there are two ways to do it. The most appropriate way is +usually to use DELEGATION. Delegation allows you to pass +the options and methods you specify along to particular components. +This effectively hides the components from the users of your type, and +ensures good encapsulation.

+

However, there are times when it's appropriate, not to mention +simpler, just to make the entire component part of your type's public +interface.

+
+

How do I expose a component's object command?

+

When you declare the component, specify the component +statement's -public option. The value of this option is the +name of a method which will be delegated to your component's object +command.

+

For example, supposed you've written a combobox megawidget which owns +a listbox widget, and you want to make the listbox's entire interface +public. You can do it like this:

+
snit::widget combobox {
+     component listbox -public listbox
+     constructor {args} {
+         install listbox using listbox $win.listbox ....
+     }
+}
+combobox .mycombo
+.mycombo listbox configure -width 30
+
+

Your comobox widget, .mycombo, now has a listbox method +which has all of the same subcommands as the listbox widget itself. +Thus, the above code sets the listbox component's width to 30.

+

Usually you'll let the method name be the same as the component name; +however, you can name it anything you like.

+
+
+

TYPE COMPONENTS

+

What is a type component?

+

A type component is a component that belongs to the type itself +instead of to a particular instance of the type. The relationship +between components and type components is the same as the +relationship between INSTANCE VARIABLES and +TYPE VARIABLES. Both INSTANCE METHODS and +TYPE METHODS can be delegated to type components.

+

Once you understand COMPONENTS and +DELEGATION, type components are just more of the same.

+
+

How do I declare a type component?

+

Declare a type component using the typecomponent statement. It +takes the same options (-inherit and -public) as the +component statement does, and defines a type variable to hold +the type component's object command.

+

Suppose in your model you've got many dogs, but only one +veterinarian. You might make the veterinarian a type component.

+
snit::type veterinarian { ... }
+snit::type dog {
+    typecomponent vet
+    # ...
+}
+
+
+

How do I install a type component?

+

Just use the set command to assign the component's object +command to the type component. Because types +(even snit::widget types) are not widgets, and do not have +options anyway, the extra features of the install command are +not needed.

+

You'll usually install type components in the type constructor, as +shown here:

+
snit::type veterinarian { ... }
+snit::type dog {
+    typecomponent vet
+    typeconstructor {
+        set vet [veterinarian %AUTO%]
+    }
+}
+
+
+ +
+

DELEGATION

+

What is delegation?

+

Delegation, simply put, is when you pass a task you've been given to +one of your assistants. (You do have assistants, don't you?) Snit +objects can do the same thing. The following example shows one way in +which the dog object can delegate its wag method and its +-taillength option to its tail component.

+
snit::type dog {
+    variable mytail
+    option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption
+    
+    method SetTailOption {option value} {
+         $mytail configure $option $value
+    }
+    method GetTailOption {option} {
+         $mytail cget $option
+    }
+    method wag {} {
+        $mytail wag
+    }
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+

This is the hard way to do it, by it demonstrates what delegation is +all about. See the following answers for the easy way to do it.

+

Note that the constructor calls the configurelist method +after it creates its tail; otherwise, +if -taillength appeared in the list of args we'd get an +error.

+
+

How can I delegate a method to a component object?

+

Delegation occurs frequently enough that Snit makes it easy. Any +method can be delegated to any component or type component +by placing a single delegate statement in the type definition. +(See COMPONENTS and TYPE COMPONENTS +for more information about component names.)

+

For example, here's a much better way to delegate the dog +object's wag method:

+
% snit::type dog {
+    delegate method wag to mytail
+    constructor {} {
+        install mytail using tail %AUTO%
+    }
+}
+::dog
+% snit::type tail {
+    method wag {} { return "Wag, wag, wag."}
+}
+::tail
+% dog spot
+::spot
+% spot wag
+Wag, wag, wag.
+
+

This code has the same effect as the code shown under the previous +question: when a dog's wag method is called, the call and +its arguments are passed along automatically to the tail object.

+

Note that when a component is mentioned in a delegate statement, +the component's instance variable is defined implicitly. However, +it's still good practice to declare it explicitly using the +component statement.

+

Note also that you can define a method name using the method +statement, or you can define it using delegate; you can't do +both.

+
+

Can I delegate to a method with a different name?

+

Suppose you wanted to delegate the dog's wagtail method to +the tail's wag method. After all you wag the tail, not +the dog. It's easily done:

+
snit::type dog {
+    delegate method wagtail to mytail as wag
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+
+

Can I delegate to a method with additional arguments?

+

Suppose the tail's wag method takes as an argument the +number of times the tail should be wagged. You want to delegate the +dog's wagtail method to the tail's wag +method, specifying that the tail should be wagged exactly three times. +This is easily done, too:

+
snit::type dog {
+    delegate method wagtail to mytail as {wag 3}
+    # ...
+}
+snit::type tail {
+    method wag {count} {
+        return [string repeat "Wag " $count]
+    }
+    # ...
+}
+
+
+

Can I delegate a method to something other than an object?

+

Normal method delegation assumes that you're delegating a method (a +subcommand of an object command) to a method of another object (a +subcommand of a different object command). But not all Tcl objects +follow Tk conventions, and not everything you'd to which you'd like +to delegate a method is necessary an object. Consequently, Snit makes +it easy to delegate a method to pretty much anything you like using +the delegate statement's using clause.

+

Suppose your dog simulation stores dogs in a database, each dog as a +single record. The database API you're using provides a number of +commands to manage records; each takes the record ID (a string you +choose) as its first argument. For example, saverec +saves a record. If you let the record ID be the name of the dog +object, you can delegate the dog's save method to the +saverec command as follows:

+
snit::type dog {
+    delegate method save using {saverec %s}
+}
+
+

The %s is replaced with the instance name when the +save method is called; any additional arguments are the +appended to the resulting command.

+

The using clause understands a number of other %-conversions; +in addition to the instance name, you can substitute in the method +name (%m), the type name (%t), the instance +namespace (%n), the Tk window name (%w), and, +if a component or typecomponent name was given in the +delegate statement, the component's object command +(%c).

+
+

How can I delegate a method to a type component object?

+

Just exactly as you would to a component object. The +delegate method statement accepts both component and type +component names in its to clause.

+
+

How can I delegate a type method to a type component object?

+

Use the delegate typemethod statement. It works like +delegate method, with these differences: first, it defines +a type method instead of an instance method; second, the +using clause ignores the %s, %n, +and %w %-conversions.

+

Naturally, you can't delegate a type method to an instance +component...Snit wouldn't know which instance should receive it.

+
+

How can I delegate an option to a component object?

+

The first question in this section (see DELEGATION) shows +one way to delegate an option to a component; but this pattern occurs +often enough that Snit makes it easy. For example, every tail +object has a -length option; we want to allow the creator of +a dog object to set the tail's length. We can do this:

+
% snit::type dog {
+    delegate option -length to mytail
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+::dog
+% snit::type tail {
+    option -partof
+    option -length 5
+}
+::tail
+% dog spot -length 7
+::spot
+% spot cget -length
+7
+
+

This produces nearly the same result as the -configuremethod and +-cgetmethod shown under the first question in this +section: whenever a dog object's -length option is set +or retrieved, the underlying tail object's option is set or +retrieved in turn.

+

Note that you can define an option name using the option +statement, or you can define it using delegate; you can't do +both.

+
+

Can I delegate to an option with a different name?

+

In the previous answer we delegated the dog's -length +option down to its tail. This is, of course, wrong. The dog +has a length, and the tail has a length, and they are different. What +we'd really like to do is give the dog a -taillength +option, but delegate it to the tail's -length option:

+
snit::type dog {
+    delegate option -taillength to mytail as -length
+    constructor {args} {
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+}
+
+
+

How can I delegate any unrecognized method or option to a component object?

+

It may happen that a Snit object gets most of its behavior from one of +its components. This often happens with snit::widgetadaptors, +for example, where we wish to slightly the modify the behavior of an +existing widget. To carry on with our dog example, however, suppose +that we have a snit::type called animal that implements a +variety of animal behaviors--moving, eating, sleeping, and so forth. +We want our dog objects to inherit these same behaviors, while +adding dog-like behaviors of its own. +Here's how we can give a dog methods and options of its own +while delegating all other methods and options to its animal +component:

+
snit::type dog {
+    delegate option * to animal
+    delegate method * to animal
+    option -akc 0
+    constructor {args} {
+        install animal using animal %AUTO% -name $self
+        $self configurelist $args
+    }
+    method wag {} {
+        return "$self wags its tail"
+    }
+}
+
+

That's it. A dog is now an animal that has a +-akc option and can wag its tail.

+

Note that we don't need to specify the full list of method names or +option names that animal will receive. +It gets anything dog doesn't recognize--and if it doesn't +recognize it either, it will simply throw an error, just as it should.

+

You can also delegate all unknown type methods to a type component +using delegate typemethod *.

+
+

How can I delegate all but certain methods or options to a component?

+

In the previous answer, we said that every dog is +an animal by delegating all unknown methods and options to the +animal component. But what if the animal type has some +methods or options that we'd like to suppress?

+

One solution is to explicitly delegate all the options and methods, +and forgo the convenience of delegate method * and +delegate option *. But if we wish to suppress only a few +options or methods, there's an easier way:

+
snit::type dog {
+    delegate option * to animal except -numlegs
+    delegate method * to animal except {fly climb}
+    # ...
+    constructor {args} {
+        install animal using animal %AUTO% -name $self -numlegs 4
+        $self configurelist $args
+    }
+    # ...
+}
+
+

Dogs have four legs, so we specify that explicitly when we create the +animal component, and explicitly exclude -numlegs from the +set of delegated options. Similarly, dogs can neither +fly nor climb, +so we exclude those animal methods as shown.

+
+

Can a hierarchical method be delegated?

+

Yes; just specify multiple words in the delegated method's name:

+
snit::type tail {
+    method wag {} {return "Wag, wag"}
+    method droop {} {return "Droop, droop"}
+}
+snit::type dog {
+    delegate method {tail wag} to mytail
+    delegate method {tail droop} to mytail
+    # ...
+    constructor {args} {
+        install mytail using tail %AUTO%
+        $self configurelist $args
+    }
+    # ...
+}
+
+

Unrecognized hierarchical methods can also be delegated; the following +code delegates all subcommands of the "tail" method to the "mytail" +component:

+
snit::type dog {
+    delegate method {tail *} to mytail
+    # ...
+}
+
+
+
+

WIDGETS

+

What is a snit::widget?

+

A snit::widget is the Snit version of what Tcl programmers +usually call a megawidget: a widget-like object usually +consisting of one or more Tk widgets all contained within a Tk frame.

+

A snit::widget is also a special kind of snit::type. Just +about everything in this FAQ list that relates to snit::types +also applies to snit::widgets.

+
+

How do I define a snit::widget?

+

snit::widgets are defined using the snit::widget command, +just as snit::types are defined by the snit::type command.

+

The body of the definition can contain all of the same kinds of +statements, plus a couple of others which will be mentioned below.

+
+

How do snit::widgets differ from snit::types?

+
    +

  • The name of an instance of a snit::type can be any valid Tcl +command name, in any namespace. +The name of an instance of a snit::widget must be a valid Tk +widget name, and its parent widget must already exist.

    • +

  • An instance of a snit::type can be destroyed by calling +its destroy method. Instances of a snit::widget have no +destroy method; use the Tk destroy command instead.

    • +

  • Every instance of a snit::widget has one predefined component +called its hull component. +The hull is usually a Tk frame or toplevel widget; any other +widgets created as part of the snit::widget will usually be +contained within the hull.

    • +

  • snit::widgets can have their options receive default values from +THE TK OPTION DATABASE.

    • +
+
+

What is a hull component?

+

Snit can't create a Tk widget object; only Tk can do that. +Thus, every instance of a snit::widget must be wrapped around a +genuine Tk widget; this Tk widget is called the hull component. +Snit effectively piggybacks the behavior you define (methods, options, +and so forth) on top of the hull component so that the whole thing +behaves like a standard Tk widget.

+

For snit::widgets the hull component must be a Tk widget that +defines the -class option.

+

snit::widgetadaptors differ from snit::widgets chiefly in +that any kind of widget can be used as the hull component; see +WIDGET ADAPTORS.

+
+

How can I set the hull type for a snit::widget?

+

A snit::widget's hull component will usually be a Tk frame +widget; however, it may be any Tk widget that defines the +-class option. You can +explicitly choose the hull type you prefer by including the hulltype +command in the widget definition:

+
snit::widget mytoplevel {
+    hulltype toplevel
+    # ...
+}
+
+

If no hulltype command appears, the hull will be a frame.

+

By default, Snit recognizes the following hull types: the Tk widgets +frame, labelframe, toplevel, and the Tile widgets +ttk::frame, ttk::labelframe, and ttk::toplevel. To +enable the use of some other kind of widget as the hull type, you can +lappend the widget command to the variable snit::hulltypes (always +provided the widget defines the -class option. For example, +suppose Tk gets a new widget type called a prettyframe:

+
lappend snit::hulltypes prettyframe
+snit::widget mywidget {
+    hulltype prettyframe
+    # ...
+}
+
+
+

How should I name widgets which are components of a snit::widget?

+

Every widget, whether a genuine Tk widget or a Snit megawidget, has to +have a valid Tk window name. When a snit::widget is first +created, its instance name, self, is a Tk window name; +however, if the snit::widget is used as the hull component by a +snit::widgetadaptor its instance name will be changed to +something else. For this reason, every snit::widget method, +constructor, destructor, and so forth is passed another implicit +argument, win, which is the window name of the megawidget. Any +children should be named using win as the root.

+

Thus, suppose you're writing a toolbar widget, a frame consisting of a +number of buttons placed side-by-side. It might look something like +this:

+
snit::widget toolbar {
+    delegate option * to hull
+    constructor {args} {
+        button $win.open -text Open -command [mymethod open]
+        button $win.save -text Save -command [mymethod save]
+        # ....
+        $self configurelist $args
+    }
+}
+
+

See also the question on renaming objects, toward the top of this +file.

+
+
+

WIDGET ADAPTORS

+

What is a snit::widgetadaptor?

+

A snit::widgetadaptor is a kind of snit::widget. Whereas +a snit::widget's hull is automatically created and is always a +Tk frame, a snit::widgetadaptor can be based on any Tk +widget--or on any Snit megawidget, or even (with luck) on megawidgets +defined using some other package.

+

It's called a widget adaptor because it allows you to take an +existing widget and customize its behavior.

+
+

How do I define a snit::widgetadaptor?

+

Use the snit::widgetadaptor command. The definition for a +snit::widgetadaptor looks just like that for a snit::type +or snit::widget, except that the constructor must create and +install the hull component.

+

For example, the following code creates a read-only text widget by the +simple device of turning its insert and delete +methods into no-ops. Then, we define new methods, ins and +del, +which get delegated to the hull component as insert and +delete. Thus, we've adapted the text widget and given it new +behavior while still leaving it fundamentally a text widget.

+
::snit::widgetadaptor rotext {
+    constructor {args} {
+        # Create the text widget; turn off its insert cursor
+        installhull using text -insertwidth 0
+        # Apply any options passed at creation time.
+        $self configurelist $args
+    }
+    # Disable the text widget's insert and delete methods, to
+    # make this readonly.
+    method insert {args} {}
+    method delete {args} {}
+    # Enable ins and del as synonyms, so the program can insert and
+    # delete.
+    delegate method ins to hull as insert
+    delegate method del to hull as delete
+    
+    # Pass all other methods and options to the real text widget, so
+    # that the remaining behavior is as expected.
+    delegate method * to hull
+    delegate option * to hull
+}
+
+

The most important part is in the constructor. +Whereas snit::widget creates the hull for you, +snit::widgetadaptor cannot -- it doesn't know what kind of +widget you want. So the first thing the constructor does is create +the hull component (a Tk text widget in this case), and then installs +it using the installhull command.

+

Note: There is no instance command until you create one by +installing a hull component. Any attempt to pass methods to $self +prior to calling installhull will fail.

+
+

Can I adapt a widget created elsewhere in the program?

+

Yes.

+

At times, it can be convenient to adapt a pre-existing widget instead +of creating your own. +For example, the Bwidget PagesManager widget manages a +set of frame widgets, only one of which is visible at a time. +The application chooses which frame is visible. All of the +These frames are created by the PagesManager itself, using +its add method. It's convenient to adapt these frames to +do what we'd like them to do.

+

In a case like this, the Tk widget will already exist when the +snit::widgetadaptor is created. Snit provides an alternate form +of the installhull command for this purpose:

+
snit::widgetadaptor pageadaptor {
+    constructor {args} {
+        # The widget already exists; just install it.
+        installhull $win
+        # ...
+    }
+}
+
+
+

Can I adapt another megawidget?

+

Maybe. If the other megawidget is a snit::widget or +snit::widgetadaptor, then yes. If it isn't then, again, maybe. +You'll have to try it and see. You're most likely to have trouble +with widget destruction--you have to make sure that your +megawidget code receives the <Destroy> event before the +megawidget you're adapting does.

+
+
+

THE TK OPTION DATABASE

+

What is the Tk option database?

+

The Tk option database is a database of default option values +maintained by Tk itself; every Tk application has one. The concept of +the option database derives from something called the X Windows +resource database; however, the option database is available in every +Tk implementation, including those which do not use the X Windows +system (e.g., Microsoft Windows).

+

Full details about the Tk option database are beyond the scope of this +document; both Practical Programming in Tcl and Tk by Welch, +Jones, and Hobbs, and Effective Tcl/Tk Programming by +Harrison and McClennan., have good introductions to it.

+

Snit is implemented so that most of the time it will simply do the +right thing with respect to the option database, provided that the +widget developer does the right thing by Snit. The body of this +section goes into great deal about what Snit requires. The following +is a brief statement of the requirements, for reference.

+
    +

  • If the widget's default widget class is not what is desired, set it +explicitly using the widgetclass statement in the widget +definition.

    • +

  • When defining or delegating options, specify the resource and class +names explicitly when necessary.

    • +

  • Use the installhull using command to create and install the +hull for snit::widgetadaptors.

    • +

  • Use the install command to create and install all +components which are widgets.

    • +

  • Use the install command to create and install +components which aren't widgets if you'd like them to +receive option values from the option database.

    • +
+

The interaction of Tk widgets with the option database is a complex +thing; the interaction of Snit with the option database is even more +so, and repays attention to detail.

+
+

Do snit::types use the Tk option database?

+

No, they don't; querying the option database requires a Tk window +name, and snit::types don't have one.

+

If you create an instance of a snit::type as a +component of a snit::widget or snit::widgetadaptor, on the +other hand, and if any options are delegated to the component, +and if you use install to create and install it, then +the megawidget will query the option database on the +snit::type's behalf. This might or might not be what you +want, so take care.

+
+

What is my snit::widget's widget class?

+

Every Tk widget has a "widget class": a name that is used when adding +option settings to the database. For Tk widgets, the widget class is +the same as the widget command name with an initial capital. For +example, the widget class of the Tk button widget is +Button.

+

Similarly, the widget class of a snit::widget defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of

+
snit::widget ::mylibrary::scrolledText { ... }
+
+

is ScrolledText.

+

The widget class can also be set explicitly using the +widgetclass statement within the snit::widget definition:

+
snit::widget ::mylibrary::scrolledText {
+    widgetclass Text
+    # ...
+}
+
+

The above definition says that a scrolledText megawidget has the +same widget class as an ordinary text widget. This might or +might not be a good idea, depending on how the rest of the megawidget +is defined, and how its options are delegated.

+
+

What is my snit::widgetadaptor's widget class?

+

The widget class of a snit::widgetadaptor is just the widget +class of its hull widget; Snit has no control over this.

+

Note that the widget class can be changed only for frame and +toplevel widgets, which is why these are the valid hull types +for snit::widgets.

+

Try to use snit::widgetadaptors only to make small modifications +to another widget's behavior. Then, it will usually not make sense to +change the widget's widget class anyway.

+
+

What are option resource and class names?

+

Every Tk widget option has three names: the option name, the resource +name, and the class name. +The option name begins with a hyphen and is all lowercase; it's used +when creating widgets, and with the configure and cget +commands.

+

The resource and class names are used to initialize option +default values by querying the option database. +The resource name is usually just the option +name minus the hyphen, but may contain uppercase letters at word +boundaries; the class name is usually just the resource +name with an initial capital, but not always. For example, here are +the option, resource, and class names for several Tk text +widget options:

+
    -background         background         Background 
+    -borderwidth        borderWidth        BorderWidth 
+    -insertborderwidth  insertBorderWidth  BorderWidth 
+    -padx               padX               Pad 
+
+

As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always.

+
+

What are the resource and class names for my megawidget's options?

+

For options implicitly delegated to a component using +delegate option *, the resource and class names will be +exactly those defined by the component. The configure method +returns these names, along with the option's default and current +values:

+
% snit::widget mytext {
+    delegate option * to text
+    constructor {args} {
+        install text using text .text
+        # ...
+    }
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -padx
+-padx padX Pad 1 1
+%
+
+

For all other options (whether locally defined or explicitly +delegated), the resource and class names can be defined explicitly, or +they can be allowed to have default values.

+

By default, the resource name is just the option name minus the +hyphen; the the class name is just the option name with an initial +capital letter. For example, suppose we explicitly delegate "-padx":

+
% snit::widget mytext {
+    option -myvalue 5
+    delegate option -padx to text
+    delegate option * to text
+    constructor {args} {
+        install text using text .text
+        # ...
+    }
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -myvalue
+-myvalue myvalue Myvalue 5 5
+% .text configure -padx
+-padx padx Padx 1 1
+%
+
+

Here the resource and class names are chosen using the default rules. +Often these rules are sufficient, but in the case of "-padx" we'd most +likely prefer that the option's resource and class names are the same +as for the built-in Tk widgets. This is easily done:

+
% snit::widget mytext {
+    delegate option {-padx padX Pad} to text
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -padx
+-padx padX Pad 1 1
+%
+
+
+

How does Snit initialize my megawidget's locally-defined options?

+

The option database is queried for each of the megawidget's +locally-defined options, using the option's resource and class name. +If the result isn't "", then it replaces the default value given in +widget definition. In either case, the default can be overridden by +the caller. For example,

+
option add *Mywidget.texture pebbled
+snit::widget mywidget {
+    option -texture smooth
+    # ...
+}
+mywidget .mywidget -texture greasy
+
+

Here, -texture would normally default to "smooth", but because of +the entry added to the option database it defaults to "pebbled". +However, the caller has explicitly overridden the default, and so the +new widget will be "greasy".

+
+

How does Snit initialize delegated options?

+

That depends on whether the options are delegated to the hull, or to +some other component.

+
+

How does Snit initialize options delegated to the hull?

+

A snit::widget's hull is a widget, and given that its class has +been set it is expected to query the option database for itself. The +only exception concerns options that are delegated to it with a +different name. Consider the following code:

+
option add *Mywidget.borderWidth 5
+option add *Mywidget.relief sunken
+option add *Mywidget.hullbackground red
+option add *Mywidget.background green
+snit::widget mywidget {
+    delegate option -borderwidth to hull
+    delegate option -hullbackground to hull as -background
+    delegate option * to hull
+    # ...
+}
+mywidget .mywidget
+set A [.mywidget cget -relief]
+set B [.mywidget cget -hullbackground]
+set C [.mywidget cget -background]
+set D [.mywidget cget -borderwidth]
+
+

The question is, what are the values of variables A, B, C and D?

+

The value of A is "sunken". The hull is a Tk frame which has been +given the widget class Mywidget; it will automatically query the +option database and pick up this value. Since the -relief option is +implicitly delegated to the hull, Snit takes no action.

+

The value of B is "red". The hull will automatically pick up the +value "green" for its -background option, just as it picked up the +-relief value. However, Snit knows that -hullbackground +is mapped to the hull's -background option; hence, it queries +the option database for -hullbackground and gets "red" and +updates the hull accordingly.

+

The value of C is also "red", because -background is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +-hullbackground. Note that this case is unusual; the +-background option should probably have been excluded using the delegate +statement's except clause, or (more likely) delegated to some other +component.

+

The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for -borderwidth defaults to +borderwidth, whereas the option database entry is +borderWidth, in +accordance with the standard Tk naming for this option. As with +-relief, the hull picks up its own -borderwidth +option before Snit +does anything. Because the option is delegated under its own name, +Snit assumes that the correct thing has happened, and doesn't worry +about it any further. To avoid confusion, the +-borderwidth option +should have been delegated like this:

+
    delegate option {-borderwidth borderWidth BorderWidth} to hull
+
+

For snit::widgetadaptors, the case is somewhat altered. Widget +adaptors retain the widget class of their hull, and the hull is not +created automatically by Snit. Instead, the snit::widgetadaptor +must call installhull in its constructor. The normal way +to do this is as follows:

+
snit::widgetadaptor mywidget {
+    # ...
+    constructor {args} {
+        # ...
+        installhull using text -foreground white
+        # ...
+    }
+    # ...
+}
+
+

In this case, the installhull command will create the hull using +a command like this:

+
    set hull [text $win -foreground white]
+
+

The hull is a text widget, so its widget class is Text. Just +as with snit::widget hulls, Snit assumes that it will pick up +all of its normal option values automatically, without help from Snit. +Options delegated from a different name are initialized from the +option database in the same way as described above.

+

In earlier versions of Snit, snit::widgetadaptors were expected +to call installhull like this:

+
    installhull [text $win -foreground white]
+
+

This form still works--but Snit will not query the option database as +described above.

+
+

How does Snit initialize options delegated to other components?

+

For hull components, Snit assumes that Tk will do most of the work +automatically. Non-hull components are somewhat more complicated, because +they are matched against the option database twice.

+

A component widget remains a widget still, and is therefore +initialized from the option database in the usual way. A text +widget remains a text widget whether it is a component of a +megawidget or not, and will be created as such.

+

But then, the option database is queried for all options delegated to +the component, and the component is initialized accordingly--provided +that the install command is used to create it.

+

Before option database support was added to Snit, the usual way to +create a component was to simply create it in the constructor and +assign its command name to the component variable:

+
snit::widget mywidget {
+    delegate option -background to myComp
+    constructor {args} {
+        set myComp [text $win.text -foreground black]
+    }
+}
+
+

The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used:

+
snit::widget mywidget {
+    delegate option -background to myComp
+    constructor {args} {
+        install myComp using text $win.text -foreground black
+    }
+}
+
+

The install command does the following:

+
    +

  • Builds a list of the options explicitly included in the install +command--in this case, -foreground.

    • +

  • Queries the option database for all options delegated explicitly to +the named component.

    • +

  • Creates the component using the specified command, after inserting +into it a list of options and values read from the option database. +Thus, the explicitly included options (like -foreground) will +override anything read from the option database.

    • +

  • If the widget definition implicitly delegated options to the component +using delegate option *, then Snit calls the newly created +component's configure method to receive a list of all of the +component's options. From this Snit builds a list of options +implicitly delegated to the component which were not explicitly +included in the install command. For all such options, Snit +queries the option database and configures the component accordingly.

    • +
+

You don't really need to know all of this; just use install to +install your components, and Snit will try to do the right thing.

+
+

What happens if I install a non-widget as a component of widget?

+

A snit::type never queries the option database. +However, a snit::widget can have non-widget components. And if +options are delegated to those components, and if the install +command is used to install those components, then they will be +initialized from the option database just as widget components are.

+

However, when used within a megawidget, install assumes that the +created component uses a reasonably standard widget-like creation +syntax. If it doesn't, don't use install.

+
+
+

ENSEMBLE COMMANDS

+

What is an ensemble command?

+

An ensemble command is a command with subcommands. Snit objects are +all ensemble commands; however, the term more usually refers to +commands like the standard Tcl commands string, file, +and clock. In a sense, these are singleton objects--there's +only one instance of them.

+
+

How can I create an ensemble command using Snit?

+

There are two ways--as a snit::type, or as an instance of +a snit::type.

+
+

How can I create an ensemble command using an instance of a snit::type?

+

Define a type whose INSTANCE METHODS are the subcommands +of your ensemble command. Then, create an instance of the type with +the desired name.

+

For example, the following code uses DELEGATION to create +a work-alike for the standard string command:

+
snit::type ::mynamespace::mystringtype {
+    delegate method * to stringhandler
+    constructor {} {
+        set stringhandler string
+    }
+}
+::mynamespace::mystringtype mystring
+
+

We create the type in a namespace, so that the type command is hidden; +then we create a single instance with the desired name-- +mystring, in this case.

+

This method has two drawbacks. First, it leaves the type command +floating about. More seriously, your shiny new ensemble +command will have info and destroy subcommands that +you probably have no use for. But read on.

+
+

How can I create an ensemble command using a snit::type?

+

Define a type whose TYPE METHODS are the subcommands +of your ensemble command.

+

For example, the following code uses DELEGATION to create +a work-alike for the standard string command:

+
snit::type mystring {
+    delegate typemethod * to stringhandler
+    typeconstructor {
+        set stringhandler string
+    }
+}
+
+

Now the type command itself is your ensemble command.

+

This method has only one drawback, and though it's major, it's +also surmountable. Your new ensemble command will have +create, info and destroy subcommands +you don't want. And worse yet, since the create method +can be implicit, users of your command will accidentally be creating +instances of your mystring type if they should mispell one +of the subcommands. The command will succeed--the first time--but +won't do what's wanted. This is very bad.

+

The work around is to set some PRAGMAS, as shown here:

+
snit::type mystring {
+    pragma -hastypeinfo    no 
+    pragma -hastypedestroy no 
+    pragma -hasinstances   no
+    delegate typemethod * to stringhandler
+    typeconstructor {
+        set stringhandler string
+    }
+}
+
+

Here we've used the pragma statement to tell Snit that we don't +want the info typemethod or the destroy typemethod, +and that our type has no instances; this eliminates the +create typemethod and all related code. As +a result, our ensemble command will be well-behaved, with no +unexpected subcommands.

+
+
+

PRAGMAS

+

What is a pragma?

+

A pragma is an option you can set in your type definitions that +affects how the type is defined and how it works once it is defined.

+
+

How do I set a pragma?

+

Use the pragma statement. Each pragma is an option with a +value; each time you use the pragma statement you can set one or +more of them.

+
+

How can I get rid of the "info" type method?

+

Set the -hastypeinfo pragma to no:

+
snit::type dog {
+    pragma -hastypeinfo no
+    # ...
+}
+
+

Snit will refrain from defining the info type method.

+
+

How can I get rid of the "destroy" type method?

+

Set the -hastypedestroy pragma to no:

+
snit::type dog {
+    pragma -hastypedestroy no
+    # ...
+}
+
+

Snit will refrain from defining the destroy type method.

+
+

How can I get rid of the "create" type method?

+

Set the -hasinstances pragma to no:

+
snit::type dog {
+    pragma -hasinstances no
+    # ...
+}
+
+

Snit will refrain from defining the create type method; +if you call the type command with an unknown method name, you'll get +an error instead of a new instance of the type.

+

This is useful if you wish to use a snit::type to define +an ensemble command rather than a type with instances.

+

Pragmas -hastypemethods and -hasinstances cannot +both be false (or there'd be nothing left).

+
+

How can I get rid of type methods altogether?

+

Normal Tk widget type commands don't have subcommands; all they do is +create widgets--in Snit terms, the type command calls the +create type method directly. To get the same behavior from +Snit, set the -hastypemethods pragma to no:

+
snit::type dog {
+    pragma -hastypemethods no
+    #...
+}
+# Creates ::spot
+dog spot
+# Tries to create an instance called ::create
+dog create spot
+
+

Pragmas -hastypemethods and -hasinstances cannot +both be false (or there'd be nothing left).

+
+

Why can't I create an object that replaces an old object with the same name?

+

Up until Snit 0.95, you could use any name for an instance of a +snit::type, even if the name was already in use by some other +object or command. You could do the following, for example:

+
snit::type dog { ... }
+dog proc
+
+

You now have a new dog named "proc", which is probably not something +that you really wanted to do. As a result, Snit now throws an error +if your chosen instance name names an existing command. To restore +the old behavior, set the -canreplace pragma to yes:

+
snit::type dog {
+    pragma -canreplace yes
+    # ...
+}
+
+
+

How can I make my simple type run faster?

+

In Snit 1.x, you can set the -simpledispatch pragma to yes.

+

Snit 1.x method dispatch is both flexible and fast, but the flexibility +comes with a price. If your type doesn't require the flexibility, the +-simpledispatch pragma allows you to substitute a simpler +dispatch mechanism that runs quite a bit faster. The limitations +are these:

+
    +

  • Methods cannot be delegated.

    • +

  • uplevel and upvar do not work as expected: the +caller's scope is two levels up rather than one.

    • +

  • The option-handling methods +(cget, configure, and configurelist) are very +slightly slower.

    • +
+

In Snit 2.2, the -simpledispatch macro is obsolete, and +ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's +-simpledispatch.

+
+
+

MACROS

+

What is a macro?

+

A Snit macro is nothing more than a Tcl proc that's defined in the +Tcl interpreter used to compile Snit type definitions.

+
+

What are macros good for?

+

You can use Snit macros to define new type definition syntax, and to +support conditional compilation.

+
+

How do I do conditional compilation?

+

Suppose you want your type to use a fast C extension if it's +available; otherwise, you'll fallback to a slower Tcl implementation. +You want to define one set of methods in the first case, and another +set in the second case. But how can your type definition know whether +the fast C extension is available or not?

+

It's easily done. Outside of any type definition, define a macro that +returns 1 if the extension is available, and 0 otherwise:

+
if {$gotFastExtension} {
+    snit::macro fastcode {} {return 1}
+} else {
+    snit::macro fastcode {} {return 0}
+}
+
+

Then, use your macro in your type definition:

+
snit::type dog {
+    if {[fastcode]} {
+        # Fast methods
+        method bark {} {...}
+        method wagtail {} {...}
+    } else {
+        # Slow methods
+        method bark {} {...}
+        method wagtail {} {...}
+    }
+}
+
+
+

How do I define new type definition syntax?

+

Use a macro. For example, your snit::widget's +-background option should be propagated to a number +of component widgets. You could implement that like this:

+
snit::widget mywidget {
+    option -background -default white -configuremethod PropagateBackground
+    method PropagateBackground {option value} {
+        $comp1 configure $option $value
+        $comp2 configure $option $value
+        $comp3 configure $option $value
+    }
+}
+
+

For one option, this is fine; if you've got a number of options, it +becomes tedious and error prone. So package it as a macro:

+
snit::macro propagate {option "to" components} {
+    option $option -configuremethod Propagate$option
+    set body "\n"
+    foreach comp $components {
+        append body "\$$comp configure $option \$value\n"
+    }
+    method Propagate$option {option value} $body
+}
+
+

Then you can use it like this:

+
snit::widget mywidget {
+    option -background default -white
+    option -foreground default -black
+    propagate -background to {comp1 comp2 comp3}
+    propagate -foreground to {comp1 comp2 comp3}
+}
+
+
+

Are there are restrictions on macro names?

+

Yes, there are. You can't redefine any standard Tcl commands or Snit +type definition statements. You can use any other command name, +including the name of a previously defined macro.

+

If you're using Snit macros in your application, go ahead and name +them in the global namespace, as shown above. But if you're using +them to define types or widgets for use by others, you should define +your macros in the same namespace as your types or widgets. That way, +they won't conflict with other people's macros.

+

If my fancy snit::widget is called ::mylib::mywidget, +for example, then I should define my propagate macro as +::mylib::propagate:

+
snit::macro mylib::propagate {option "to" components} { ... }
+snit::widget ::mylib::mywidget {
+    option -background default -white
+    option -foreground default -black
+    mylib::propagate -background to {comp1 comp2 comp3}
+    mylib::propagate -foreground to {comp1 comp2 comp3}
+}
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category snit of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/soundex/soundex.html Index: embedded/www/tcllib/files/modules/soundex/soundex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/soundex/soundex.html @@ -0,0 +1,172 @@ + + +soundex - Soundex + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

soundex(n) 1.0 tcllib "Soundex"

+

Name

+

soundex - Soundex

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require soundex ?1.0?
    • +
+ +
+
+

Description

+

This package provides soundex algorithms which allow the +comparison of words based on their phonetic likeness.

+

Currently only an algorithm by Knuth is provided, which +is tuned to english names and words.

+
+
::soundex::knuth string
+

Computes the soundex code of the input string using +Knuth's algorithm and returns it as the result of the +command.

+
+
+

EXAMPLES

+
+    % ::soundex::knuth Knuth
+    K530
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category soundex of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/stooop/stooop.html Index: embedded/www/tcllib/files/modules/stooop/stooop.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/stooop/stooop.html @@ -0,0 +1,298 @@ + + +stooop - Simple Tcl Only Object Oriented Programming + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

stooop(n) 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming"

+

Name

+

stooop - Object oriented extension.

+
+ + +

Description

+

This package provides commands to extend Tcl in an object oriented +manner, using a familiar C++ like syntax and behaviour. Stooop only +introduces a few new commands: class, new, delete, +virtual and classof. Along with a few coding conventions, +that is basically all you need to know to use stooop. Stooop is meant +to be as simple to use as possible.

+

This manual is very succinct and is to be used as a quick reminder for +the programmer, who should have read the thorough stooop_man.html +HTML documentation at this point.

+
+
::stooop::class name body
+

This command creates a class. The body, similar in contents to a Tcl +namespace (which a class actually also is), contains member procedure +definitions. Member procedures can also be defined outside the class +body, by prefixing their name with class::, as you would +proceed with namespace procedures.

+
+
proc class {this ?arg arg ...?} ?base {?arg arg ...?} ...? body
+

This is the constructor procedure for the class. It is invoked +following a new invocation on the class. It must have the same +name as the class and a first argument named this. Any number +of base classes specifications, including arguments to be passed to +their constructor, are allowed before the actual body of the +procedure.

+
proc ~class {this} body
+

This is the destructor procedure for the class. It is invoked +following a delete invocation. Its name must be the +concatenation of a single ~ character followed by the class +name (as in C++). It must have a single argument named this.

+
proc name {this ?arg arg ...?} body
+

This is a member procedure of the class, as its first argument is +named this. It allows a simple access of member data for the +object referenced by this inside the procedure. For example:

+
+   set ($this,data) 0
+
+
+
proc name {?arg arg ...?} body
+

This is a static (as in C++) member procedure of the class, as its +first argument is not named this. Static (global) class data +can be accessed as in:

+
+   set (data) 0
+
+
+
proc class {this copy} body
+

This is the optional copy procedure for the class. It must have the +same name as the class and exactly 2 arguments named this and +copy. It is invoked following a new invocation on an +existing object of the class.

+
+
::stooop::new class ?arg arg ...?
+

This command is used to create an object. The first argument is the +class name and is followed by the arguments needed by the +corresponding class constructor. A unique identifier for the object +just created is returned.

+
::stooop::delete object ?object ...?
+

This command is used to delete one or several objects. It takes one or +more object identifiers as argument(s).

+
::stooop::virtual proc name {this ?arg arg ...?} ?body?
+

The virtual specifier may be used on member procedures to +achieve dynamic binding. A procedure in a base class can then be +redefined (overloaded) in the derived class(es). If the base class +procedure is invoked on an object, it is actually the derived class +procedure which is invoked, if it exists. If the base class procedure +has no body, then it is considered to be a pure virtual and the +derived class procedure is always invoked.

+
::stooop::classof object
+

This command returns the class of the existing object passed as single +parameter.

+
::stooop::new object
+

This command is used to create an object by copying an existing +object. The copy constructor of the corresponding class is invoked if +it exists, otherwise a simple copy of the copied object data members +is performed.

+
+
+

DEBUGGING

+
+
Environment variables
+
+
STOOOPCHECKDATA
+

Setting this variable to any true value will cause stooop to check for +invalid member or class data access.

+
STOOOPCHECKPROCEDURES
+

Setting this variable to any true value will cause stooop to check for +invalid member procedure arguments and pure interface classes +instanciation.

+
STOOOPCHECKALL
+

Setting this variable to any true value will cause stooop to activate +both procedure and data member checking.

+
STOOOPCHECKOBJECTS
+

Setting this variable to any true value will cause stooop to activate +object checking. The following stooop namespace procedures then become +available for debugging: printObjects, record and +report.

+
STOOOPTRACEPROCEDURES
+

Setting this environment variable to either stdout, +stderr or a file name, activates procedure tracing. The +stooop library will then output to the specified channel 1 line of +informational text for each member procedure invocation.

+
STOOOPTRACEPROCEDURESFORMAT
+

Defines the trace procedures output format. Defaults to +"class: %C, procedure: %p, object: %O, arguments: %a".

+
STOOOPTRACEDATA
+

Setting this environment variable to either stdout, +stderr or a file name, activates data tracing. The stooop +library will then output to the specified channel 1 line of +informational text for each member data access.

+
STOOOPTRACEDATAFORMAT
+

Defines the trace data output format. Defaults to +"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v".

+
STOOOPTRACEDATAOPERATIONS
+

When tracing data output, by default, all read, write and unsetting +accesses are reported, but the user can set this variable to any +combination of the letters r, w, and u for +more specific tracing (please refer to the trace Tcl manual page +for more information).

+
STOOOPTRACEALL
+

Setting this environment variable to either stdout, +stderr or a file name, enables both procedure and data +tracing.

+
+
::stooop::printObjects ?pattern?
+

Prints an ordered list of existing objects, in creation order, oldest +first. Each output line contains the class name, object identifier and +the procedure within which the creation occurred. The optional pattern +argument (as in the Tcl string match command) can be used to +limit the output to matching class names.

+
::stooop::record
+

When invoked, a snapshot of all existing stooop objects is +taken. Reporting can then be used at a later time to see which objects +were created or deleted in the interval.

+
::stooop::report ?pattern?
+

Prints the created and deleted objects since the ::stooop::record +procedure was invoked last. If present, the pattern argument limits +the output to matching class names.

+
+
+

EXAMPLES

+

Please see the full HTML documentation in stooop_man.html.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stooop of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/stringprep/stringprep.html Index: embedded/www/tcllib/files/modules/stringprep/stringprep.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/stringprep/stringprep.html @@ -0,0 +1,230 @@ + + +stringprep - Preparation of Internationalized Strings + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

stringprep(n) 1.0.1 tcllib "Preparation of Internationalized Strings"

+

Name

+

stringprep - Implementation of stringprep

+
+ + +

Description

+

This is an implementation in Tcl of the Preparation of Internationalized +Strings ("stringprep"). It allows to define stringprep profiles and use +them to prepare Unicode strings for comparison as defined in RFC-3454.

+
+

COMMANDS

+
+
::stringprep::register profile ?-mapping list? ?-normalization form? ?-prohibited list? ?-prohibitedList list? ?-prohibitedCommand command? ?-prohibitedBidi boolean?
+

Register the stringprep profile named profile. Options +are the following.

+

Option -mapping specifies stringprep mapping tables. +This parameter takes list of tables from appendix B of RFC-3454. The usual +list values are {B.1 B.2} or {B.1 B.3} where B.1 contains characters which +commonly map to nothing, B.3 specifies case folding, and B.2 is used in +profiles with unicode normalization form KC. Defult value is {} which means +no mapping.

+

Option -normalization takes a string and if it is nonempty then it +uses as a name of Unicode normalization form. Any value of "D", "C", "KD" +or "KC" may be used, though RFC-3454 defines only two options: no +normalization or normalization using form KC.

+

Option -prohibited takes a list of RFC-3454 tables with prohibited +characters. Current version does allow to prohibit either all tables from +C.3 to C.9 or neither of them. An example of this list for RFC-3491 is +{A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}.

+

Option -prohibitedList specifies a list of additional prohibited +characters. The list contains not characters themselves but their Unicode +numbers. For example, Nodeprep specification from RFC-3920 forbids the +following codes: {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} (\" \& \' / : < > @).

+

Option -prohibitedCommand specifies a command which is called for +every character code in mapped and normalized string. If the command returns +true then the character is considered prohibited. This option is useful when +a list for -prohibitedList is too large.

+

Option -prohibitedBidi takes boolean value and if it is true then the +bidirectional character processing rules defined in section 6 of RFC-3454 are +used.

+
::stringprep::stringprep profile string
+

Performs stringprep operations defined in profile profile +to string string. Result is a prepared string or one of the following +errors: invalid_profile (profile profile is not defined), +prohibited_character (string string contains a prohibited character) +or prohibited_bidi (string string contains a prohibited bidirectional +sequence).

+
::stringprep::compare profile string1 string2
+

Compares two unicode strings prepared accordingly to stringprep +profile profile. The command returns 0 if prepared strings are equal, +-1 if string1 is lexicographically less than string2, or +1 if string1 is lexicographically greater than string2.

+
+
+

EXAMPLES

+

Nameprep profile definition (see RFC-3491):

+
+::stringprep::register nameprep  -mapping {B.1 B.2}  -normalization KC  -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedBidi 1
+
+

Nodeprep and resourceprep profile definitions (see RFC-3920):

+
+::stringprep::register nodeprep  -mapping {B.1 B.2}  -normalization KC  -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40}  -prohibitedBidi 1
+::stringprep::register resourceprep  -mapping {B.1}  -normalization KC  -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedBidi 1
+
+
+

REFERENCES

+
    +

  1. "Preparation of Internationalized Strings ('stringprep')", + (http://www.ietf.org/rfc/rfc3454.txt)

    2. +

  2. "Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)", + (http://www.ietf.org/rfc/rfc3491.txt)

    3. +

  3. "Extensible Messaging and Presence Protocol (XMPP): Core", + (http://www.ietf.org/rfc/rfc3920.txt)

    4. +
+
+

AUTHORS

+

Sergei Golovan

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/stringprep/stringprep_data.html Index: embedded/www/tcllib/files/modules/stringprep/stringprep_data.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/stringprep/stringprep_data.html @@ -0,0 +1,151 @@ + + +stringprep::data - Preparation of Internationalized Strings + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

stringprep::data(n) 1.0.1 tcllib "Preparation of Internationalized Strings"

+

Name

+

stringprep::data - stringprep data tables, generated, internal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require stringprep::data 1.0.1
    • +
+
+
+

Description

+

The stringprep::data package is a helper for +stringprep, providing it with the data tables needed to +perform its functions. It is an internal package which should +not be accessed on its own. Because of that it has no publicly +documented API either. Its implementation is generated by a script.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/stringprep/unicode.html Index: embedded/www/tcllib/files/modules/stringprep/unicode.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/stringprep/unicode.html @@ -0,0 +1,205 @@ + + +unicode - Unicode normalization + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

unicode(n) 1.0.0 tcllib "Unicode normalization"

+

Name

+

unicode - Implementation of Unicode normalization

+
+ + +

Description

+

This is an implementation in Tcl of the Unicode normalization forms.

+
+

COMMANDS

+
+
::unicode::fromstring string
+

Converts string to list of integer Unicode character codes which +is used in unicode for internal string representation.

+
::unicode::tostring uclist
+

Converts list of integers uclist back to Tcl string.

+
::unicode::normalize form uclist
+

Normalizes Unicode characters list ulist according to form +and returns the normalized list. Form form takes one of the following +values: D (canonical decomposition), C (canonical decomposition, followed +by canonical composition), KD (compatibility decomposition), or KC +(compatibility decomposition, followed by canonical composition).

+
::unicode::normalizeS form string
+

A shortcut to +::unicode::tostring [unicode::normalize \$form [::unicode::fromstring \$string]]. +Normalizes Tcl string and returns normalized string.

+
+
+

EXAMPLES

+
+% ::unicode::fromstring "\u0410\u0411\u0412\u0413"
+1040 1041 1042 1043
+% ::unicode::tostring {49 50 51 52 53}
+12345
+%
+
+
+% ::unicode::normalize D {7692 775}
+68 803 775
+% ::unicode::normalizeS KD "\u1d2c"
+A
+%
+
+
+

REFERENCES

+
    +

  1. "Unicode Standard Annex #15: Unicode Normalization Forms", + (http://unicode.org/reports/tr15/)

    2. +
+
+

AUTHORS

+

Sergei Golovan

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/stringprep/unicode_data.html Index: embedded/www/tcllib/files/modules/stringprep/unicode_data.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/stringprep/unicode_data.html @@ -0,0 +1,151 @@ + + +unicode::data - Preparation of Internationalized Strings + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

unicode::data(n) 1.0.0 tcllib "Preparation of Internationalized Strings"

+

Name

+

unicode::data - unicode data tables, generated, internal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require unicode::data 1.0.0
    • +
+
+
+

Description

+

The unicode::data package is a helper for +unicode, providing it with the data tables needed to +perform its functions. It is an internal package which should +not be accessed on its own. Because of that it has no publicly +documented API either. Its implementation is generated by a script.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/struct/disjointset.html Index: embedded/www/tcllib/files/modules/struct/disjointset.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/disjointset.html @@ -0,0 +1,245 @@ + +struct::disjointset - Tcl Data Structures + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::disjointset(n) 1.0 tcllib "Tcl Data Structures"

+

Name

+

struct::disjointset - Disjoint set data structure

+
+ + +

Description

+

This package provides disjoint sets. An alternative name for +this kind of structure is merge-find.

+

Normally when dealing with sets and their elements the question is "Is +this element E contained in this set S?", with both E and S known.

+

Here the question is "Which of several sets contains the element +E?". I.e. while the element is known, the set is not, and we wish to +find it quickly. It is not quite the inverse of the original question, +but close. +Another operation which is often wanted is that of quickly merging two +sets into one, with the result still fast for finding elements. Hence +the alternative term merge-find for this.

+

Why now is this named a disjoint-set ? +Because another way of describing the whole situation is that we have

+
    +

  • a finite set S, containing

    • +

  • a number of elements E, split into

    • +

  • a set of partitions P. The latter term + applies, because the intersection of each pair P, P' of + partitions is empty, with the union of all partitions + covering the whole set.

    • +

  • An alternative name for the partitions would be + equvalence classes, and all elements in the same + class are considered as equal.

    • +
+

Here is a pictorial representation of the concepts listed above:

+
+	+-----------------+ The outer lines are the boundaries of the set S.
+	|           /     | The inner regions delineated by the skewed lines
+	|  *       /   *  | are the partitions P. The *'s denote the elements
+	|      *  / \     | E in the set, each in a single partition, their
+	|*       /   \    | equivalence class.
+	|       /  *  \   |
+	|      / *   /    |
+	| *   /\  * /     |
+	|    /  \  /      |
+	|   /    \/  *    |
+	|  / *    \       |
+	| /     *  \      |
+	+-----------------+
+
+

For more information see http://en.wikipedia.org/wiki/Disjoint_set_data_structure.

+
+

API

+

The package exports a single command, ::struct::disjointset. All +functionality provided here can be reached through a subcommand of +this command.

+
+
::struct::disjointset disjointsetName
+

Creates a new disjoint set object with an associated global Tcl +command whose name is disjointsetName. This command may be used +to invoke various operations on the disjointset. It has the following +general form:

+
+
disjointsetName option ?arg arg ...?
+

The option and the args determine the exact behavior of +the command. The following commands are possible for disjointset +objects:

+
+
disjointsetName add-partition elements
+

Creates a new partition in specified disjoint set, and fills it with +the values found in the set of elements. The command maintains +the integrity of the disjoint set, i.e. it verifies that none of the +elements are already part of the disjoint set and throws an +error otherwise.

+

The result of the command is the empty string.

+
disjointsetName partitions
+

Returns the set of partitions the named disjoint set currently +consists of.

+
disjointsetName num-partitions
+

Returns the number of partitions the named disjoint set currently +consists of.

+
disjointsetName equal a b
+

Determines if the two elements a and b of the disjoint set +belong to the same partition. The result of the method is a boolean +value, True if the two elements are contained in the same +partition, and False otherwise.

+

An error will be thrown if either a or b are not elements +of the disjoint set.

+
disjointsetName merge a b
+

Determines the partitions the elements a and b are +contained in and merges them into a single partition. If the two +elements were already contained in the same partition nothing will +change.

+

The result of the method is the empty string.

+
disjointsetName find e
+

Returns the partition of the disjoint set which contains the element +e.

+
disjointsetName destroy
+

Destroys the disjoint set object and all associated memory.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: disjointset of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/graph.html Index: embedded/www/tcllib/files/modules/struct/graph.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/graph.html @@ -0,0 +1,785 @@ + + +struct::graph - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::graph(n) 2.4 tcllib "Tcl Data Structures"

+

Name

+

struct::graph - Create and manipulate directed graph objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require struct::graph ?2.4?
    • +
  • package require struct::list ?1.5?
    • +
  • package require struct::set ?2.2.3?
    • +
+ +
+
+

Description

+

A directed graph is a structure containing two collections of +elements, called nodes and arcs respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs.

+

Each arc is connected to two nodes, one of which is called the +source and the other the target. This imposes a +direction upon the arc, which is said to go from the source to the +target. It is allowed that source and target of an arc are the same +node. Such an arc is called a loop. +Whenever a node is either the source or target of an arc both are said +to be adjacent. This extends into a relation between nodes, +i.e. if two nodes are connected through at least one arc they are said +to be adjacent too.

+

Each node can be the source and target for any number of arcs. The +former are called the outgoing arcs of the node, the latter +the incoming arcs of the node. The number of arcs in either +set is called the in-degree resp. the out-degree of the +node.

+

In addition to maintaining the node and arc relationships, this graph +implementation allows any number of named attributes to be +associated with the graph itself, and each node or arc.

+

Note: The major version of the package struct has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +Changes for 2.0 for a full list of all changes, +incompatible and otherwise.

+

Note: A C-implementation of the command can be had from the +location http://www.purl.org/NET/schlenker/tcl/cgraph. See also +http://wiki.tcl.tk/cgraph. This implementation uses a bit less +memory than the tcl version provided here directly, and is faster. Its +support is limited to versions of the package before 2.0.

+

As of version 2.2 of this package a critcl based C implementation is +available from here as well. This implementation however requires Tcl +8.4 to run.

+

The main command of the package is:

+
+
::struct::graph ?graphName? ?=|:=|as|deserialize source?
+

The command creates a new graph object with an associated global Tcl +command whose name is graphName. This command may be used to +invoke various operations on the graph. It has the following general +form:

+
+
graphName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If graphName is not specified a unique name will be generated by +the package itself. If a source is specified the new graph will +be initialized to it. For the operators =, :=, and +as the source argument is interpreted as the name of +another graph object, and the assignment operator = will be +executed. For the operator deserialize the source is a +serialized graph object and deserialize will be executed.

+

In other words

+
+    ::struct::graph mygraph = b
+
+

is equivalent to

+
+    ::struct::graph mygraph
+    mygraph = b
+
+

and

+
+    ::struct::graph mygraph deserialize $b
+
+

is equivalent to

+
+    ::struct::graph mygraph
+    mygraph deserialize $b
+
+
+
+

The following commands are possible for graph objects:

+
+
graphName = sourcegraph
+

This is the assignment operator for graph objects. It copies +the graph contained in the graph object sourcegraph over the +graph data in graphName. The old contents of graphName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    graphName deserialize [sourcegraph serialize]
+
+

The operation assumes that the sourcegraph provides the method +serialize and that this method returns a valid graph +serialization.

+
graphName --> destgraph
+

This is the reverse assignment operator for graph objects. It +copies the graph contained in the graph object graphName over +the graph data in the object destgraph. +The old contents of destgraph are deleted by this operation.

+

This operation is in effect equivalent to

+
+    destgraph deserialize [graphName serialize]
+
+

The operation assumes that the destgraph provides the method +deserialize and that this method takes a graph serialization.

+
graphName append key value
+

Appends a value to one of the keyed values associated with the graph. +Returns the new value given to the attribute key.

+
graphName deserialize serialization
+

This is the complement to serialize. It replaces the graph +data in graphName with the graph described by the +serialization value. The old contents of graphName are +deleted by this operation.

+
graphName destroy
+

Destroys the graph, including its storage space and associated command.

+
graphName arc append arc key value
+

Appends a value to one of the keyed values associated with an +arc. Returns the new value given to the attribute key.

+
graphName arc attr key
+
+
graphName arc attr key -arcs list
+
+
graphName arc attr key -glob globpattern
+
+
graphName arc attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all arcs in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from arc names to the value of +attribute key at that arc. +Arcs not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-arcs
+

The value is a list of arcs. Only the arcs mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the arcs in the graph whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the arcs in the graph whose +names match this pattern are searched for the attribute.

+
+
graphName arc delete arc ?arc ...?
+

Remove the specified arcs from the graph.

+
graphName arc exists arc
+

Return true if the specified arc exists in the graph.

+
graphName arc flip arc
+

Reverses the direction of the named arc, i.e. the source and +target nodes of the arc are exchanged with each other.

+
graphName arc get arc key
+

Returns the value associated with the key key for the arc.

+
graphName arc getall arc ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the arc. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName arc getunweighted
+

Returns a list containing the names of all arcs in the graph which +have no weight associated with them.

+
graphName arc getweight arc
+

Returns the weight associated with the arc. Throws an error if +the arc has no weight associated with it.

+
graphName arc keys arc ?pattern?
+

Returns a list of keys for the arc. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName arc keyexists arc key
+

Return true if the specified key exists for the arc.

+
graphName arc insert start end ?child?
+

Insert an arc named child into the graph beginning at the node +start and ending at the node end. If the name of the new +arc is not specified the system will generate a unique name of the +form arcx.

+
graphName arc lappend arc key value
+

Appends a value (as a list) to one of the keyed values +associated with an arc. Returns the new value given to the +attribute key.

+
graphName arc rename arc newname
+

Renames the arc arc to newname. An error is thrown if +either the arc does not exist, or a arc with name newname does +exist. The result of the command is the new name of the arc.

+
graphName arc set arc key ?value?
+

Set or get one of the keyed values associated with an arc. +An arc may have any number of keyed values associated with it. +If value is not specified, this command returns the current value assigned to the key; +if value is specified, this command assigns that value to the key, and returns +that value.

+
graphName arc setunweighted ?weight?
+

Sets the weight of all arcs without a weight to weight. Returns +the empty string as its result. If not present weight defaults +to 0.

+
graphName arc setweight arc weight
+

Sets the weight of the arc to weight. Returns weight.

+
graphName arc unsetweight arc
+

Removes the weight of the arc, if present. Does nothing +otherwise. Returns the empty string.

+
graphName arc hasweight arc
+

Determines if the arc has a weight associated with it. The +result is a boolean value, True if a weight is defined, and +False otherwise.

+
graphName arc source arc
+

Return the node the given arc begins at.

+
graphName arc target arc
+

Return the node the given arc ends at.

+
graphName arc nodes arc
+

Return the nodes the given arc begins and ends at, +as a two-element list.

+
graphName arc move-source arc newsource
+

Changes the source node of the arc to newsource. It can be said +that the arc rotates around its target node.

+
graphName arc move-target arc newtarget
+

Changes the target node of the arc to newtarget. It can be said +that the arc rotates around its source node.

+
graphName arc move arc newsource newtarget
+

Changes both source and target nodes of the arc to newsource, +and newtarget resp.

+
graphName arc unset arc key
+

Remove a keyed value from the arc arc. The method will do +nothing if the key does not exist.

+
graphName arc weights
+

Returns a dictionary whose keys are the names of all arcs which have a +weight associated with them, and the values are these weights.

+
graphName arcs ?-key key? ?-value value? ?-filter cmdprefix? ?-in|-out|-adj|-inner|-embedding node node...?
+

Returns a list of arcs in the graph. If no restriction is specified a +list containing all arcs is returned. Restrictions can limit the list +of returned arcs based on the nodes that are connected by the arc, on +the keyed values associated with the arc, or both. A general filter +command can be used as well. The restrictions that involve connected +nodes take a variable number of nodes as argument, specified after the +name of the restriction itself.

+

The restrictions imposed by either -in, -out, +-adj, -inner, or -embedded are applied +first. Specifying more than one of them is illegal.

+

After that the restrictions set via -key (and +-value) are applied. Specifying more than one -key +(and -value) is illegal. Specifying -value alone, +without -key is illegal as well.

+

Any restriction set through -filter is applied +last. Specifying more than one -filter is illegal.

+

Coming back to the restrictions based on a set of nodes, the command +recognizes the following switches:

+
+
-in
+

Return a list of all arcs whose target is one of the nodes in the set +of nodes. I.e. it computes the union of all incoming arcs of the nodes +in the set.

+
-out
+

Return a list of all arcs whose source is one of the nodes in the set +of nodes. I.e. it computes the union of all outgoing arcs of the nodes +in the set.

+
-adj
+

Return a list of all arcs adjacent to at least one of the nodes in the +set. This is the union of the nodes returned by -in and +-out.

+
-inner
+

Return a list of all arcs which are adjacent to two of the nodes in +the set. This is the set of arcs in the subgraph spawned by the +specified nodes.

+
-embedding
+

Return a list of all arcs adjacent to exactly one of the nodes in the +set. This is the set of arcs connecting the subgraph spawned by the +specified nodes to the rest of the graph.

+
-key key
+

Limit the list of arcs that are returned to those arcs that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of arcs that are returned to those +arcs whose associated key key has the value value.

+
-filter cmdrefix
+

Limit the list of arcs that are returned to those arcs that pass the +test. The command in cmdprefix is called with two arguments, the +name of the graph object, and the name of the arc in question. It is +executed in the context of the caller and has to return a boolean +value. Arcs for which the command returns false are removed +from the result list before it is returned to the caller.

+
+
graphName lappend key value
+

Appends a value (as a list) to one of the keyed values +associated with the graph. Returns the new value given to the +attribute key.

+
graphName node append node key value
+

Appends a value to one of the keyed values associated with an +node. Returns the new value given to the attribute key.

+
graphName node attr key
+
+
graphName node attr key -nodes list
+
+
graphName node attr key -glob globpattern
+
+
graphName node attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all nodes in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from node names to the value of +attribute key at that node. +Nodes not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-nodes
+

The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the nodes in the graph whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the nodes in the graph whose +names match this pattern are searched for the attribute.

+
+
graphName node degree ?-in|-out? node
+

Return the number of arcs adjacent to the specified node. If one +of the restrictions -in or -out is given only the +incoming resp. outgoing arcs are counted.

+
graphName node delete node ?node...?
+

Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs.

+
graphName node exists node
+

Return true if the specified node exists in the graph.

+
graphName node get node key
+

Return the value associated with the key key for the node.

+
graphName node getall node ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName node keys node ?pattern?
+

Returns a list of keys for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName node keyexists node key
+

Return true if the specified key exists for the node.

+
graphName node insert ?node...?
+

Insert one or more nodes into the graph. The new nodes have no arcs +connected to them. If no node is specified one node will be inserted, +and the system will generate a unique name of the form +nodex for it.

+
graphName node lappend node key value
+

Appends a value (as a list) to one of the keyed values +associated with an node. Returns the new value given to the +attribute key.

+
graphName node opposite node arc
+

Return the node at the other end of the specified arc, which has +to be adjacent to the given node.

+
graphName node rename node newname
+

Renames the node node to newname. An error is thrown if +either the node does not exist, or a node with name newname does +exist. The result of the command is the new name of the node.

+
graphName node set node key ?value?
+

Set or get one of the keyed values associated with a node. A node may have any +number of keyed values associated with it. If value is not +specified, this command returns the current value assigned to the key; +if value is specified, this command assigns that value to the +key.

+
graphName node unset node key
+

Remove a keyed value from the node node. The method will do +nothing if the key does not exist.

+
graphName nodes ?-key key? ?-value value? ?-filter cmdprefix? ?-in|-out|-adj|-inner|-embedding node node...?
+

Return a list of nodes in the graph. Restrictions can limit the list +of returned nodes based on neighboring nodes, or based on the keyed +values associated with the node. The restrictions that involve +neighboring nodes have a list of nodes as argument, specified after +the name of the restriction itself.

+

The possible restrictions are the same as for method +arcs. The exact meanings change slightly, as they operate on +nodes instead of arcs. The command recognizes:

+
+
-in
+

Return a list of all nodes with at least one outgoing arc ending in a +node found in the specified set of nodes. Alternatively specified as +the set of source nodes for the -in arcs of the node set. The +incoming neighbours.

+
-out
+

Return a list of all nodes with at least one incoming arc starting in +a node found in the specified set of nodes. Alternatively specified as +the set of target nodes for the -out arcs of the node +set. The outgoing neighbours.

+
-adj
+

This is the union of the nodes returned by -in and +-out. The neighbours.

+
-inner
+

The set of neighbours (see -adj above) which are also in the +set of nodes. I.e. the intersection between the set of nodes and the +neighbours per -adj.

+
-embedding
+

The set of neighbours (see -adj above) which are not in the +set of nodes. I.e. the difference between the neighbours as per +-adj, and the set of nodes.

+
-key key
+

Limit the list of nodes that are returned to those nodes that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of nodes that are returned to those +nodes whose associated key key has the value value.

+
-filter cmdrefix
+

Limit the list of nodes that are returned to those nodes that pass the +test. The command in cmdprefix is called with two arguments, the +name of the graph object, and the name of the node in question. It is +executed in the context of the caller and has to return a boolean +value. Nodes for which the command returns false are removed +from the result list before it is returned to the caller.

+
+
graphName get key
+

Return the value associated with the key key for the graph.

+
graphName getall ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the whole graph. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName keys ?pattern?
+

Returns a list of keys for the whole graph. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName keyexists key
+

Return true if the specified key exists for the whole graph.

+
graphName serialize ?node...?
+

This method serializes the sub-graph spanned up by the nodes. In +other words it returns a tcl value completely describing that +graph. If no nodes are specified the whole graph will be serialized. +This allows, for example, the transfer of graph objects (or parts +thereof) over arbitrary channels, persistence, etc. +This method is also the basis for both the copy constructor and +the assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the graph interface. This is what will enable us to +copy graph data between different implementations of the same +interface.

+

The result is a list containing a multiple of three items, plus one! +In other words, '[llength $serial] % 3 == 1'. Valid values +include 1, 4, 7, ...

+

The last element of the list is a dictionary containing the attributes +associated with the whole graph. +Regarding the other elements; each triple consists of

+
    +

  1. The name of the node to be described,

    2. +

  2. A dictionary containing the attributes associated with the node,

    3. +

  3. And a list describing all the arcs starting at that node.

    4. +
+

The elements of the arc list are lists containing three or four +elements each, i.e.

+
    +

  1. The name of the arc described by the element,

    2. +

  2. A reference to the destination node of the arc. This reference is an +integer number given the index of that node in the main serialization +list. As that it is greater than or equal to zero, less than the +length of the serialization, and a multiple of three. +Note: For internal consistency no arc name may be used twice, +whether in the same node, or at some other node. This is a global +consistency requirement for the serialization.

    3. +

  3. And a dictionary containing the attributes associated with the arc.

    4. +

  4. The weight associated with the arc. This value is optional. Its +non-presence means that the arc in question has no weight associated +with it.

    +

    Note: This information is new, compared to the +serialization of graph 2.3 and earlier. By making it an +optional element the new format is maximally compatible with the +old. This means that any graph not using weights will generate a +serialization which is still understood by the older graph package. A +serialization will not be understood any longer by the older packages +if, and only if the graph it was generated from actually has arcs with +weights.

    5. +
+

For all attribute dictionaries they keys are the names of the +attributes, and the values are the values for each name.

+

Note: The order of the nodes in the serialization has no +relevance, nor has the order of the arcs per node.

+
+    # A possible serialization for the graph structure
+    #
+    #        d -----> %2
+    #       /         ^ \\
+    #      /         /   \\
+    #     /         b     \\
+    #    /         /       \\
+    #  %1 <- a - %0         e
+    #    ^         \\      /
+    #     \\        c     /
+    #      \\        \\  /
+    #       \\        v v
+    #        f ------ %3
+    # is
+    #
+    # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
+    #
+    # This assumes that the graph has neither attribute data nor weighted arcs.
+
+
+
graphName set key ?value?
+

Set or get one of the keyed values associated with a graph. A graph +may have any number of keyed values associated with it. If value +is not specified, this command returns the current value assigned to +the key; if value is specified, this command assigns that value +to the key.

+
graphName swap node1 node2
+

Swap the position of node1 and node2 in the graph.

+
graphName unset key
+

Remove a keyed value from the graph. The method will do nothing if the +key does not exist.

+
graphName walk node ?-order order? ?-type type? ?-dir direction? -command cmd
+

Perform a breadth-first or depth-first walk of the graph starting at +the node node going in either the direction of outgoing or +opposite to the incoming arcs.

+

The type of walk, breadth-first or depth-first, is determined by the +value of type; bfs indicates breadth-first, +dfs indicates depth-first. Depth-first is the default.

+

The order of the walk, pre-order, post-order or both-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order. Pre-order is the default. Pre-order walking means that a +node is visited before any of its neighbors (as defined by the +direction, see below). Post-order walking means that a parent is +visited after any of its neighbors. Both-order walking means that a +node is visited before and after any of its neighbors. The +combination of a breadth-first walk with post- or both-order is illegal.

+

The direction of the walk is determined by the value of dir; +backward indicates the direction opposite to the incoming +arcs, forward indicates the direction of the outgoing arcs.

+

As the walk progresses, the command cmd will be evaluated at +each node, with the mode of the call (enter or +leave) and values graphName and the name of the current +node appended. For a pre-order walk, all nodes are entered, for a +post-order all nodes are left. In a both-order walk the first visit of +a node enters it, the second visit leaves it.

+
+
+

Changes for 2.0

+

The following noteworthy changes have occurred:

+
    +

  1. The API for accessing attributes and their values has been +simplified.

    +

    All functionality regarding the default attribute "data" has been +removed. This default attribute does not exist anymore. All accesses +to attributes have to specify the name of the attribute in +question. This backward incompatible change allowed us to +simplify the signature of all methods handling attributes.

    +

    Especially the flag -key is not required anymore, even more, +its use is now forbidden. Please read the documentation for the arc +and node methods set, get, getall, +unset, append, lappend, keyexists +and keys for a description of the new API's.

    2. +

  2. The methods keys and getall now take an optional +pattern argument and will return only attribute data for keys matching +this pattern.

    3. +

  3. Arcs and nodes can now be renamed. See the documentation for the +methods arc rename and node rename.

    4. +

  4. The structure has been extended with API's for the serialization and +deserialization of graph objects, and a number of operations based on +them (graph assignment, copy construction).

    +

    Please read the documentation for the methods serialize, +deserialize, =, and -->, and the +documentation on the construction of graph objects.

    +

    Beyond the copying of whole graph objects these new API's also enable +the transfer of graph objects over arbitrary channels and for easy +persistence.

    5. +

  5. A new method, attr, was added to both arc and +node allowing the query and retrieval of attribute data +without regard to arc and node relationships.

    6. +

  6. Both methods arcs and nodes have been extended with +the ability to select arcs and nodes based on an arbitrary filtering +criterium.

    7. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/graph1.html Index: embedded/www/tcllib/files/modules/struct/graph1.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/graph1.html @@ -0,0 +1,412 @@ + + +struct::graph_v1 - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::graph_v1(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::graph_v1 - Create and manipulate directed graph objects

+
+ + +

Description

+

The ::struct::graph command creates a new graph object with an +associated global Tcl command whose name is graphName. This +command may be used to invoke various operations on the graph. It has +the following general form:

+
+
graphName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A directed graph is a structure containing two collections of +elements, called nodes and arcs respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs.

+

Each arc is connected to two nodes, one of which is called the +source and the other the target. This imposes a +direction upon the arc, which is said to go from the source to the +target. It is allowed that source and target of an arc are the same +node. Such an arc is called a loop. Whenever a node is source +or target of an arc both are said to be adjacent. This extends +into a relation between nodes, i.e. if two nodes are connected through +at least one arc they are said to be adjacent too.

+

Each node can be the source and target for any number of arcs. The +former are called the outgoing arcs of the node, the latter +the incoming arcs of the node. The number of edges in either +set is called the in- resp. the out-degree of the node.

+

In addition to maintaining the node and arc relationships, this graph +implementation allows any number of keyed values to be associated with +each node and arc.

+

The following commands are possible for graph objects:

+
+
graphName destroy
+

Destroy the graph, including its storage space and associated command.

+
graphName arc append arc ?-key key? value
+

Appends a value to one of the keyed values associated with an +arc. If no key is specified, the key data is +assumed.

+
graphName arc delete arc ?arc ...?
+

Remove the specified arcs from the graph.

+
graphName arc exists arc
+

Return true if the specified arc exists in the graph.

+
graphName arc get arc ?-key key?
+

Return the value associated with the key key for the arc. +If no key is specified, the key data is assumed.

+
graphName arc getall arc
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the arc.

+
graphName arc keys arc
+

Returns a list of keys for the arc.

+
graphName arc keyexists arc ?-key key?
+

Return true if the specified key exists for the arc. If no +key is specified, the key data is assumed.

+
graphName arc insert start end ?child?
+

Insert an arc named child into the graph beginning at the node +start and ending at the node end. If the name of the new +arc is not specified the system will generate a unique name of the +form arcx.

+
graphName arc lappend arc ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an arc. If no key is specified, the key +data is assumed.

+
graphName arc set arc ?-key key? ?value?
+

Set or get one of the keyed values associated with an arc. If no key +is specified, the key data is assumed. Each arc that is +added to a graph has the empty string assigned to the key +data automatically. An arc may have any number of keyed +values associated with it. If value is not specified, this +command returns the current value assigned to the key; if value +is specified, this command assigns that value to the key.

+
graphName arc source arc
+

Return the node the given arc begins at.

+
graphName arc target arc
+

Return the node the given arc ends at.

+
graphName arc unset arc ?-key key?
+

Remove a keyed value from the arc arc. If no key is specified, +the key data is assumed.

+
graphName arcs ?-key key? ?-value value? ?-in|-out|-adj|-inner|-embedding nodelist?
+

Return a list of arcs in the graph. If no restriction is specified a +list containing all arcs is returned. Restrictions can limit the list +of returned arcs based on the nodes that are connected by the arc, on +the keyed values associated with the arc, or both. The restrictions +that involve connected nodes have a list of nodes as argument, +specified after the name of the restriction itself.

+
+
-in
+

Return a list of all arcs whose target is one of the nodes in the +nodelist.

+
-out
+

Return a list of all arcs whose source is one of the nodes in the +nodelist.

+
-adj
+

Return a list of all arcs adjacent to at least one of the nodes in the +nodelist. This is the union of the nodes returned by +-in and -out.

+
-inner
+

Return a list of all arcs adjacent to two of the nodes in the +nodelist. This is the set of arcs in the subgraph spawned by the +specified nodes.

+
-embedding
+

Return a list of all arcs adjacent to exactly one of the nodes in the +nodelist. This is the set of arcs connecting the subgraph +spawned by the specified nodes to the rest of the graph.

+
-key key
+

Limit the list of arcs that are returned to those arcs that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of arcs that are returned to those +arcs whose associated key key has the value value.

+
+

The restrictions imposed by either -in, -out, +-adj, -inner, or -embedded are applied +first. Specifying more than one of them is illegal. +At last the restrictions set via -key (and -value) +are applied. +Specifying more than one -key (and -value) is +illegal.

+
graphName node append node ?-key key? value
+

Appends a value to one of the keyed values associated with an +node. If no key is specified, the key data is +assumed.

+
graphName node degree ?-in|-out? node
+

Return the number of arcs adjacent to the specified node. If one +of the restrictions -in or -out is given only the +incoming resp. outgoing arcs are counted.

+
graphName node delete node ?node ...?
+

Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs.

+
graphName node exists node
+

Return true if the specified node exists in the graph.

+
graphName node get node ?-key key?
+

Return the value associated with the key key for the node. +If no key is specified, the key data is assumed.

+
graphName node getall node
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the node.

+
graphName node keys node
+

Returns a list of keys for the node.

+
graphName node keyexists node ?-key key?
+

Return true if the specified key exists for the node. If +no key is specified, the key data is assumed.

+
graphName node insert ?child?
+

Insert a node named child into the graph. The nodes has no arcs +connected to it. If the name of the new child is not specified the +system will generate a unique name of the form nodex.

+
graphName node lappend node ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an node. If no key is specified, the key +data is assumed.

+
graphName node opposite node arc
+

Return the node at the other end of the specified arc, which has +to be adjacent to the given node.

+
graphName node set node ?-key key? ?value?
+

Set or get one of the keyed values associated with a node. If no key +is specified, the key data is assumed. Each node that is +added to a graph has the empty string assigned to the key +data automatically. A node may have any number of keyed +values associated with it. If value is not specified, this +command returns the current value assigned to the key; if value +is specified, this command assigns that value to the key.

+
graphName node unset node ?-key key?
+

Remove a keyed value from the node node. If no key is +specified, the key data is assumed.

+
graphName nodes ?-key key? ?-value value? ?-in|-out|-adj|-inner|-embedding nodelist?
+

Return a list of nodes in the graph. Restrictions can limit the list +of returned nodes based on neighboring nodes, or based on the keyed +values associated with the node. The restrictions that involve +neighboring nodes have a list of nodes as argument, specified after +the name of the restriction itself.

+

The possible restrictions are the same as for method +arcs. The set of nodes to return is computed as the union of +all source and target nodes for all the arcs satisfying the +restriction as defined for arcs.

+
graphName get ?-key key?
+

Return the value associated with the key key for the graph. If +no key is specified, the key data is assumed.

+
graphName getall
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the whole graph.

+
graphName keys
+

Returns a list of keys for the whole graph.

+
graphName keyexists ?-key key?
+

Return true if the specified key exists for the whole graph. If no +key is specified, the key data is assumed.

+
graphName set ?-key key? ?value?
+

Set or get one of the keyed values associated with a graph. If no key +is specified, the key data is assumed. Each graph has the +empty string assigned to the key data automatically. A graph +may have any number of keyed values associated with it. If value +is not specified, this command returns the current value assigned to +the key; if value is specified, this command assigns that value +to the key.

+
graphName swap node1 node2
+

Swap the position of node1 and node2 in the graph.

+
graphName unset ?-key key?
+

Remove a keyed value from the graph. If no key is specified, the key +data is assumed.

+
graphName walk node ?-order order? ?-type type? ?-dir direction? -command cmd
+

Perform a breadth-first or depth-first walk of the graph starting at +the node node going in either the direction of outgoing or +opposite to the incoming arcs.

+

The type of walk, breadth-first or depth-first, is determined by the +value of type; bfs indicates breadth-first, +dfs indicates depth-first. Depth-first is the default.

+

The order of the walk, pre-order, post-order or both-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order. Pre-order is the default. Pre-order walking means that a +node is visited before any of its neighbors (as defined by the +direction, see below). Post-order walking means that a parent is +visited after any of its neighbors. Both-order walking means that a +node is visited before and after any of its neighbors. The +combination of a bread-first walk with post- or both-order is illegal.

+

The direction of the walk is determined by the value of dir; +backward indicates the direction opposite to the incoming +arcs, forward indicates the direction of the outgoing arcs.

+

As the walk progresses, the command cmd will be evaluated at +each node, with the mode of the call (enter or +leave) and values graphName and the name of the current +node appended. For a pre-order walk, all nodes are entered, for a +post-order all nodes are left. In a both-order walk the first visit of +a node enters it, the second visit leaves it.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/graphops.html Index: embedded/www/tcllib/files/modules/struct/graphops.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/graphops.html @@ -0,0 +1,1042 @@ + + +struct::graph::op - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::graph::op(n) 0.11.3 tcllib "Tcl Data Structures"

+

Name

+

struct::graph::op - Operation for (un)directed graph objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require struct::graph::op ?0.11.3?
    • +
+ +
+
+

Description

+

The package described by this document, struct::graph::op, +is a companion to the package struct::graph. It provides a +series of common operations and algorithms applicable to (un)directed +graphs.

+

Despite being a companion the package is not directly dependent on +struct::graph, only on the API defined by that +package. I.e. the operations of this package can be applied to any and +all graph objects which provide the same API as the objects created +through struct::graph.

+
+

Operations

+
+
struct::graph::op::toAdjacencyMatrix g
+

This command takes the graph g and returns a nested list +containing the adjacency matrix of g.

+

The elements of the outer list are the rows of the matrix, the inner +elements are the column values in each row. The matrix has "n+1" +rows and columns, with the first row and column (index 0) containing +the name of the node the row/column is for. All other elements are +boolean values, True if there is an arc between the 2 nodes +of the respective row and column, and False otherwise.

+

Note that the matrix is symmetric. It does not represent the +directionality of arcs, only their presence between nodes. It is also +unable to represent parallel arcs in g.

+
struct::graph::op::toAdjacencyList G ?options...?
+

Procedure creates for input graph G, it's representation as Adjacency List. +It handles both directed and undirected graphs (default is undirected). +It returns dictionary that for each node (key) returns list of nodes adjacent +to it. When considering weighted version, for each adjacent node there is also +weight of the edge included.

+
+
Arguments:
+
+
Graph object G (input)
+

A graph to convert into an Adjacency List.

+
+
Options:
+
+
-directed
+

By default G is operated as if it were an Undirected graph. +Using this option tells the command to handle G as the directed graph it is.

+
-weights
+

By default any weight information the graph G may have is ignored. +Using this option tells the command to put weight information into the result. +In that case it is expected that all arcs have a proper weight, and an error +is thrown if that is not the case.

+
+
+
struct::graph::op::kruskal g
+

This command takes the graph g and returns a list containing the +names of the arcs in g which span up a minimum weight spanning tree +(MST), or, in the case of an un-connected graph, a minimum weight spanning +forest (except for the 1-vertex components). Kruskal's algorithm is used +to compute the tree or forest. +This algorithm has a time complexity of O(E*log E) or O(E* log V), +where V is the number of vertices and E is the number of edges +in graph g.

+

The command will throw an error if one or more arcs in g have no +weight associated with them.

+

A note regarding the result, the command refrains from explicitly +listing the nodes of the MST as this information is implicitly +provided in the arcs already.

+
struct::graph::op::prim g
+

This command takes the graph g and returns a list containing the +names of the arcs in g which span up a minimum weight spanning tree +(MST), or, in the case of an un-connected graph, a minimum weight spanning +forest (except for the 1-vertex components). Prim's algorithm is used to +compute the tree or forest. +This algorithm has a time complexity between O(E+V*log V) and O(V*V), +depending on the implementation (Fibonacci heap + Adjacency list versus +Adjacency Matrix). As usual V is the number of vertices and +E the number of edges in graph g.

+

The command will throw an error if one or more arcs in g have no +weight associated with them.

+

A note regarding the result, the command refrains from explicitly +listing the nodes of the MST as this information is implicitly +provided in the arcs already.

+
struct::graph::op::isBipartite? g ?bipartvar?
+

This command takes the graph g and returns a boolean value +indicating whether it is bipartite (true) or not +(false). If the variable bipartvar is specified the two +partitions of the graph are there as a list, if, and only if the graph +is bipartit. If it is not the variable, if specified, is not touched.

+
struct::graph::op::tarjan g
+

This command computes the set of strongly connected +components (SCCs) of the graph g. The result of the command is a +list of sets, each of which contains the nodes for one of the SCCs of +g. The union of all SCCs covers the whole graph, and no two SCCs +intersect with each other.

+

The graph g is acyclic if all SCCs in the result contain +only a single node. The graph g is strongly connected +if the result contains only a single SCC containing all nodes of +g.

+
struct::graph::op::connectedComponents g
+

This command computes the set of connected components (CCs) of +the graph g. The result of the command is a list of sets, each +of which contains the nodes for one of the CCs of g. The union +of all CCs covers the whole graph, and no two CCs intersect with each +other.

+

The graph g is connected if the result contains only a +single SCC containing all nodes of g.

+
struct::graph::op::connectedComponentOf g n
+

This command computes the connected component (CC) of the graph +g containing the node n. The result of the command is a +sets which contains the nodes for the CC of n in g.

+

The command will throw an error if n is not a node of the graph +g.

+
struct::graph::op::isConnected? g
+

This is a convenience command determining whether the graph g is +connected or not. The result is a boolean value, true +if the graph is connected, and false otherwise.

+
struct::graph::op::isCutVertex? g n
+

This command determines whether the node n in the graph g +is a cut vertex (aka articulation point). The result +is a boolean value, true if the node is a cut vertex, and +false otherwise.

+

The command will throw an error if n is not a node of the graph +g.

+
struct::graph::op::isBridge? g a
+

This command determines whether the arc a in the graph g +is a bridge (aka cut edge, or isthmus). The +result is a boolean value, true if the arc is a bridge, and +false otherwise.

+

The command will throw an error if a is not an arc of the graph +g.

+
struct::graph::op::isEulerian? g ?tourvar?
+

This command determines whether the graph g is eulerian +or not. The result is a boolean value, true if the graph is +eulerian, and false otherwise.

+

If the graph is eulerian and tourvar is specified then an euler +tour is computed as well and stored in the named variable. The tour is +represented by the list of arcs traversed, in the order of traversal.

+
struct::graph::op::isSemiEulerian? g ?pathvar?
+

This command determines whether the graph g is +semi-eulerian or not. The result is a boolean value, true +if the graph is semi-eulerian, and false otherwise.

+

If the graph is semi-eulerian and pathvar is specified then an +euler path is computed as well and stored in the named variable. The +path is represented by the list of arcs traversed, in the order of +traversal.

+
struct::graph::op::dijkstra g start ?options...?
+

This command determines distances in the weighted g from the +node start to all other nodes in the graph. The options specify +how to traverse graphs, and the format of the result.

+

Two options are recognized

+
+
-arcmode mode
+

The accepted mode values are directed and undirected. +For directed traversal all arcs are traversed from source to +target. For undirected traversal all arcs are traversed in the +opposite direction as well. Undirected traversal is the default.

+
-outputformat format
+

The accepted format values are distances and tree. In +both cases the result is a dictionary keyed by the names of all nodes +in the graph. For distances the value is the distance of the +node to start, whereas for tree the value is the path +from the node to start, excluding the node itself, but including +start. Tree format is the default.

+
+
struct::graph::op::distance g origin destination ?options...?
+

This command determines the (un)directed distance between the two +nodes origin and destination in the graph g. It +accepts the option -arcmode of struct::graph::op::dijkstra.

+
struct::graph::op::eccentricity g n ?options...?
+

This command determines the (un)directed eccentricity of the +node n in the graph g. It accepts the option +-arcmode of struct::graph::op::dijkstra.

+

The (un)directed eccentricity of a node is the maximal +(un)directed distance between the node and any other node in the +graph.

+
struct::graph::op::radius g ?options...?
+

This command determines the (un)directed radius of the graph +g. It accepts the option -arcmode of struct::graph::op::dijkstra.

+

The (un)directed radius of a graph is the minimal (un)directed +eccentricity of all nodes in the graph.

+
struct::graph::op::diameter g ?options...?
+

This command determines the (un)directed diameter of the graph +g. It accepts the option -arcmode of struct::graph::op::dijkstra.

+

The (un)directed diameter of a graph is the maximal (un)directed +eccentricity of all nodes in the graph.

+
struct::graph::op::BellmanFord G startnode
+

Searching for shortests paths between chosen node and all other nodes in graph G. Based +on relaxation method. In comparison to struct::graph::op::dijkstra it doesn't need assumption that all weights +on edges in input graph G have to be positive.

+

That generality sets the complexity of algorithm to - O(V*E), where V is the number of vertices +and E is number of edges in graph G.

+
+
Arguments:
+
+
Graph object G (input)
+

Directed, connected and edge weighted graph G, without any negative cycles ( presence of cycles with the negative sum +of weight means that there is no shortest path, since the total weight becomes lower each time the cycle is +traversed ). Negative weights on edges are allowed.

+
Node startnode (input)
+

The node for which we find all shortest paths to each other node in graph G.

+
+
Result:
+

Dictionary containing for each node (key) distances to each other node in graph G.

+
+

Note: If algorithm finds a negative cycle, it will return error message.

+
struct::graph::op::Johnsons G ?options...?
+

Searching for shortest paths between all pairs of vertices in graph. For sparse graphs +asymptotically quicker than struct::graph::op::FloydWarshall algorithm. Johnson's algorithm +uses struct::graph::op::BellmanFord and struct::graph::op::dijkstra as subprocedures.

+

Time complexity: O(n**2*log(n) +n*m), where n is the number of nodes and m is +the number of edges in graph G.

+
+
Arguments:
+
+
Graph object G (input)
+

Directed graph G, weighted on edges and not containing +any cycles with negative sum of weights ( the presence of such cycles means +there is no shortest path, since the total weight becomes lower each time the +cycle is traversed ). Negative weights on edges are allowed.

+
+
Options:
+
+
-filter
+

Returns only existing distances, cuts all Inf values for +non-existing connections between pairs of nodes.

+
+
Result:
+

Dictionary containing distances between all pairs of vertices.

+
+
struct::graph::op::FloydWarshall G
+

Searching for shortest paths between all pairs of edges in weighted graphs.

+

Time complexity: O(V^3) - where V is number of vertices.

+

Memory complexity: O(V^2).

+
+
Arguments:
+
+
Graph object G (input)
+

Directed and weighted graph G.

+
+
Result:
+

Dictionary containing shortest distances to each node from each node.

+
+

Note: Algorithm finds solutions dynamically. It compares all possible paths through the graph +between each pair of vertices. Graph shouldn't possess any cycle with negative +sum of weights (the presence of such cycles means there is no shortest path, +since the total weight becomes lower each time the cycle is traversed).

+

On the other hand algorithm can be used to find those cycles - if any shortest distance +found by algorithm for any nodes v and u (when v is the same node as u) is negative, +that node surely belong to at least one negative cycle.

+
struct::graph::op::MetricTravellingSalesman G
+

Algorithm for solving a metric variation of Travelling salesman problem. +TSP problem is NP-Complete, so there is no efficient algorithm to solve it. Greedy methods +are getting extremely slow, with the increase in the set of nodes.

+
+
Arguments:
+
+
Graph object G (input)
+

Undirected, weighted graph G.

+
+
Result:
+

Approximated solution of minimum Hamilton Cycle - closed path visiting all nodes, +each exactly one time.

+
+

Note: It's 2-approximation algorithm.

+
struct::graph::op::Christofides G
+

Another algorithm for solving metric TSP problem. +Christofides implementation uses Max Matching for reaching better approximation factor.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected, weighted graph G.

+
+
Result:
+

Approximated solution of minimum Hamilton Cycle - closed path visiting all nodes, +each exactly one time.

+
+

Note: It's is a 3/2 approximation algorithm.

+
struct::graph::op::GreedyMaxMatching G
+

Greedy Max Matching procedure, which finds maximal matching (not maximum) +for given graph G. It adds edges to solution, beginning from edges with the +lowest cost.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected graph G.

+
+
Result:
+

Set of edges - the max matching for graph G.

+
+
struct::graph::op::MaxCut G U V
+

Algorithm solving a Maximum Cut Problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

The graph to cut.

+
List U (output)
+

Variable storing first set of nodes (cut) given by solution.

+
List V (output)
+

Variable storing second set of nodes (cut) given by solution.

+
+
Result:
+

Algorithm returns number of edges between found two sets of nodes.

+
+

Note: MaxCut is a 2-approximation algorithm.

+
struct::graph::op::UnweightedKCenter G k
+

Approximation algorithm that solves a k-center problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected complete graph G, which satisfies triangle inequality.

+
Integer k (input)
+

Positive integer that sets the number of nodes that will be included in k-center.

+
+
Result:
+

Set of nodes - k center for graph G.

+
+

Note: UnweightedKCenter is a 2-approximation algorithm.

+
struct::graph::op::WeightedKCenter G nodeWeights W
+

Approximation algorithm that solves a weighted version of k-center problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected complete graph G, which satisfies triangle inequality.

+
Integer W (input)
+

Positive integer that sets the maximum possible weight of k-center found by algorithm.

+
List nodeWeights (input)
+

List of nodes and its weights in graph G.

+
+
Result:
+

Set of nodes, which is solution found by algorithm.

+
+

Note:WeightedKCenter is a 3-approximation algorithm.

+
struct::graph::op::GreedyMaxIndependentSet G
+

A maximal independent set is an independent set such that adding any other node +to the set forces the set to contain an edge.

+

Algorithm for input graph G returns set of nodes (list), which are contained in Max Independent +Set found by algorithm.

+
struct::graph::op::GreedyWeightedMaxIndependentSet G nodeWeights
+

Weighted variation of Maximal Independent Set. It takes as an input argument +not only graph G but also set of weights for all vertices in graph G.

+

Note: +Read also Maximal Independent Set description for more info.

+
struct::graph::op::VerticesCover G
+

Vertices cover is a set of vertices such that each edge of the graph is incident to +at least one vertex of the set. This 2-approximation algorithm searches for minimum +vertices cover, which is a classical optimization problem in computer science and +is a typical example of an NP-hard optimization problem that has an approximation +algorithm. +For input graph G algorithm returns the set of edges (list), which is Vertex Cover found by algorithm.

+
struct::graph::op::EdmondsKarp G s t
+

Improved Ford-Fulkerson's algorithm, computing the maximum flow in given flow network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Weighted and directed graph. Each edge should have set integer attribute considered as +maximum throughputs that can be carried by that link (edge).

+
Node s (input)
+

The node that is a source for graph G.

+
Node t (input)
+

The node that is a sink for graph G.

+
+
Result:
+

Procedure returns the dictionary containing throughputs for all edges. For +each key ( the edge between nodes u and v in the form of list u v ) there is +a value that is a throughput for that key. Edges where throughput values +are equal to 0 are not returned ( it is like there was no link in the flow network +between nodes connected by such edge).

+
+

The general idea of algorithm is finding the shortest augumenting paths in graph G, as long +as they exist, and for each path updating the edge's weights along that path, +with maximum possible throughput. The final (maximum) flow is found +when there is no other augumenting path from source to sink.

+

Note: Algorithm complexity : O(V*E), where V is the number of nodes and E is the number +of edges in graph G.

+
struct::graph::op::BusackerGowen G desiredFlow s t
+

Algorithm finds solution for a minimum cost flow problem. So, the goal is to find a flow, +whose max value can be desiredFlow, from source node s to sink node t in given flow network G. +That network except throughputs at edges has also defined a non-negative cost on each edge - cost of using that edge when +directing flow with that edge ( it can illustrate e.g. fuel usage, time or any other measure dependent on usages ).

+
+
Arguments:
+
+
Graph Object G (input)
+

Flow network (directed graph), each edge in graph should have two integer attributes: cost and throughput.

+
Integer desiredFlow (input)
+

Max value of the flow for that network.

+
Node s (input)
+

The source node for graph G.

+
Node t (input)
+

The sink node for graph G.

+
+
Result:
+

Dictionary containing values of used throughputs for each edge ( key ). +found by algorithm.

+
+

Note: Algorithm complexity : O(V**2*desiredFlow), where V is the number of nodes in graph G.

+
struct::graph::op::ShortestsPathsByBFS G s outputFormat
+

Shortest pathfinding algorithm using BFS method. In comparison to struct::graph::op::dijkstra it can +work with negative weights on edges. Of course negative cycles are not allowed. Algorithm is better than dijkstra +for sparse graphs, but also there exist some pathological cases (those cases generally don't appear in practise) that +make time complexity increase exponentially with the growth of the number of nodes.

+
+
Arguments:
+
+
Graph Object G (input)
+

Input graph.

+
Node s (input)
+

Source node for which all distances to each other node in graph G are computed.

+
+
Options and result:
+
+
distances
+

When selected outputFormat is distances - procedure returns dictionary containing +distances between source node s and each other node in graph G.

+
paths
+

When selected outputFormat is paths - procedure returns dictionary containing +for each node v, a list of nodes, which is a path between source node s and node v.

+
+
+
struct::graph::op::BFS G s ?outputFormat...?
+

Breadth-First Search - algorithm creates the BFS Tree. +Memory and time complexity: O(V + E), where V is the number of nodes and E +is number of edges.

+
+
Arguments:
+
+
Graph Object G (input)
+

Input graph.

+
Node s (input)
+

Source node for BFS procedure.

+
+
Options and result:
+
+
graph
+

When selected outputFormat is graph - procedure returns a graph structure (struct::graph), +which is equivalent to BFS tree found by algorithm.

+
tree
+

When selected outputFormat is tree - procedure returns a tree structure (struct::tree), +which is equivalent to BFS tree found by algorithm.

+
+
+
struct::graph::op::MinimumDiameterSpanningTree G
+

The goal is to find for input graph G, the spanning tree that +has the minimum diameter value.

+

General idea of algorithm is to run BFS over all vertices in graph +G. If the diameter d of the tree is odd, then we are sure that tree +given by BFS is minimum (considering diameter value). When, diameter d +is even, then optimal tree can have minimum diameter equal to d or +d-1.

+

In that case, what algorithm does is rebuilding the tree given by BFS, by +adding a vertice between root node and root's child node (nodes), such that +subtree created with child node as root node is the greatest one (has the +greatests height). In the next step for such rebuilded tree, we run again BFS +with new node as root node. If the height of the tree didn't changed, we have found +a better solution.

+

For input graph G algorithm returns the graph structure (struct::graph) that is +a spanning tree with minimum diameter found by algorithm.

+
struct::graph::op::MinimumDegreeSpanningTree G
+

Algorithm finds for input graph G, a spanning tree T with the minimum possible +degree. That problem is NP-hard, so algorithm is an approximation algorithm.

+

Let V be the set of nodes for graph G and let W be any subset of V. Lets +assume also that OPT is optimal solution and ALG is solution found by algorithm for input +graph G.

+

It can be proven that solution found with the algorithm must fulfil inequality:

+

((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected simple graph.

+
+
Result:
+

Algorithm returns graph structure, which is equivalent to spanning tree T found by algorithm.

+
+
struct::graph::op::MaximumFlowByDinic G s t blockingFlowAlg
+

Algorithm finds maximum flow for the flow network represented by graph G. It is based on +the blocking-flow finding methods, which give us different complexities what makes a better fit for +different graphs.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Options:
+
+
dinic
+

Procedure will find maximum flow for flow network G using Dinic's algorithm (struct::graph::op::BlockingFlowByDinic) +for blocking flow computation.

+
mkm
+

Procedure will find maximum flow for flow network G using Malhotra, Kumar and Maheshwari's algorithm (struct::graph::op::BlockingFlowByMKM) +for blocking flow computation.

+
+
Result:
+

Algorithm returns dictionary containing it's flow value for each edge (key) in network G.

+
+

Note: struct::graph::op::BlockingFlowByDinic gives O(m*n^2) complexity and +struct::graph::op::BlockingFlowByMKM gives O(n^3) complexity, where n is the number of nodes +and m is the number of edges in flow network G.

+
struct::graph::op::BlockingFlowByDinic G s t
+

Algorithm for given network G with source s and sink t, finds a blocking +flow, which can be used to obtain a maximum flow for that network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Result:
+

Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network G.

+
+

Note: Algorithm's complexity is O(n*m), where n is the number of nodes +and m is the number of edges in flow network G.

+
struct::graph::op::BlockingFlowByMKM G s t
+

Algorithm for given network G with source s and sink t, finds a blocking +flow, which can be used to obtain a maximum flow for that network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Result:
+

Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network G.

+
+

Note: Algorithm's complexity is O(n^2), where n is the number of nodes in flow network G.

+
struct::graph::op::createResidualGraph G f
+

Procedure creates a residual graph (or residual network ) for network G and given +flow f.

+
+
Arguments:
+
+
Graph Object G (input)
+

Flow network (directed graph where each edge has set attribute: throughput ).

+
dictionary f (input)
+

Current flows in flow network G.

+
+
Result:
+

Procedure returns graph structure that is a residual graph created from input flow +network G.

+
+
struct::graph::op::createAugmentingNetwork G f path
+

Procedure creates an augmenting network for a given residual network G +, flow f and augmenting path path.

+
+
Arguments:
+
+
Graph Object G (input)
+

Residual network (directed graph), where for every edge there are set two attributes: throughput and cost.

+
Dictionary f (input)
+

Dictionary which contains for every edge (key), current value of the flow on that edge.

+
List path (input)
+

Augmenting path, set of edges (list) for which we create the network modification.

+
+
Result:
+

Algorithm returns graph structure containing the modified augmenting network.

+
+
struct::graph::op::createLevelGraph Gf s
+

For given residual graph Gf procedure finds the level graph.

+
+
Arguments:
+
+
Graph Object Gf (input)
+

Residual network, where each edge has it's attribute throughput set with certain value.

+
Node s (input)
+

The source node for the residual network Gf.

+
+
Result:
+

Procedure returns a level graph created from input residual network.

+
+
struct::graph::op::TSPLocalSearching G C
+

Algorithm is a heuristic of local searching for Travelling Salesman Problem. For some +solution of TSP problem, it checks if it's possible to find a better solution. As TSP +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 2 approximation factor).

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected and complete graph with attributes "weight" set on each single edge.

+
List C (input)
+

A list of edges being Hamiltonian cycle, which is solution of TSP Problem for graph G.

+
+
Result:
+

Algorithm returns the best solution for TSP problem, it was able to find.

+
+

Note: The solution depends on the choosing of the beginning cycle C. It's not true that better cycle +assures that better solution will be found, but practise shows that we should give starting cycle with as small +sum of weights as possible.

+
struct::graph::op::TSPLocalSearching3Approx G C
+

Algorithm is a heuristic of local searching for Travelling Salesman Problem. For some +solution of TSP problem, it checks if it's possible to find a better solution. As TSP +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 3 approximation factor).

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected and complete graph with attributes "weight" set on each single edge.

+
List C (input)
+

A list of edges being Hamiltonian cycle, which is solution of TSP Problem for graph G.

+
+
Result:
+

Algorithm returns the best solution for TSP problem, it was able to find.

+
+

Note: In practise 3-approximation algorithm turns out to be far more effective than 2-approximation, but it gives +worser approximation factor. Further heuristics of local searching (e.g. 4-approximation) doesn't give enough boost to +square the increase of approximation factor, so 2 and 3 approximations are mainly used.

+
struct::graph::op::createSquaredGraph G
+

X-Squared graph is a graph with the same set of nodes as input graph G, but a different set of edges. X-Squared graph +has edge (u,v), if and only if, the distance between u and v nodes is not greater than X and u != v.

+

Procedure for input graph G, returns its two-squared graph.

+

Note: Distances used in choosing new set of edges are considering the number of edges, not the sum of weights at edges.

+
struct::graph::op::createCompleteGraph G originalEdges
+

For input graph G procedure adds missing arcs to make it a complete graph. It also holds in +variable originalEdges the set of arcs that graph G possessed before that operation.

+
+
+

Background theory and terms

+

Shortest Path Problem

+
+
Definition (single-pair shortest path problem):
+

Formally, given a weighted graph (let V be the set of vertices, and E a set of edges), +and one vertice v of V, find a path P from v to a v' of V so that +the sum of weights on edges along the path is minimal among all paths connecting v to v'.

+
Generalizations:
+
    +

  • The single-source shortest path problem, in which we have to find shortest paths from a source vertex v to all other vertices in the graph.

    • +

  • The single-destination shortest path problem, in which we have to find shortest paths from all vertices in the graph to a single destination vertex v. This can be reduced to the single-source shortest path problem by reversing the edges in the graph.

    • +

  • The all-pairs shortest path problem, in which we have to find shortest paths between every pair of vertices v, v' in the graph.

    • +
+

Note: +The result of Shortest Path problem can be Shortest Path tree, which is a subgraph of a given (possibly weighted) graph constructed so that the +distance between a selected root node and all other nodes is minimal. It is a tree because if there are two paths between the root node and some +vertex v (i.e. a cycle), we can delete the last edge of the longer path without increasing the distance from the root node to any node in the subgraph.

+
+
+

Travelling Salesman Problem

+
+
Definition:
+

For given edge-weighted (weights on edges should be positive) graph the goal is to find the cycle that visits each node in graph +exactly once (Hamiltonian cycle).

+
Generalizations:
+
    +

  • Metric TSP - A very natural restriction of the TSP is to require that the distances between cities form a metric, i.e., +they satisfy the triangle inequality. That is, for any 3 cities A, B and C, the distance between A and C +must be at most the distance from A to B plus the distance from B to C. Most natural instances of TSP +satisfy this constraint.

    • +

  • Euclidean TSP - Euclidean TSP, or planar TSP, is the TSP with the distance being the ordinary Euclidean distance. +Euclidean TSP is a particular case of TSP with triangle inequality, since distances in plane obey triangle inequality. However, +it seems to be easier than general TSP with triangle inequality. For example, the minimum spanning tree of the graph associated +with an instance of Euclidean TSP is a Euclidean minimum spanning tree, and so can be computed in expected O(n log n) time for +n points (considerably less than the number of edges). This enables the simple 2-approximation algorithm for TSP with triangle +inequality above to operate more quickly.

    • +

  • Asymmetric TSP - In most cases, the distance between two nodes in the TSP network is the same in both directions. +The case where the distance from A to B is not equal to the distance from B to A is called asymmetric TSP. +A practical application of an asymmetric TSP is route optimisation using street-level routing (asymmetric due to one-way streets, +slip-roads and motorways).

    • +
+
+
+

Matching Problem

+
+
Definition:
+

Given a graph G = (V,E), a matching or edge-independent set M in G is a set of pairwise non-adjacent edges, +that is, no two edges share a common vertex. A vertex is matched if it is incident to an edge in the matching M. +Otherwise the vertex is unmatched.

+
Generalizations:
+
    +

  • Maximal matching - a matching M of a graph G with the property that if any edge not in M is added to M, +it is no longer a matching, that is, M is maximal if it is not a proper subset of any other matching in graph G. +In other words, a matching M of a graph G is maximal if every edge in G has a non-empty intersection with at least one edge in M.

    • +

  • Maximum matching - a matching that contains the largest possible number of edges. There may be many maximum matchings. +The matching number of a graph G is the size of a maximum matching. Note that every maximum matching is maximal, +but not every maximal matching is a maximum matching.

    • +

  • Perfect matching - a matching which matches all vertices of the graph. That is, every vertex of the graph is incident to exactly one +edge of the matching. Every perfect matching is maximum and hence maximal. In some literature, the term complete matching +is used. A perfect matching is also a minimum-size edge cover. Moreover, the size of a maximum matching is no larger than the +size of a minimum edge cover.

    • +

  • Near-perfect matching - a matching in which exactly one vertex is unmatched. This can only occur when the graph has an odd number of vertices, +and such a matching must be maximum. If, for every vertex in a graph, there is a near-perfect matching that omits only that vertex, the graph +is also called factor-critical.

    • +
+
Related terms:
+
    +

  • Alternating path - given a matching M, an alternating path is a path in which the edges belong alternatively +to the matching and not to the matching.

    • +

  • Augmenting path - given a matching M, an augmenting path is an alternating path that starts from +and ends on free (unmatched) vertices.

    • +
+
+
+

Cut Problems

+
+
Definition:
+

A cut is a partition of the vertices of a graph into two disjoint subsets. The cut-set of the cut is the +set of edges whose end points are in different subsets of the partition. Edges are said to be crossing the cut if they are in its cut-set.

+

Formally:

+
    +

  • a cut C = (S,T) is a partition of V of a graph G = (V, E).

    • +

  • an s-t cut C = (S,T) of a flow network N = (V, E) is a cut of N such that s is included in S +and t is included in T, where s and t are the source and the sink of N respectively.

    • +

  • The cut-set of a cut C = (S,T) is such set of edges from graph G = (V, E) that each edge (u, v) satisfies +condition that u is included in S and v is included in T.

    • +
+

In an unweighted undirected graph, the size or weight of a cut is the number of edges crossing the cut. In a weighted graph, +the same term is defined by the sum of the weights of the edges crossing the cut.

+

In a flow network, an s-t cut is a cut that requires the source and the sink to be in different subsets, +and its cut-set only consists of edges going from the source's side to the sink's side. The capacity of an s-t cut +is defined by the sum of capacity of each edge in the cut-set.

+

The cut of a graph can sometimes refer to its cut-set instead of the partition.

+
Generalizations:
+
    +

  • Minimum cut - A cut is minimum if the size of the cut is not larger than the size of any other cut.

    • +

  • Maximum cut - A cut is maximum if the size of the cut is not smaller than the size of any other cut.

    • +

  • Sparsest cut - The Sparsest cut problem is to bipartition the vertices so as to minimize the ratio of the number +of edges across the cut divided by the number of vertices in the smaller half of the partition.

    • +
+
+
+

K-Center Problem

+
+
Definitions:
+
+
Unweighted K-Center
+

For any set S ( which is subset of V ) and node v, let the connect(v,S) be the +cost of cheapest edge connecting v with any node in S. The goal is to find +such S, that |S| = k and max_v{connect(v,S)} is possibly small.

+

In other words, we can use it i.e. for finding best locations in the city ( nodes +of input graph ) for placing k buildings, such that those buildings will be as close +as possible to all other locations in town.

+
Weighted K-Center
+

The variation of unweighted k-center problem. Besides the fact graph is edge-weighted, +there are also weights on vertices of input graph G. We've got also restriction +W. The goal is to choose such set of nodes S ( which is a subset of V ), that it's +total weight is not greater than W and also function: max_v { min_u { cost(u,v) }} +has the smallest possible worth ( v is a node in V and u is a node in S ).

+
+
+
+

Flow Problems

+
+
Definitions:
+
    +

  • the maximum flow problem - the goal is to find a feasible flow through a single-source, single-sink flow network that is maximum. +The maximum flow problem can be seen as a special case of more complex network flow problems, such as the circulation problem. +The maximum value of an s-t flow is equal to the minimum capacity of an s-t cut in the network, as stated in the +max-flow min-cut theorem.

    +

    More formally for flow network G = (V,E), where for each edge (u, v) we have its throuhgput c(u,v) defined. As flow +F we define set of non-negative integer attributes f(u,v) assigned to edges, satisfying such conditions:

    +
      +

    1. for each edge (u, v) in G such condition should be satisfied: 0 <= f(u,v) <= c(u,v)

      2. +

    2. Network G has source node s such that the flow F is equal to the sum of outcoming flow decreased by the sum of incoming flow from that source node s.

      3. +

    3. Network G has sink node t such that the the -F value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node t.

      4. +

    4. For each node that is not a source or sink the sum of incoming flow and sum of outcoming flow should be equal.

      5. +
    +
    • +

  • the minimum cost flow problem - the goal is finding the cheapest possible way of sending a certain amount of flow through a flow network.

    • +

  • blocking flow - a blocking flow for a residual network Gf we name such flow b in Gf that:

    +
      +

    1. Each path from sink to source is the shortest path in Gf.

      2. +

    2. Each shortest path in Gf contains an edge with fully used throughput in Gf+b.

      3. +
    +
    • +

  • residual network - for a flow network G and flow f residual network is built with those edges, which can +send larger flow. It contains only those edges, which can send flow larger than 0.

    • +

  • level network - it has the same set of nodes as residual graph, but has only those edges (u,v) from Gf +for which such equality is satisfied: distance(s,u)+1 = distance(s,v).

    • +

  • augmenting network - it is a modification of residual network considering the new +flow values. Structure stays unchanged but values of throughputs and costs at edges +are different.

    • +
+
+
+

Approximation algorithm

+
+
k-approximation algorithm:
+

Algorithm is a k-approximation, when for ALG (solution returned by algorithm) and +OPT (optimal solution), such inequality is true:

+
    +

  • for minimalization problems: ALG/OPT <= k

    • +

  • for maximalization problems: OPT/ALG <= k

    • +
+
+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/matrix.html Index: embedded/www/tcllib/files/modules/struct/matrix.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/matrix.html @@ -0,0 +1,556 @@ + + +struct::matrix - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::matrix(n) 2.0.1 tcllib "Tcl Data Structures"

+

Name

+

struct::matrix - Create and manipulate matrix objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require struct::matrix ?2.0.1?
    • +
+ +
+
+

Description

+

A matrix is a rectangular collection of cells, i.e. organized in rows +and columns. Each cell contains exactly one value of arbitrary +form. The cells in the matrix are addressed by pairs of integer +numbers, with the first (left) number in the pair specifying the +column and the second (right) number specifying the row the cell is +in. These indices are counted from 0 upward. The special non-numeric +index end refers to the last row or column in the matrix, +depending on the context. Indices of the form +end-number are counted from the end of the row or +column, like they are for standard Tcl lists. Trying to access +non-existing cells causes an error.

+

The matrices here are created empty, i.e. they have neither rows nor +columns. The user then has to add rows and columns as needed by his +application. A specialty of this structure is the ability to export an +array-view onto its contents. Such can be used by tkTable, for +example, to link the matrix into the display.

+

The main command of the package is:

+
+
::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
+

The command creates a new matrix object with an associated global Tcl +command whose name is matrixName. This command may be used to +invoke various operations on the matrix. It has the following general +form:

+
+
matrixName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If matrixName is not specified a unique name will be generated +by the package itself. If a source is specified the new matrix +will be initialized to it. For the operators =, :=, +and as the argument source is interpreted as the name of +another matrix object, and the assignment operator = will be +executed. For deserialize the source is a serialized +matrix object and deserialize will be executed.

+

In other words

+
+    ::struct::matrix mymatrix = b
+
+

is equivalent to

+
+    ::struct::matrix mymatrix
+    mymatrix = b
+
+

and

+
+    ::struct::matrix mymatrix deserialize $b
+
+

is equivalent to

+
+    ::struct::matrix mymatrix
+    mymatrix deserialize $b
+
+
+
+

The following commands are possible for matrix objects:

+
+
matrixName = sourcematrix
+

This is the assignment operator for matrix objects. It copies the matrix +contained in the matrix object sourcematrix over the matrix data in +matrixName. The old contents of matrixName are deleted by +this operation.

+

This operation is in effect equivalent to

+
+    matrixName deserialize [sourcematrix serialize]
+
+
+
matrixName --> destmatrix
+

This is the reverse assignment operator for matrix objects. It copies +the matrix contained in the matrix object matrixName over the matrix +data in the object destmatrix. +The old contents of destmatrix are deleted by this operation.

+

This operation is in effect equivalent to

+
+    destmatrix deserialize [matrixName serialize]
+
+
+
matrixName add column ?values?
+

Extends the matrix by one column and then acts like set column +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column.

+
matrixName add row ?values?
+

Extends the matrix by one row and then acts like set row (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row.

+
matrixName add columns n
+

Extends the matrix by n columns. The new cells will be set to +the empty string. The new columns are appended immediately behind the +last existing column. A value of n equal to or smaller than 0 is +not allowed.

+
matrixName add rows n
+

Extends the matrix by n rows. The new cells will be set to the +empty string. The new rows are appended immediately behind the last +existing row. A value of n equal to or smaller than 0 is not +allowed.

+
matrixName cells
+

Returns the number of cells currently managed by the matrix. This is +the product of rows and columns.

+
matrixName cellsize column row
+

Returns the length of the string representation of the value currently +contained in the addressed cell.

+
matrixName columns
+

Returns the number of columns currently managed by the matrix.

+
matrixName columnwidth column
+

Returns the length of the longest string representation of all the +values currently contained in the cells of the addressed column if +these are all spanning only one line. For cell values spanning +multiple lines the length of their longest line goes into the +computation.

+
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 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 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 getrect 0 0 4 4
+ {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
+
+
+ % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
+ % M getrect 0 0 4 4
+ {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
+
+

Assuming that the style definitions in the example section of the +manpage for the package report are loaded into the +interpreter now an example which formats a matrix into a tabular +report. The code filling the matrix with data is not shown. contains +useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % m format 2string r
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % r printmatrix m
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: matrix of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/matrix1.html Index: embedded/www/tcllib/files/modules/struct/matrix1.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/matrix1.html @@ -0,0 +1,447 @@ + + +struct::matrix_v1 - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::matrix_v1 - Create and manipulate matrix objects

+
+ + +

Description

+

The ::struct::matrix command creates a new matrix object with an +associated global Tcl command whose name is matrixName. This +command may be used to invoke various operations on the matrix. It has +the following general form:

+
+
matrixName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A matrix is a rectangular collection of cells, i.e. organized in rows +and columns. Each cell contains exactly one value of arbitrary +form. The cells in the matrix are addressed by pairs of integer +numbers, with the first (left) number in the pair specifying the +column and the second (right) number specifying the row the cell is +in. These indices are counted from 0 upward. The special non-numeric +index end refers to the last row or column in the matrix, +depending on the context. Indices of the form +end-number are counted from the end of the row or +column, like they are for standard Tcl lists. Trying to access +non-existing cells causes an error.

+

The matrices here are created empty, i.e. they have neither rows nor +columns. The user then has to add rows and columns as needed by his +application. A specialty of this structure is the ability to export an +array-view onto its contents. Such can be used by tkTable, for +example, to link the matrix into the display.

+

The following commands are possible for matrix objects:

+
+
matrixName add column ?values?
+

Extends the matrix by one column and then acts like setcolumn +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column.

+
matrixName add row ?values?
+

Extends the matrix by one row and then acts like setrow (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row.

+
matrixName add columns n
+

Extends the matrix by n columns. The new cells will be set to +the empty string. The new columns are appended immediately behind the +last existing column. A value of n equal to or smaller than 0 is +not allowed.

+
matrixName add rows n
+

Extends the matrix by n rows. The new cells will be set to the +empty string. The new rows are appended immediately behind the last +existing row. A value of n equal to or smaller than 0 is not +allowed.

+
matrixName cells
+

Returns the number of cells currently managed by the matrix. This is +the product of rows and columns.

+
matrixName cellsize column row
+

Returns the length of the string representation of the value currently +contained in the addressed cell.

+
matrixName columns
+

Returns the number of columns currently managed by the matrix.

+
matrixName columnwidth column
+

Returns the length of the longest string representation of all the +values currently contained in the cells of the addressed column if +these are all spanning only one line. For cell values spanning +multiple lines the length of their longest line goes into the +computation.

+
matrixName delete column column
+

Deletes the specified column from the matrix and shifts all columns +with higher indices one index down.

+
matrixName delete row row
+

Deletes the specified row from the matrix and shifts all row with +higher indices one index down.

+
matrixName destroy
+

Destroys the matrix, including its storage space and associated +command.

+
matrixName format 2string ?report?
+

Formats the matrix using the specified report object and returns the +string containing the result of this operation. The report has to +support the printmatrix method. If no report is +specified the system will use an internal report definition to format +the matrix.

+
matrixName format 2chan ??report? channel?
+

Formats the matrix using the specified report object and writes the +string containing the result of this operation into the channel. The +report has to support the printmatrix2channel method. If no +report is specified the system will use an internal report +definition to format the matrix. If no channel is specified the +system will use stdout.

+
matrixName get cell column row
+

Returns the value currently contained in the cell identified by row +and column index.

+
matrixName get column column
+

Returns a list containing the values from all cells in the column +identified by the index. The contents of the cell in row 0 are stored +as the first element of this list.

+
matrixName get rect column_tl row_tl column_br row_br
+

Returns a list of lists of cell values. The values stored in the +result come from the sub-matrix whose top-left and bottom-right cells +are specified by column_tl, row_tl and +column_br, row_br resp. Note that the following equations have +to be true: "column_tl <= column_br" and "row_tl <= +row_br". The result is organized as follows: The outer list is +the list of rows, its elements are lists representing a single +row. The row with the smallest index is the first element of the outer +list. The elements of the row lists represent the selected cell +values. The cell with the smallest index is the first element in each +row list.

+
matrixName get row row
+

Returns a list containing the values from all cells in the row +identified by the index. The contents of the cell in column 0 are +stored as the first element of this list.

+
matrixName insert column column ?values?
+

Extends the matrix by one column and then acts like setcolumn +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is inserted just before the column specified by +the given index. This means, if column is less than or equal to +zero, then the new column is inserted at the beginning of the matrix, +before the first column. If column has the value end, +or if it is greater than or equal to the number of columns in the +matrix, then the new column is appended to the matrix, behind the last +column. The old column at the chosen index and all columns with higher +indices are shifted one index upward.

+
matrixName insert row row ?values?
+

Extends the matrix by one row and then acts like setrow (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is inserted just before the row specified by the given index. This +means, if row is less than or equal to zero, then the new row is +inserted at the beginning of the matrix, before the first row. If +row has the value end, or if it is greater than or +equal to the number of rows in the matrix, then the new row is +appended to the matrix, behind the last row. The old row at that index +and all rows with higher indices are shifted one index upward.

+
matrixName link ?-transpose? arrayvar
+

Links the matrix to the specified array variable. This means that the +contents of all cells in the matrix is stored in the array too, with +all changes to the matrix propagated there too. The contents of the +cell (column,row) is stored in the array using the key +column,row. If the option -transpose is specified the +key row,column will be used instead. It is possible to link the +matrix to more than one array. Note that the link is bidirectional, +i.e. changes to the array are mirrored in the matrix too.

+
matrixName links
+

Returns a list containing the names of all array variables the matrix +was linked to through a call to method link.

+
matrixName rowheight row
+

Returns the height of the specified row in lines. This is the highest +number of lines spanned by a cell over all cells in the row.

+
matrixName rows
+

Returns the number of rows currently managed by the matrix.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
+

Searches the whole matrix for cells matching the pattern and +returns a list with all matches. Each item in the aforementioned list +is a list itself and contains the column and row index of the matching +cell, in this order. The results are ordered by column first and row +second, both times in ascending order. This means that matches to the +left and the top of the matrix come before matches to the right and +down.

+

The type of the pattern (string, glob, regular expression) is +determined by the option after the search keyword. If no +option is given it defaults to -exact.

+

If the option -nocase is specified the search will be +case-insensitive.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern
+

Like search all, but the search is restricted to the +specified column.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
+

Like search all, but the search is restricted to the +specified row.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern
+

Like search all, but the search is restricted to the +specified rectangular area of the matrix.

+
matrixName set cell column row value
+

Sets the value in the cell identified by row and column index to the +data in the third argument.

+
matrixName set column column values
+

Sets the values in the cells identified by the column index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in row 0 and then upward. If there are less values in the +list than there are rows the remaining rows are set to the empty +string. If there are more values in the list than there are rows the +superfluous elements are ignored. The matrix is not extended by this +operation.

+
matrixName set rect column row values
+

Takes a list of lists of cell values and writes them into the +submatrix whose top-left cell is specified by the two indices. If the +sublists of the outerlist are not of equal length the shorter sublists +will be filled with empty strings to the length of the longest +sublist. If the submatrix specified by the top-left cell and the +number of rows and columns in the values extends beyond the +matrix we are modifying the over-extending parts of the values are +ignored, i.e. essentially cut off. This subcommand expects its input +in the format as returned by getrect.

+
matrixName set row row values
+

Sets the values in the cells identified by the row index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in column 0 and then upward. If there are less values in the +list than there are columns the remaining columns are set to the empty +string. If there are more values in the list than there are columns +the superfluous elements are ignored. The matrix is not extended by +this operation.

+
matrixName sort columns ?-increasing|-decreasing? row
+

Sorts the columns in the matrix using the data in the specified +row as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName sort rows ?-increasing|-decreasing? column
+

Sorts the rows in the matrix using the data in the specified +column as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName swap columns column_a column_b
+

Swaps the contents of the two specified columns.

+
matrixName swap rows row_a row_b
+

Swaps the contents of the two specified rows.

+
matrixName unlink arrayvar
+

Removes the link between the matrix and the specified arrayvariable, +if there is one.

+
+
+

EXAMPLES

+

The examples below assume a 5x5 matrix M with the first row containing +the values 1 to 5, with 1 in the top-left cell. Each other row +contains the contents of the row above it, rotated by one cell to the +right.

+
+ % M getrect 0 0 4 4
+ {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
+
+
+ % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
+ % M getrect 0 0 4 4
+ {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
+
+

Assuming that the style definitions in the example section of the +manpage for the package report are loaded into the +interpreter now an example which formats a matrix into a tabular +report. The code filling the matrix with data is not shown. contains +useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % m format 2string r
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % r printmatrix m
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: matrix of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/pool.html Index: embedded/www/tcllib/files/modules/struct/pool.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/pool.html @@ -0,0 +1,457 @@ + + +struct::pool - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::pool(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::pool - Create and manipulate pool objects (of discrete items)

+
+ + +

Description

+

This package provides pool objects which can be used to manage +finite collections of discrete items.

+
+
::struct::pool ?poolName? ?maxsize?
+

Creates a new pool object. If no poolName is supplied, then the +new pool will be named poolX, where X is a positive integer. +The optional second argument maxsize has to be a positive +integer indicating the maximum size of the pool; this is the maximum +number of items the pool may hold. The default for this value is +10.

+

The pool object has an associated global Tcl command whose name is +poolName. This command may be used to invoke various +configuration operations on the report. It has the following general +form:

+
+
poolName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section POOL OBJECT COMMAND for a detailed +list of options and their behaviour.

+
+
+
+

POOLS AND ALLOCATION

+

The purpose of the pool command and the pool object command that it +generates, is to manage pools of discrete items. + +Examples of a pool of discrete items are:

+
    +

  • the seats in a cinema, theatre, train etc.. for which visitors/travelers can make a reservation;

    • +

  • the dynamic IP-addresses that an ISP can dole out to subscribers;

    • +

  • a car rental's collection of cars, which can be rented by customers;

    • +

  • the class rooms in a school building, which need to be scheduled;

    • +

  • the database connections available to client-threads in a web-server application;

    • +

  • the books in a library that customers can borrow;

    • +

  • etc ...

    • +
+

The common denominator in the examples is that there is a more or less +fixed number of items (seats, IP-addresses, cars, ...) that are +supposed to be allocated on a more or less regular basis. An item can +be allocated only once at a time. An item that is allocated, must be +released before it can be re-allocated. While several items in a pool +are being allocated and released continuously, the total number of +items in the pool remains constant.

+

Keeping track of which items are allocated, and by whom, is the +purpose of the pool command and its subordinates.

+

Pool parlance: If we say that an item is +allocated, it means that the item is busy, +owned or occupied; it is not available anymore. If +an item is free, it is available. Deallocating an +item is equivalent to setting free or releasing an item. The person or +entity to which the item has been allotted is said to own the item.

+
+

ITEMS

+

Discrete items

+

The pool command is designed for +discrete items only. Note that there are pools where +allocation occurs on a non-discrete basis, for example computer +memory. There are also pools from which the shares that are doled out +are not expected to be returned, for example a charity fund or a pan +of soup from which you may receive a portion. Finally, there are even +pools from which nothing is ever allocated or returned, like a +swimming pool or a cesspool.

+

Unique item names

+

A pool cannot manage duplicate item names. Therefore, items in a pool +must have unique names.

+

Item equivalence

+

From the point of view of the manager of a pool, items are +equivalent. The manager of a pool is indifferent about which +entity/person occupies a given item. However, clients may have +preferences for a particular item, based on some item property they +know.

+

Preferences

+

A future owner may have a preference for a particular item. Preference +based allocation is supported (see the -prefer option to the +request subcommand). A preference for a particular item is most likely +to result from variability among features associated with the +items. Note that the pool commands themselves are not designed to +manage such item properties. If item properties play a role in an +application, they should be managed separately.

+
+

POOL OBJECT COMMAND

+

The following subcommands and corresponding arguments are available to +any pool object command.

+
+ +
poolName add itemName1 ?itemName2 itemName3 ...?
+

This command adds the items on the command line to the pool. If +duplicate item names occur on the command line, an error is raised. If +one or more of the items already exist in the pool, this also is +considered an error.

+
poolName clear ?-force?
+

Removes all items from the pool. If there are any allocated items at +the time when the command is invoked, an error is raised. This +behaviour may be modified through the -force argument. If it +is supplied on the command line, the pool will be cleared regardless +the allocation state of its items.

+
poolName destroy ?-force?
+

Destroys the pool data structure, all associated variables and the +associated pool object command. By default, the command checks whether +any items are still allocated and raises an error if such is the +case. This behaviour may be modified through the argument +-force. If it is supplied on the command line, the pool data +structure will be destroyed regardless allocation state of its items.

+
poolName info type ?arg?
+

Returns various information about the pool for further programmatic +use. The type argument indicates the type of information +requested. Only the type allocID uses an additional argument.

+
+ +
allocID itemName
+

returns the allocID of the item whose name is itemName. Free +items have an allocation id of -1.

+
allitems
+

returns a list of all items in the pool.

+
allocstate
+

Returns a list of key-value pairs, where the keys are the items and +the values are the corresponding allocation id's. Free items have an +allocation id of -1.

+
cursize
+

returns the current pool size, i.e. the number of items in the pool.

+
freeitems
+

returns a list of items that currently are not allocated.

+
maxsize
+

returns the maximum size of the pool.

+
+
poolName maxsize ?maxsize?
+

Sets or queries the maximum size of the pool, depending on whether the +maxsize argument is supplied or not. If maxsize is +supplied, the maximum size of the pool will be set to that value. If +no argument is supplied, the current maximum size of the pool is +returned. In this variant, the command is an alias for:

+

poolName info maxsize.

+

The maxsize argument has to be a positive integer.

+
poolName release itemName
+

Releases the item whose name is itemName that was allocated +previously. An error is raised if the item was not allocated at the +time when the command was issued.

+
poolName remove itemName ?-force?
+

Removes the item whose name is itemName from the pool. If the +item was allocated at the time when the command was invoked, an error +is raised. This behaviour may be modified through the optional +argument -force. If it is supplied on the command line, the +item will be removed regardless its allocation state.

+
poolName request itemVar ?options?
+

Handles a request for an item, taking into account a possible +preference for a particular item. There are two possible outcomes +depending on the availability of items:

+
    +

  1. The request is honoured, an item is allocated and the variable whose +name is passed with the argument itemVar will be set to the name +of the item that was allocated. The command returns 1.

    2. +

  2. The request is denied. No item is allocated. The variable whose name +is itemVar is not set. Attempts to read itemVar may raise an +error if the variable was not defined before issuing the request. The +command returns 0.

    3. +
+

The return values from this command are meant to be inspected. The +examples below show how to do this. Failure to check the return value +may result in erroneous behaviour. If no preference for a particular +item is supplied through the option -prefer (see below), then +all requests are honoured as long as items are available.

+

The following options are supported:

+
+ +
-allocID allocID
+

If the request is honoured, an item will be allocated to the entity +identified by allocID. If the allocation state of an item is queried, +it is this allocation ID that will be returned. If the option +-allocID is not supplied, the item will be given to and owned +by dummyID. Allocation id's may be anything except the value +-1, which is reserved for free items.

+
-prefer preferredItem
+

This option modifies the allocation strategy as follows: If the item +whose name is preferredItem is not allocated at the time when +the command is invoked, the request is honoured (return value is +1). If the item was allocated at the time when the command was +invoked, the request is denied (return value is 0).

+
+
+
+

EXAMPLES

+

Two examples are provided. The first one mimics a step by step +interactive tclsh session, where each step is explained. The second +example shows the usage in a server application that talks to a +back-end application.

+

Example 1

+

This example presents an interactive tclsh session which considers the +case of a Car rental's collection of cars. Ten steps explain its usage +in chronological order, from the creation of the pool, via the most +important stages in the usage of a pool, to the final destruction.

+

Note aside:

+

In this example, brand names are used to label the various +items. However, a brand name could be regarded as a property of an +item. Because the pool command is not designed to manage properties of +items, they need to be managed separately. In the latter case the +items should be labeled with more neutral names such as: car1, car2, +car3 , etc ... and a separate database or array should hold the brand +names associated with the car labels.

+
      
+     1. Load the package into an interpreter
+     % package require pool
+     0.1
+      
+     2. Create a pool object called `CarPool' with a maximum size of 55 items (cars):
+     % pool CarPool 55
+     CarPool
+      
+     4. Add items to the pool:
+     % CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
+                   
+     5. Somebody crashed the Toyota. Remove it from the pool as follows:
+     % CarPool remove Toyota
+      
+     6. Acquired a new car for the pool. Add it as follows:
+     % CarPool add Nissan
+      
+     7. Check whether the pool was adjusted correctly:
+     % CarPool info allitems
+     Trabant Chrysler1 Chrysler2 Volkswagen Nissan
+
+

Suspend the interactive session temporarily, and show the programmatic +use of the request subcommand:

+
     
+     # Mrs. Swift needs a car. She doesn't have a preference for a
+     # particular car. We'll issue a request on her behalf as follows:
+     if { [CarPool request car -allocID "Mrs. Swift"] }  {
+         # request was honoured, process the variable `car'
+         puts "$car has been allocated to [CarPool info allocID $car]."
+     } else {
+         # request was denied
+          puts "No car available."
+     }
+
+

Note how the if command uses the value returned by the +request subcommand.

+
      
+     # Suppose Mr. Wiggly has a preference for the Trabant:
+     if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] }  {
+         # request was honoured, process the variable `car'
+         puts "$car has been allocated to [CarPool info allocID $car]."
+     } else {
+         # request was denied
+          puts "The Trabant was not available."
+     }
+
+

Resume the interactive session:

+
+     8. When the car is returned then you can render it available by:
+     % CarPool release Trabant
+      
+     9. When done, you delete the pool.
+     % CarPool destroy
+     Couldn't destroy `CarPool' because some items are still allocated.
+      
+     Oops, forgot that Mrs. Swift still occupies a car.
+      
+     10. We force the destruction of the pool as follows: 
+     % CarPool destroy -force
+
+

Example 2

+

This example describes the case from which the author's need for pool +management originated. It is an example of a server application that +receives requests from client applications. The client requests are +dispatched onto a back-end application before being returned to the +client application. In many cases there are a few equivalent instances +of back-end applications to which a client request may be passed +along. The file descriptors that identify the channels to these +back-end instances make up a pool of connections. A particular +connection may be allocated to just one client request at a time.

+
 
+     # Create the pool of connections (pipes)
+     set maxpipes 10
+     pool Pipes $maxpipes
+     for {set i 0} {$i < $maxpipes} {incr i} {
+         set fd [open "|backendApplication" w+]
+         Pipes add $fd
+     }
+      
+     # A client request comes in. The request is identified as `clientX'.
+     # Dispatch it onto an instance of a back-end application
+     if { [Pipes request fd -allocID clientX] } {
+         # a connection was allocated
+         # communicate to the back-end application via the variable `fd'
+         puts $fd "someInstruction"
+         # ...... etc.
+     } else {
+         # all connections are currently occupied
+         # store the client request in a queue for later processing,
+         # or return a 'Server busy' message to the client.
+     }
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: pool of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/prioqueue.html Index: embedded/www/tcllib/files/modules/struct/prioqueue.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/prioqueue.html @@ -0,0 +1,221 @@ + +struct::prioqueue - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::prioqueue(n) 1.4 tcllib "Tcl Data Structures"

+

Name

+

struct::prioqueue - Create and manipulate prioqueue objects

+
+ + +

Description

+

This package implements a simple priority queue using nested tcl lists.

+

The command ::struct::prioqueue creates a new priority queue +with default priority key type -integer. This means that keys +given to the put subcommand must have this type.

+

This also sets the priority ordering. For key types -ascii and +-dictionary the data is sorted in ascending order (as with +lsort -increasing), thereas for -integer and +-real the data is sorted in descending order (as with +lsort -decreasing).

+

Prioqueue names are unrestricted, but may be recognized as options if +no priority type is given.

+
+
::struct::prioqueue ?-ascii|-dictionary|-integer|-real? ?prioqueueName?
+

The ::struct::prioqueue command creates a new prioqueue object +with an associated global Tcl command whose name is +prioqueueName. This command may be used to invoke various +operations on the prioqueue. It has the following general form:

+
prioqueueName option ?arg arg ...?
+

option and the args determine the exact behavior of the +command. The following commands are possible for prioqueue objects:

+
prioqueueName clear
+

Remove all items from the prioqueue.

+
prioqueueName remove item
+

Remove the selected item from this priority queue.

+
prioqueueName destroy
+

Destroy the prioqueue, including its storage space and associated +command.

+
prioqueueName get ?count?
+

Return the front count items of the prioqueue (but not their +priorities) and remove them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the prioqueue, this command will throw an +error.

+
prioqueueName peek ?count?
+

Return the front count items of the prioqueue (but not their +priorities), without removing them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the queue, this command will throw an +error.

+
prioqueueName peekpriority ?count?
+

Return the front count items priority keys, without removing +them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the queue, this command will throw an +error.

+
prioqueueName put item prio ?item prio ...?
+

Put the item or items specified into the prioqueue. prio +must be a valid priority key for this type of prioqueue, otherwise an +error is thrown and no item is added. Items are inserted at their +priority ranking. Items with equal priority are added in the order +they were added.

+
prioqueueName size
+

Return the number of items in the prioqueue.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: prioqueue of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/queue.html Index: embedded/www/tcllib/files/modules/struct/queue.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/queue.html @@ -0,0 +1,198 @@ + + +struct::queue - Tcl Data Structures + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::queue(n) 1.4.4 tcllib "Tcl Data Structures"

+

Name

+

struct::queue - Create and manipulate queue objects

+
+ + +

Description

+

The ::struct namespace contains a commands for processing +finite queues.

+

It exports a single command, ::struct::queue. All functionality +provided here can be reached through a subcommand of this command.

+

Note: As of version 1.4.1 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+

The ::struct::queue command creates a new queue object with an +associated global Tcl command whose name is queueName. This +command may be used to invoke various operations on the queue. It has +the following general form:

+
+
queueName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. The following commands are possible for queue objects:

+
queueName clear
+

Remove all items from the queue.

+
queueName destroy
+

Destroy the queue, including its storage space and associated command.

+
queueName get ?count?
+

Return the front count items of the queue and remove them from +the queue. If count is not specified, it defaults to 1. If +count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enough items in the queue to fulfull the request, +this command will throw an error.

+
queueName peek ?count?
+

Return the front count items of the queue, without removing them +from the queue. If count is not specified, it defaults to 1. +If count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enough items in the queue to fulfull the request, +this command will throw an error.

+
queueName put item ?item ...?
+

Put the item or items specified into the queue. If more than +one item is given, they will be added in the order they are +listed.

+
queueName unget item
+

Put the item into the queue, at the front, i.e. before any other +items already in the queue. This makes this operation the complement +to the method get.

+
queueName size
+

Return the number of items in the queue.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: queue of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/record.html Index: embedded/www/tcllib/files/modules/struct/record.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/record.html @@ -0,0 +1,431 @@ + + +struct::record - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::record(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::record - Define and create records (similar to 'C' structures)

+
+ + +

Description

+

The ::struct::record package provides a mechanism to group variables together +as one data structure, similar to a 'C' structure. The members of a +record can be variables or other records. However, a record can not contain circular +record, i.e. records that contain the same record as a +member.

+

This package was structured so that it is very similar to how Tk objects work. Each record +definition creates a record object that encompasses that definition. Subsequently, that +record object can create instances of that record. These instances can then +be manipulated with the cget and configure methods.

+

The package only contains one top level command, but several sub commands (see below). It also obeys the namespace in which the record was define, hence the objects returned are fully qualified.

+
+
record define recordName recordMembers ?instanceName1 instanceName2 ...?
+

Defines a record. recordName is the name of the record, and is also +used as an object command. This object command is used to create instances of the +record definition. recordMembers are the members of +the record that make up the record definition. These are variables +and other record. If optional instanceName args are given, then an instance +is generated after the definition is created for each instanceName.

+
record show record
+

Returns a list of records that have been defined.

+
record show instances recordName
+

Returns the instances that have been instantiated by +recordName.

+
record show members recordName
+

Returns the members that are defined for +record recordName. It returns the same format as how the +records were defined.

+
record show values instanceName
+

Returns a list of values that are set for the instance +instanceName. The output is a list of key/value pairs. If there +are nested records, then the values of the nested records will +itself be a list.

+
record exists record recordName
+

Tests for the existence of a record with the +name recordName.

+
record exists instance instanceName
+

Tests for the existence of a instance with the +name instanceName.

+
record delete record recordName
+

Deletes recordName, and all instances of recordName. It will return +an error if the record does not exist.

+
record delete instance instanceName
+

Deletes instance with the name of instanceName. It +will return an error if the instance does not exist.

+
+
+

RECORD MEMBERS

+

Record members can either be variables, or other records, However, the +same record can not be nested witin itself (circular). To define a +nested record, you need to specify the record keyword, along +the with name of the record, and the name of the instance of that +nested record. For example, it would look like this:

+
+# this is the nested record
+record define mynestedrecord {
+    nest1
+    nest2
+}
+# This is the main record
+record define myrecord {
+    mem1
+    mem2
+    {record mynestedrecord mem3}
+}
+
+

You can also assign default or initial values to the members of a record, +by enclosing the member entry in braces:

+
+record define myrecord {
+    mem1
+    {mem2 5}
+}
+
+

All instances created from this record definition, will initially have 5 as +the value for mem2. If no default is given, then the value will be the empty string.

+

Getting Values

+

To get a value of a member, there are several ways to do this.

+
    +

  1. To get a member value, then use the instance built-in cget method:

    +

    instanceName cget -mem1

    2. +

  2. To get multiple member values, you can specify them all in one command:

    +

    instanceName cget -mem1 -mem2

    3. +

  3. To get a list of the key/value of all of the members, there are 3 ways:

    +

    - instanceName cget

    +

    - instanceName configure

    +

    - instanceName

    4. +

  4. To get a value of a nested member, then use the dot notation:

    +

    instanceName cget -mem3.nest1

    5. +
+

Setting Values

+

To set a value of a member, there are several ways to do this.

+
    +

  1. To set a member value, then use the instance built-in configure method:

    +

    instanceName configure -mem1 val1

    2. +

  2. To set multiple member values, you can specify them all in one command:

    +

    instanceName configure -mem1 va1 -mem2 val2

    3. +

  3. To set a value of a nested member, then use the dot notation:

    +

    instanceName configure -mem3.nest1 value

    4. +
+

Alias access

+

In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However, +there was a concensus to make the interface more Tcl like, which made sense. However, the original alias access still +exists. It might prove to be helpful to some.

+

Basically, for every member of every instance, an alias is created. This alias is used to get and set values for that +member. An example will illustrate the point, using the above defined records:

+
+# Create an instance first
+% myrecord inst1
+::inst1
+% # To get a member of an instance, just use the 
+% # alias (it behaves like a Tcl command):
+% inst1.mem1
+%
+% # To set a member via the alias, just include 
+% # a value (optionally the equal sign - syntactic sugar)
+% inst1.mem1 = 5
+5
+% inst1.mem1
+5
+% # For nested records, just continue with the 
+% # dot notation (note no equal sign)
+% inst1.mem3.nest1 10
+10
+% inst1.mem3.nest1
+10
+% # just the instance by itself gives all 
+% # member/values pairs for that instance
+% inst1
+-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
+% # and to get all members within the nested record
+% inst1.mem3
+-nest1 10 -nest2 {}
+%
+
+
+

RECORD COMMAND

+

The following subcommands and corresponding arguments are available to any +record command:

+
+
recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
+

Using the recordName object command that was created from the record definition, +instances of the record definition can be created. Once a instance is +created, then it inherits the members of the record definition, very +similar to how objects work. During instance generation, an object command for the instance +is created as well, using instanceName. This object command is used +to access the data members of the instance. During the instantiation, values for +that instance can be given, but all values must be given, and be given +in key/value pairs. Nested records, need to be in list format.

+

Optionally, #auto can be used in place of instanceName. When #auto is used, +then a instance name will automatically be generated, of the form recordName<integer>, where +<integer> is a unique integer (starting at 0) that is generated.

+
+
+

INSTANCE COMMAND

+

The following subcommands and corresponding arguments are available to +any record instance command:

+
+ +
instanceName cget ?-member1 -member2 ...?
+

Each instance has the sub command cget associated with it. This +is very similar to how Tk widget's cget command works. It queries +the values of the member for that particular instance. If +no arguments are given, then a key/value list is returned.

+
instanceName configure ?-member1 value1 -member2 value2 ...?
+

Each instance has the sub command configure associated with it. This +is very similar to how Tk widget's configure command works. It sets +the values of the particular member for that particular instance. If +no arguments are given, then a key/value list is returned.

+
+
+

EXAMPLES

+

Two examples are provided to give an good illustration on how to use +this package.

+

Example 1

+

Probably the most obvious example would be to hold contact information, +such as addresses, phone numbers, comments, etc. Since a person can have +multiple phone numbers, multiple email addresses, etc, we will use nested +records to define these. So, the first thing we do is define the nested +records:

+
+##
+##  This is an interactive example, to see what is 
+##  returned by each command as well.
+##
+% namespace import ::struct::record::*
+% # define a nested record. Notice that country has default 'USA'.
+% record define locations {
+    street
+    street2
+    city
+    state
+    zipcode
+    {country USA}
+    phone
+}
+::locations
+% # Define the main record. Notice that it uses the location record twice.
+% record define contacts {
+    first 
+    middle 
+    last 
+    {record locations home}
+    {record locations work}
+}
+::contacts
+% # Create an instance for the contacts record.
+% contacts cont1
+::cont1
+% # Display some introspection values
+% record show records
+::contacts ::locations
+% #
+% record show values cont1
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% #
+% record show instances contacts
+::cont1
+% #
+% cont1 config
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% #
+% cont1 cget
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% # copy one record to another record
+% record define contacts2 [record show members contacts]
+::contacts2
+% record show members contacts2
+first middle last {record locations home} {record locations work}
+% record show members contacts
+first middle last {record locations home} {record locations work}
+%
+
+

Example 1

+

This next example just illustrates a simple linked list

+
+% # define a very simple record for linked list
+% record define llist {
+    value
+    next
+}
+::llist
+% llist lstart
+::lstart
+% lstart config -value 1 -next [llist #auto]
+% [lstart cget -next] config -value 2 -next [llist #auto]
+% [[lstart cget -next] cget -next] config -value 3 -next "end"
+% set next lstart
+lstart
+% while 1 {
+lappend values [$next cget -value]
+set next [$next cget -next]
+if {[string match "end" $next]} {break}
+}
+% puts "$values"
+1 2 3
+% # cleanup linked list
+% # We could just use delete record llist also
+% foreach I [record show instances llist] {
+record delete instance $I
+}
+% record show instances llist
+%
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: record of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/skiplist.html Index: embedded/www/tcllib/files/modules/struct/skiplist.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/skiplist.html @@ -0,0 +1,199 @@ + + +struct::skiplist - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::skiplist(n) 1.3 tcllib "Tcl Data Structures"

+

Name

+

struct::skiplist - Create and manipulate skiplists

+
+ + +

Description

+

The ::struct::skiplist command creates a new skiplist object +with an associated global Tcl command whose name is +skiplistName. This command may be used to invoke various +operations on the skiplist. It has the following general form:

+
+
skiplistName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

Skip lists are an alternative data structure to binary trees. They can +be used to maintain ordered lists over any sequence of insertions and +deletions. Skip lists use randomness to achieve probabilistic +balancing, and as a result the algorithms for insertion and deletion +in skip lists are much simpler and faster than those for binary trees.

+

To read more about skip lists see Pugh, William. +Skip lists: a probabilistic alternative to balanced trees +In: Communications of the ACM, June 1990, 33(6) 668-676.

+

Currently, the key can be either a number or a string, and comparisons +are performed with the built in greater than operator. +The following commands are possible for skiplist objects:

+
+
skiplistName delete node ?node...?
+

Remove the specified nodes from the skiplist.

+
skiplistName destroy
+

Destroy the skiplist, including its storage space and associated command.

+
skiplistName insert key value
+

Insert a node with the given key and value into the +skiplist. If a node with that key already exists, then the that node's +value is updated and its node level is returned. Otherwise a new node +is created and 0 is returned.

+
skiplistName search node ?-key key?
+

Search for a given key in a skiplist. If not found then 0 is returned. +If found, then a two element list of 1 followed by the node's value is retuned.

+
skiplistName size
+

Return a count of the number of nodes in the skiplist.

+
skiplistName walk cmd
+

Walk the skiplist from the first node to the last. At each node, the +command cmd will be evaluated with the key and value of the +current node appended.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: skiplist of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/stack.html Index: embedded/www/tcllib/files/modules/struct/stack.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/stack.html @@ -0,0 +1,212 @@ + +struct::stack - Tcl Data Structures + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::stack(n) 1.5.3 tcllib "Tcl Data Structures"

+

Name

+

struct::stack - Create and manipulate stack objects

+
+ + +

Description

+

The ::struct namespace contains a commands for processing +finite stacks.

+

It exports a single command, ::struct::stack. All functionality +provided here can be reached through a subcommand of this command.

+

Note: As of version 1.3.3 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+

The ::struct::stack command creates a new stack object with an +associated global Tcl command whose name is stackName. This +command may be used to invoke various operations on the stack. It has +the following general form:

+
+
stackName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. The following commands are possible for stack objects:

+
stackName clear
+

Remove all items from the stack.

+
stackName destroy
+

Destroy the stack, including its storage space and associated command.

+
stackName get
+

Returns the whole contents of the stack as a list, without removing +them from the stack.

+
stackName getr
+

A variant of get, which returns the contents in reversed order.

+
stackName peek ?count?
+

Return the top count items of the stack, without removing them from +the stack. If count is not specified, it defaults to 1. If +count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enoughs items on the stack to fulfull the request, +this command will throw an error.

+
stackName peekr ?count?
+

A variant of peek, which returns the items in reversed order.

+
stackName trim ?newsize?
+

Shrinks the stack to contain at most newsize elements and +returns a list containing the elements which were removed. Nothing is +done if the stack is already at the specified size, or smaller. In +that case the result is the empty list.

+
stackName trim* ?newsize?
+

A variant of trim which performs the shrinking, but does not +return the removed elements.

+
stackName pop ?count?
+

Return the top count items of the stack, and remove them +from the stack. If count is not specified, it defaults to 1. +If count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enoughs items on the stack to fulfull the request, +this command will throw an error.

+
stackName push item ?item...?
+

Push the item or items specified onto the stack. If more than +one item is given, they will be pushed in the order they are +listed.

+
stackName size
+

Return the number of items on the stack.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: stack of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/struct_list.html Index: embedded/www/tcllib/files/modules/struct/struct_list.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/struct_list.html @@ -0,0 +1,702 @@ + + +struct::list - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::list(n) 1.8.2 tcllib "Tcl Data Structures"

+

Name

+

struct::list - Procedures for manipulating lists

+
+ + +

Description

+

The ::struct::list namespace contains several useful commands +for processing Tcl lists. Generally speaking, they implement +algorithms more complex or specialized than the ones provided by Tcl +itself.

+

It exports only a single command, struct::list. All +functionality provided here can be reached through a subcommand of +this command.

+
+

COMMANDS

+
+
::struct::list longestCommonSubsequence sequence1 sequence2 ?maxOccurs?
+

Returns the longest common subsequence of elements in the two lists +sequence1 and sequence2. If the maxOccurs parameter +is provided, the common subsequence is restricted to elements that +occur no more than maxOccurs times in sequence2.

+

The return value is a list of two lists of equal length. The first +sublist is of indices into sequence1, and the second sublist is +of indices into sequence2. Each corresponding pair of indices +corresponds to equal elements in the sequences; the sequence returned +is the longest possible.

+
::struct::list longestCommonSubsequence2 sequence1 sequence2 ?maxOccurs?
+

Returns an approximation to the longest common sequence of elements in +the two lists sequence1 and sequence2. +If the maxOccurs parameter is omitted, the subsequence computed +is exactly the longest common subsequence; otherwise, the longest +common subsequence is approximated by first determining the longest +common sequence of only those elements that occur no more than +maxOccurs times in sequence2, and then using that result +to align the two lists, determining the longest common subsequences of +the sublists between the two elements.

+

As with longestCommonSubsequence, the return value is a list +of two lists of equal length. The first sublist is of indices into +sequence1, and the second sublist is of indices into +sequence2. Each corresponding pair of indices corresponds to +equal elements in the sequences. The sequence approximates the +longest common subsequence.

+
::struct::list lcsInvert lcsData len1 len2
+

This command takes a description of a longest common subsequence +(lcsData), inverts it, and returns the result. Inversion means +here that as the input describes which parts of the two sequences are +identical the output describes the differences instead.

+

To be fully defined the lengths of the two sequences have to be known +and are specified through len1 and len2.

+

The result is a list where each element describes one chunk of the +differences between the two sequences. This description is a list +containing three elements, a type and two pairs of indices into +sequence1 and sequence2 respectively, in this order. +The type can be one of three values:

+
+
added
+

Describes an addition. I.e. items which are missing in sequence1 +can be found in sequence2. +The pair of indices into sequence1 describes where the added +range had been expected to be in sequence1. The first index +refers to the item just before the added range, and the second index +refers to the item just after the added range. +The pair of indices into sequence2 describes the range of items +which has been added to it. The first index refers to the first item +in the range, and the second index refers to the last item in the +range.

+
deleted
+

Describes a deletion. I.e. items which are in sequence1 are +missing from sequence2. +The pair of indices into sequence1 describes the range of items +which has been deleted. The first index refers to the first item in +the range, and the second index refers to the last item in the range. +The pair of indices into sequence2 describes where the deleted +range had been expected to be in sequence2. The first index +refers to the item just before the deleted range, and the second index +refers to the item just after the deleted range.

+
changed
+

Describes a general change. I.e a range of items in sequence1 +has been replaced by a different range of items in sequence2. +The pair of indices into sequence1 describes the range of items +which has been replaced. The first index refers to the first item in +the range, and the second index refers to the last item in the range. +The pair of indices into sequence2 describes the range of items +replacing the original range. Again the first index refers to the +first item in the range, and the second index refers to the last item +in the range.

+
+
+    sequence 1 = {a b r a c a d a b r a}
+    lcs 1      =   {1 2   4 5     8 9 10}
+    lcs 2      =   {0 1   3 4     5 6 7}
+    sequence 2 =   {b r i c a     b r a c}
+    Inversion  = {{deleted  {0  0} {-1 0}}
+                  {changed  {3  3}  {2 2}}
+                  {deleted  {6  7}  {4 5}}
+                  {added   {10 11}  {8 8}}}
+
+

Notes:

+
    +

  • An index of -1 in a deleted chunk refers to just before +the first element of the second sequence.

    • +

  • Also an index equal to the length of the first sequence in an +added chunk refers to just behind the end of the sequence.

    • +
+
::struct::list lcsInvert2 lcs1 lcs2 len1 len2
+

Similar to lcsInvert. Instead of directly taking the result +of a call to longestCommonSubsequence this subcommand expects +the indices for the two sequences in two separate lists.

+
::struct::list lcsInvertMerge lcsData len1 len2
+

Similar to lcsInvert. It returns essentially the same +structure as that command, except that it may contain chunks of type +unchanged too.

+

These new chunks describe the parts which are unchanged between the +two sequences. This means that the result of this command describes +both the changed and unchanged parts of the two sequences in one +structure.

+
+    sequence 1 = {a b r a c a d a b r a}
+    lcs 1      =   {1 2   4 5     8 9 10}
+    lcs 2      =   {0 1   3 4     5 6 7}
+    sequence 2 =   {b r i c a     b r a c}
+    Inversion/Merge  = {{deleted   {0  0} {-1 0}}
+                        {unchanged {1  2}  {0 1}}
+                        {changed   {3  3}  {2 2}}
+                        {unchanged {4  5}  {3 4}}
+                        {deleted   {6  7}  {4 5}}
+                        {unchanged {8 10}  {5 7}}
+                        {added    {10 11}  {8 8}}}
+
+
+
::struct::list lcsInvertMerge2 lcs1 lcs2 len1 len2
+

Similar to lcsInvertMerge. Instead of directly taking the +result of a call to longestCommonSubsequence this subcommand +expects the indices for the two sequences in two separate lists.

+
::struct::list reverse sequence
+

The subcommand takes a single sequence as argument and returns a new +sequence containing the elements of the input sequence in reverse +order.

+
::struct::list shuffle list
+

The subcommand takes a list and returns a copy of that list +with the elements it contains in random order. Every possible +ordering of elements is equally likely to be generated. The +Fisher-Yates shuffling algorithm is used internally.

+
::struct::list assign sequence varname ?varname?...
+

The subcommand assigns the first n elements of the input +sequence to the one or more variables whose names were listed +after the sequence, where n is the number of specified +variables.

+

If there are more variables specified than there are elements in the +sequence the empty string will be assigned to the superfluous +variables.

+

If there are more elements in the sequence than variable names +specified the subcommand returns a list containing the unassigned +elements. Else an empty list is returned.

+
+    tclsh> ::struct::list assign {a b c d e} foo bar
+    c d e
+    tclsh> set foo
+    a
+    tclsh> set bar
+    b
+
+
+
::struct::list flatten ?-full? ?--? sequence
+

The subcommand takes a single sequence and returns a new +sequence where one level of nesting was removed from the input +sequence. In other words, the sublists in the input sequence are +replaced by their elements.

+

The subcommand will remove any nesting it finds if the option +-full is specified.

+
+    tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10}
+    1 2 3 4 5 6 7 {8 9} 10
+    tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10}
+    1 2 3 4 5 6 7 8 9 10
+
+
+
::struct::list map sequence cmdprefix
+

The subcommand takes a sequence to operate on and a command +prefix (cmdprefix) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of the results of that application.

+

The command prefix will be evaluated with a single word appended to +it. The evaluation takes place in the context of the caller of the +subcommand.

+
+    tclsh> # squaring all elements in a list
+    tclsh> proc sqr {x} {expr {$x*$x}}
+    tclsh> ::struct::list map {1 2 3 4 5} sqr
+    1 4 9 16 25
+    tclsh> # Retrieving the second column from a matrix
+    tclsh> # given as list of lists.
+    tclsh> proc projection {n list} {::lindex $list $n}
+    tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1}
+    b 2 f
+
+
+
::struct::list mapfor var sequence script
+

The subcommand takes a sequence to operate on and a tcl script, +applies the script to each element of the sequence and returns a sequence +consisting of the results of that application.

+

The script will be evaluated as is, and has access to the current list element +through the specified iteration variable var. The evaluation takes place +in the context of the caller of the subcommand.

+
+    tclsh> # squaring all elements in a list
+    tclsh> ::struct::list mapfor x {1 2 3 4 5} {
+	expr {$x * $x}
+    }
+    1 4 9 16 25
+    tclsh> # Retrieving the second column from a matrix
+    tclsh> # given as list of lists.
+    tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} {
+	lindex $x 1
+    }
+    b 2 f
+
+
+
::struct::list filter sequence cmdprefix
+

The subcommand takes a sequence to operate on and a command +prefix (cmdprefix) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of all elements of the sequence for which the command +prefix returned true. +In other words, this command filters out all elements of the input +sequence which fail the test the cmdprefix represents, and +returns the remaining elements.

+

The command prefix will be evaluated with a single word appended to +it. The evaluation takes place in the context of the caller of the +subcommand.

+
+    tclsh> # removing all odd numbers from the input
+    tclsh> proc even {x} {expr {($x % 2) == 0}}
+    tclsh> ::struct::list filter {1 2 3 4 5} even
+    2 4
+
+

Note: The filter is a specialized application of +fold where the result is extended with the current item or +not, depending o nthe result of the test.

+
::struct::list filterfor var sequence expr
+

The subcommand takes a sequence to operate on and a tcl expression +(expr) specifying a condition, applies the conditionto each element +of the sequence and returns a sequence consisting of all elements of the +sequence for which the expression returned true. +In other words, this command filters out all elements of the input +sequence which fail the test the condition expr represents, and +returns the remaining elements.

+

The expression will be evaluated as is, and has access to the current list +element through the specified iteration variable var. The evaluation +takes place in the context of the caller of the subcommand.

+
+    tclsh> # removing all odd numbers from the input
+    tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0}
+    2 4
+
+
+
::struct::list split sequence cmdprefix ?passVar failVar?
+

This is a variant of method filter, see above. Instead of +returning just the elements passing the test we get lists of both +passing and failing elements.

+

If no variable names are specified then the result of the command will +be a list containing the list of passing elements, and the list of +failing elements, in this order. Otherwise the lists of passing and +failing elements are stored into the two specified variables, and the +result will be a list containing two numbers, the number of elements +passing the test, and the number of elements failing, in this order.

+

The interface to the test is the same as used by filter.

+
::struct::list fold sequence initialvalue cmdprefix
+

The subcommand takes a sequence to operate on, an arbitrary +string initial value and a command prefix (cmdprefix) +specifying an operation.

+

The command prefix will be evaluated with two words appended to +it. The second of these words will always be an element of the +sequence. The evaluation takes place in the context of the caller of +the subcommand.

+

It then reduces the sequence into a single value through repeated +application of the command prefix and returns that value. This +reduction is done by

+
+
1
+

Application of the command to the initial value and the first element +of the list.

+
2
+

Application of the command to the result of the last call and the +second element of the list.

+
...
+
+
i
+

Application of the command to the result of the last call and the +i'th element of the list.

+
...
+
+
end
+

Application of the command to the result of the last call and the last +element of the list. The result of this call is returned as the result +of the subcommand.

+
+
+    tclsh> # summing the elements in a list.
+    tclsh> proc + {a b} {expr {$a + $b}}
+    tclsh> ::struct::list fold {1 2 3 4 5} 0 +
+    15
+
+
+
::struct::list shift listvar
+

The subcommand takes the list contained in the variable named by +listvar and shifts it down one element. +After the call listvar will contain a list containing the second +to last elements of the input list. The first element of the ist is +returned as the result of the command. Shifting the empty list does +nothing.

+
::struct::list iota n
+

The subcommand returns a list containing the integer numbers +in the range [0,n). The element at index i +of the list contain the number i.

+

For "n == 0" an empty list will be returned.

+
::struct::list equal a b
+

The subcommand compares the two lists a and b for +equality. In other words, they have to be of the same length and have +to contain the same elements in the same order. If an element is a +list the same definition of equality applies recursively.

+

A boolean value will be returned as the result of the command. +This value will be true if the two lists are equal, and +false else.

+
::struct::list repeat size element1 ?element2 element3...?
+

The subcommand creates a list of length +"size * number of elements" by repeating size +times the sequence of elements +element1 element2 .... +size must be a positive integer, elementn can be any +Tcl value. +Note that repeat 1 arg ... is identical to +list arg ..., though the arg is required +with repeat.

+

Examples:

+
+    tclsh> ::struct::list repeat 3 a
+    a a a
+    tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0]
+    {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeat 3 a b c
+    a b c a b c a b c
+    tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c
+    {a a} b c {a a} b c {a a} b c
+
+
+
::struct::list repeatn value size...
+

The subcommand creates a (nested) list containing the value in +all positions. The exact size and degree of nesting is determined by +the size arguments, all of which have to be integer numbers +greater than or equal to zero.

+

A single argument size which is a list of more than one element +will be treated as if more than argument size was specified.

+

If only one argument size is present the returned list will not +be nested, of length size and contain value in all +positions. +If more than one size argument is present the returned +list will be nested, and of the length specified by the last +size argument given to it. The elements of that list +are defined as the result of Repeat for the same arguments, +but with the last size value removed.

+

An empty list will be returned if no size arguments are present.

+
+    tclsh> ::struct::list repeatn  0 3 4
+    {0 0 0} {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeatn  0 {3 4}
+    {0 0 0} {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeatn  0 {3 4 5}
+    {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}}
+
+
+
::struct::list dbJoin ?-inner|-left|-right|-full? ?-keys varname? {keycol table}...
+

The method performs a table join according to relational algebra. The +execution of any of the possible outer join operation is triggered by +the presence of either option -left, -right, or +-full. If none of these options is present a regular inner +join will be performed. This can also be triggered by specifying +-inner. The various possible join operations are explained in +detail in section TABLE JOIN.

+

If the -keys is present its argument is the name of a +variable to store the full list of found keys into. Depending on the +exact nature of the input table and the join mode the output table may +not contain all the keys by default. In such a case the caller can +declare a variable for this information and then insert it into the +output table on its own, as she will have more information about the +placement than this command.

+

What is left to explain is the format of the arguments.

+

The keycol arguments are the indices of the columns in the +tables which contain the key values to use for the joining. Each +argument applies to the table following immediately after it. The +columns are counted from 0, which references the first +column. The table associated with the column index has to have at +least keycol+1 columns. An error will be thrown if there are +less.

+

The table arguments represent a table or matrix of rows and +columns of values. We use the same representation as generated and +consumed by the methods get rect and set rect of +matrix objects. In other words, each argument is a list, +representing the whole matrix. Its elements are lists too, each +representing a single rows of the matrix. The elements of the +row-lists are the column values.

+

The table resulting from the join operation is returned as the result +of the command. We use the same representation as described above for +the input tables.

+
::struct::list dbJoinKeyed ?-inner|-left|-right|-full? ?-keys varname? table...
+

The operations performed by this method are the same as described +above for dbJoin. The only difference is in the specification +of the keys to use. Instead of using column indices separate from the +table here the keys are provided within the table itself. The row +elements in each table are not the lists of column values, but a +two-element list where the second element is the regular list of +column values and the first element is the key to use.

+
::struct::list swap listvar i j
+

The subcommand exchanges the elements at the indices i and +j in the list stored in the variable named by listvar. The +list is modified in place, and also returned as the result of the +subcommand.

+
::struct::list firstperm list
+

This subcommand returns the lexicographically first permutation of the +input list.

+
::struct::list nextperm perm
+

This subcommand accepts a permutation of a set of elements (provided +by perm) and returns the next permutatation in lexicographic +sequence.

+

The algorithm used here is by Donal E. Knuth, see section +REFERENCES for details.

+
::struct::list permutations list
+

This subcommand returns a list containing all permutations of the +input list in lexicographic order.

+
::struct::list foreachperm var list body
+

This subcommand executes the script body once for each +permutation of the specified list. The permutations are visited +in lexicographic order, and the variable var is set to the +permutation for which body is currently executed. The result of +the loop command is the empty string.

+
+
+

LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON

+

The longestCommonSubsequence subcommand forms the core of a +flexible system for doing differential comparisons of files, similar +to the capability offered by the Unix command diff. +While this procedure is quite rapid for many tasks of file comparison, +its performance degrades severely if sequence2 contains many +equal elements (as, for instance, when using this procedure to compare +two files, a quarter of whose lines are blank. This drawback is +intrinsic to the algorithm used (see the Reference for details).

+

One approach to dealing with the performance problem that is sometimes +effective in practice is arbitrarily to exclude elements that appear +more than a certain number of times. +This number is provided as the maxOccurs parameter. If frequent +lines are excluded in this manner, they will not appear in the common +subsequence that is computed; the result will be the longest common +subsequence of infrequent elements. +The procedure longestCommonSubsequence2 implements this +heuristic. +It functions as a wrapper around longestCommonSubsequence; it +computes the longest common subsequence of infrequent elements, and +then subdivides the subsequences that lie between the matches to +approximate the true longest common subsequence.

+
+

TABLE JOIN

+

This is an operation from relational algebra for relational databases.

+

The easiest way to understand the regular inner join is that it +creates the cartesian product of all the tables involved first and +then keeps only all those rows in the resulting table for which the +values in the specified key columns are equal to each other.

+

Implementing this description naively, i.e. as described above will +generate a huge intermediate result. To avoid this the +cartesian product and the filtering of row are done at the same +time. What is required is a fast way to determine if a key is present +in a table. In a true database this is done through indices. Here we +use arrays internally.

+

An outer join is an extension of the inner join for two +tables. There are three variants of outerjoins, called left, +right, and full outer joins. Their result always +contains all rows from an inner join and then some additional rows.

+
    +

  1. For the left outer join the additional rows are all rows from the left +table for which there is no key in the right table. They are joined to +an empty row of the right table to fit them into the result.

    2. +

  2. For the right outer join the additional rows are all rows from the right +table for which there is no key in the left table. They are joined to +an empty row of the left table to fit them into the result.

    3. +

  3. The full outer join combines both left and right outer join. In other +words, the additional rows are as defined for left outer join, and +right outer join, combined.

    4. +
+

We extend all the joins from two to n tables (n > 2) by +executing

+
+    (...((table1 join table2) join table3) ...) join tableN
+
+

Examples for all the joins:

+
+    Inner Join
+    {0 foo}              {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} inner join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}             {3 driver}
+    Left Outer Join
+    {0 foo}                   {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} left outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                  {3 driver}   {2 blue  {} {}}
+    Right Outer Join
+    {0 foo}                    {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} right outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                   {3 driver}   {{} {}   3 driver}
+    Full Outer Join
+    {0 foo}                   {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} full outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                  {3 driver}   {2 blue  {} {}}
+                                           {{} {}   3 driver}
+
+
+

REFERENCES

+
    +

  1. J. W. Hunt and M. D. McIlroy, "An algorithm for differential +file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone +Laboratories (1976). Available on the Web at the second +author's personal site: http://www.cs.dartmouth.edu/~doug/

    2. +

  2. Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' +volume 4". Available on the Web at the author's personal site: +http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz.

    3. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: list of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_set.html Index: embedded/www/tcllib/files/modules/struct/struct_set.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/struct_set.html @@ -0,0 +1,241 @@ + + +struct::set - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::set(n) 2.2.3 tcllib "Tcl Data Structures"

+

Name

+

struct::set - Procedures for manipulating sets

+
+ + +

Description

+

The ::struct::set namespace contains several useful commands for +processing finite sets.

+

It exports only a single command, struct::set. All +functionality provided here can be reached through a subcommand of +this command.

+

Note: As of version 2.2 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+
+

COMMANDS

+
+
::struct::set empty set
+

Returns a boolean value indicating if the set is +empty (true), or not (false).

+
::struct::set size set
+

Returns an integer number greater than or equal to zero. This is the +number of elements in the set. In other words, its cardinality.

+
::struct::set contains set item
+

Returns a boolean value indicating if the set contains the +element item (true), or not (false).

+
::struct::set union ?set1...?
+

Computes the set containing the union of set1, set2, +etc., i.e. "set1 + set2 + ...", and returns this set +as the result of the command.

+
::struct::set intersect ?set1...?
+

Computes the set containing the intersection of set1, +set2, etc., i.e. "set1 * set2 * ...", and +returns this set as the result of the command.

+
::struct::set difference set1 set2
+

Computes the set containing the difference of set1 and +set2, i.e. ("set1 - set2") and returns this +set as the result of the command.

+
::struct::set symdiff set1 set2
+

Computes the set containing the symmetric difference of set1 and +set2, i.e. ("(set1 - set2) + (set2 - set1)") +and returns this set as the result of the command.

+
::struct::set intersect3 set1 set2
+

This command is a combination of the methods intersect and +difference. +It returns a three-element list containing "set1*set2", +"set1-set2", and "set2-set1", in this +order. In other words, the intersection of the two parameter sets, and +their differences.

+
::struct::set equal set1 set2
+

Returns a boolean value indicating if the two sets are equal +(true) or not (false).

+
::struct::set include svar item
+

The element item is added to the set specified by the variable +name in svar. The return value of the command is empty. This is +the equivalent of lappend for sets. If the variable named by +svar does not exist it will be created.

+
::struct::set exclude svar item
+

The element item is removed from the set specified by the +variable name in svar. The return value of the command is +empty. This is a near-equivalent of lreplace for sets.

+
::struct::set add svar set
+

All the element of set are added to the set specified by the +variable name in svar. The return value of the command is +empty. This is like the method include, but for the addition +of a whole set. If the variable named by svar does not exist it +will be created.

+
::struct::set subtract svar set
+

All the element of set are removed from the set specified by the +variable name in svar. The return value of the command is +empty. This is like the method exclude, but for the removal +of a whole set.

+
::struct::set subsetof A B
+

Returns a boolean value indicating if the set A is a true +subset of or equal to the set B (true), or not +(false).

+
+
+ +

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: set of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_tree.html Index: embedded/www/tcllib/files/modules/struct/struct_tree.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/struct_tree.html @@ -0,0 +1,696 @@ + + +struct::tree - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::tree(n) 2.1.1 tcllib "Tcl Data Structures"

+

Name

+

struct::tree - Create and manipulate tree objects

+
+ + +

Description

+

A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that +places a hierarchical structure on the nodes. (Data Structures and +Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In +addition to maintaining the node relationships, this tree +implementation allows any number of keyed values to be associated with +each node.

+

The element names can be arbitrary strings.

+

A tree is thus similar to an array, but with three important +differences:

+
    +

  1. Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.)

    2. +

  2. Trees have a hierarchical structure, whereas an array is just an +unordered collection.

    3. +

  3. Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary.

    4. +
+

Note: The major version of the package struct has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +Changes for 2.0 for a full list of all changes, +incompatible and otherwise.

+
+

API

+

Tree CLASS API

+

The main commands of the package are:

+
+
::struct::tree ?treeName? ?=|:=|as|deserialize source?
+

The command creates a new tree object with an associated global Tcl +command whose name is treeName. This command may be used to +invoke various operations on the tree. +It has the following general form:

+
+
treeName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If treeName is not specified a unique name will be generated by +the package itself. If a source is specified the new tree will +be initialized to it. For the operators =, :=, and +as source is interpreted as the name of another tree +object, and the assignment operator = will be executed. For +deserialize the source is a serialized tree object and +deserialize will be executed.

+

In other words

+
+    ::struct::tree mytree = b
+
+

is equivalent to

+
+    ::struct::tree mytree
+    mytree = b
+
+

and

+
+    ::struct::tree mytree deserialize $b
+
+

is equivalent to

+
+    ::struct::tree mytree
+    mytree deserialize $b
+
+
+
::struct::tree::prune
+

This command is provided outside of the tree methods, as it is not a +tree method per se. It however interacts tightly with the method +walk. When used in the walk script it causes the traversal to +ignore the children of the node we are currently at. +This command cannot be used with the traversal modes which look at +children before their parent, i.e. post and in. The +only applicable orders of traversal are pre and +both. An error is thrown if the command and chosen order of +traversal do not fit.

+
+
+

Tree OBJECT API

+

Two general observations beforehand:

+
    +

  1. The root node of the tree can be used in most places where a node is +asked for. The default name of the rootnode is "root", but this can be +changed with the method rename (see below). Whatever the +current name for the root node of the tree is, it can be retrieved by +calling the method rootname.

    2. +

  2. The method insert is the only way to create new nodes, and +they are automatically added to a parent. A tree object cannot have +nodes without a parent, save the root node.

    3. +
+

And now the methods supported by tree objects created by this package:

+
+
treeName = sourcetree
+

This is the assignment operator for tree objects. It copies the tree +contained in the tree object sourcetree over the tree data in +treeName. The old contents of treeName are deleted by this +operation.

+

This operation is in effect equivalent to

+
+    treeName deserialize [sourcetree serialize]
+
+
+
treeName --> desttree
+

This is the reverse assignment operator for tree objects. It copies the tree +contained in the tree object treeName over the tree data in the object +desttree. The old contents of desttree are deleted by this +operation.

+

This operation is in effect equivalent to

+
+    desttree deserialize [treeName serialize]
+
+
+
treeName ancestors node
+

This method extends the method parent and returns a list +containing all ancestor nodes to the specified node. The +immediate ancestor, in other words, parent node, is the first element +in that list, its parent the second element, and so on until the root +node is reached, making it the last element of the returned list.

+
treeName append node key value
+

Appends a value to one of the keyed values associated with an +node. Returns the new value given to the attribute key.

+
treeName attr key
+
+
treeName attr key -nodes list
+
+
treeName attr key -glob globpattern
+
+
treeName attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all nodes in the tree (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from node names to the value of +attribute key at that node. +Nodes not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-nodes
+

The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the nodes in the tree whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the nodes in the tree whose +names match this pattern are searched for the attribute.

+
+
treeName children ?-all? node ?filter cmdprefix?
+

Return a list of the children of node. +If the option -all is specified, then not only the direct +children, but their children, and so on are returned in the result. +If a filter command is specified only those nodes are listed in the +final result which pass the test. The command in cmdprefix is +called with two arguments, the name of the tree object, and the name +of the node in question. It is executed in the context of the caller +and has to return a boolean value. Nodes for which the command returns +false are removed from the result list before it is returned +to the caller.

+

Some examples:

+
+    mytree insert root end 0 ; mytree set 0 volume 30
+    mytree insert root end 1
+    mytree insert root end 2
+    mytree insert 0    end 3
+    mytree insert 0    end 4
+    mytree insert 4    end 5 ; mytree set 5 volume 50
+    mytree insert 4    end 6
+    proc vol {t n} {
+	$t keyexists $n volume
+    }
+    proc vgt40 {t n} {
+	if {![$t keyexists $n volume]} {return 0}
+	expr {[$t get $n volume] > 40}
+    }
+    tclsh> lsort [mytree children -all root filter vol]
+    0 5
+    tclsh> lsort [mytree children -all root filter vgt40]
+    5
+    tclsh> lsort [mytree children root filter vol]
+    0
+    tclsh> puts ([lsort [mytree children root filter vgt40]])
+    ()
+
+
+
treeName cut node
+

Removes the node specified by node from the tree, but not its +children. The children of node are made children of the parent +of the node, at the index at which node was located.

+
treeName delete node ?node ...?
+

Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes.

+
treeName depth node
+

Return the number of steps from node node to the root node.

+
treeName descendants node ?filter cmdprefix?
+

This method extends the method children and returns a list +containing all nodes descending from node, and passing the +filter, if such was specified.

+

This is actually the same as +"treeName children -all". +descendants should be prefered, and "children -all" +will be deprecated sometime in the future.

+
treeName deserialize serialization
+

This is the complement to serialize. It replaces tree data in +treeName with the tree described by the serialization +value. The old contents of treeName are deleted by this +operation.

+
treeName destroy
+

Destroy the tree, including its storage space and associated command.

+
treeName exists node
+

Returns true if the specified node exists in the tree.

+
treeName get node key
+

Returns the value associated with the key key for the node +node.

+
treeName getall node ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +containing the attribute data for the node. +If the glob pattern is specified only the attributes whose names +match the pattern will be part of the dictionary.

+
treeName keys node ?pattern?
+

Returns a list of keys for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
treeName keyexists node key
+

Return true if the specified key exists for the node.

+
treeName index node
+

Returns the index of node in its parent's list of children. For +example, if a node has nodeFoo, nodeBar, and +nodeBaz as children, in that order, the index of +nodeBar is 1.

+
treeName insert parent index ?child ?child ...??
+

Insert one or more nodes into the tree as children of the node +parent. The nodes will be added in the order they are given. If +parent is root, it refers to the root of the tree. The +new nodes will be added to the parent node's child list at the +index given by index. The index can be end in +which case the new nodes will be added after the current last child. +Indices of the form "end-n" are accepted as well.

+

If any of the specified children already exist in treeName, +those nodes will be moved from their original location to the new +location indicated by this command.

+

If no child is specified, a single node will be added, and a +name will be generated for the new node. The generated name is of the +form nodex, where x is a number. If names are +specified they must neither contain whitespace nor colons (":").

+

The return result from this command is a list of nodes added.

+
treeName isleaf node
+

Returns true if node is a leaf of the tree (if node has no +children), false otherwise.

+
treeName lappend node key value
+

Appends a value (as a list) to one of the keyed values +associated with an node. Returns the new value given to the +attribute key.

+
treeName leaves
+

Return a list containing all leaf nodes known to the tree.

+
treeName move parent index node ?node ...?
+

Make the specified nodes children of parent, inserting them into +the parent's child list at the index given by index. Note that +the command will take all nodes out of the tree before inserting them +under the new parent, and that it determines the position to place +them into after the removal, before the re-insertion. This behaviour +is important when it comes to moving one or more nodes to a different +index without changing their parent node.

+
treeName next node
+

Return the right sibling of node, or the empty string if +node was the last child of its parent.

+
treeName numchildren node
+

Return the number of immediate children of node.

+
treeName nodes
+

Return a list containing all nodes known to the tree.

+
treeName parent node
+

Return the parent of node.

+
treeName previous node
+

Return the left sibling of node, or the empty string if +node was the first child of its parent.

+
treeName rename node newname
+

Renames the node node to newname. An error is thrown if +either the node does not exist, or a node with name newname does +exist. The result of the command is the new name of the node.

+
treeName rootname
+

Returns the name of the root node of the tree.

+
treeName serialize ?node?
+

This method serializes the sub-tree starting at node. In other +words it returns a tcl value completely describing the tree +starting at node. +This allows, for example, the transfer of tree objects (or parts +thereof) over arbitrary channels, persistence, etc. +This method is also the basis for both the copy constructor and +the assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the tree interface. This is what will enable us to +copy tree data between different implementations of the same +interface.

+

The result is a list containing containing a multiple of three +elements. It is like a serialized array except that there are two +values following each key. They are the names of the nodes in the +serialized tree. The two values are a reference to the parent node and +the attribute data, in this order.

+

The reference to the parent node is the empty string for the root node +of the tree. For all other nodes it is the index of the parent node in +the list. This means that they are integers, greater than or equal to +zero, less than the length of the list, and multiples of three. +The order of the nodes in the list is important insofar as it is used +to reconstruct the lists of children for each node. The children of a +node have to be listed in the serialization in the same order as they +are listed in their parent in the tree.

+

The attribute data of a node is a dictionary, i.e. a list of even +length containing a serialized array. For a node without attribute +data the dictionary is the empty list.

+

Note: While the current implementation returns the root node as +the first element of the list, followed by its children and their +children in a depth-first traversal this is not necessarily true for +other implementations. +The only information a reader of the serialized data can rely on for +the structure of the tree is that the root node is signaled by the +empty string for the parent reference, that all other nodes refer to +their parent through the index in the list, and that children occur in +the same order as in their parent.

+
+ A possible serialization for the tree structure
+             +- d
+       +- a -+
+ root -+- b  +- e
+       +- c
+ is
+ {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}}
+ The above assumes that none of the nodes have attributes.
+
+
+
treeName set node key ?value?
+

Set or get one of the keyed values associated with a node. A node may +have any number of keyed values associated with it. If value is +not specified, this command returns the current value assigned to the +key; if value is specified, this command assigns that value to +the key, and returns it.

+
treeName size ?node?
+

Return a count of the number of descendants of the node node; if +no node is specified, root is assumed.

+
treeName splice parent from ?to? ?child?
+

Insert a node named child into the tree as a child of the node +parent. If parent is root, it refers to the root +of the tree. The new node will be added to the parent node's child +list at the index given by from. The children of parent +which are in the range of the indices from and to are made +children of child. If the value of to is not specified it +defaults to end. If no name is given for child, a name +will be generated for the new node. The generated name is of the form +nodex, where x is a number. The return result +from this command is the name of the new node.

+

The arguments from and to are regular list indices, i.e. +the form "end-n" is accepted as well.

+
treeName swap node1 node2
+

Swap the position of node1 and node2 in the tree.

+
treeName unset node key
+

Removes a keyed value from the node node. The method will do +nothing if the key does not exist.

+
treeName walk node ?-order order? ?-type type? loopvar script
+

Perform a breadth-first or depth-first walk of the tree starting at +the node node. The type of walk, breadth-first or depth-first, +is determined by the value of type; bfs indicates +breadth-first, dfs indicates depth-first. Depth-first is the +default. The order of the walk, pre-, post-, both- or in-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order and in indicates in-order. Pre-order is the +default.

+

Pre-order walking means that a parent node is visited before any of +its children. For example, a breadth-first search starting from the +root will visit the root, followed by all of the root's children, +followed by all of the root's grandchildren. Post-order walking means +that a parent node is visited after any of its children. Both-order +walking means that a parent node is visited before and after +any of its children. In-order walking means that a parent node is +visited after its first child and before the second. This is a +generalization of in-order walking for binary trees and will do the +right thing if a binary tree is walked. The combination of a breadth-first +walk with in-order is illegal.

+

As the walk progresses, the script will be evaluated at each +node. The evaluation takes place in the context of the caller of the +method. +Regarding loop variables, these are listed in loopvar. If one +only one variable is specified it will be set to the id of the +node. When two variables are specified, i.e. loopvar is a true +list, then the first variable will be set to the action performed at +the node, and the other to the id of the node itself. +All loop variables are created in the context of the caller.

+

There are three possible actions: enter, leave, +or visit. enter actions occur during pre-order +walks; leave actions occur during post-order walks; +visit actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +enter for the first evaluation, and leave for the +second.

+

Note: The enter action for a node is always performed +before the walker will look at the children of that node. This means +that changes made by the script to the children of the node +will immediately influence the walker and the steps it will take.

+

Any other manipulation, for example of nodes higher in the tree (i.e +already visited), or upon leaving will have undefined results. They +may succeed, error out, silently compute the wrong result, or anything +in between.

+

At last a small table showing the relationship between the various +options and the possible actions.

+
+ order       type    actions         notes
+ -----       ----    -----           -----
+ pre         dfs     enter           parent before children
+ post        dfs     leave           parent after children
+ in          dfs     visit           parent between first and second child.
+ both        dfs     enter, leave    parent before and after children
+ -----       ----    -----           -----
+ pre         bfs     enter           parent before children
+ post        bfs     leave           parent after children
+ in          bfs             -- illegal --
+ both        bfs     enter, leave    parent before and after children
+ -----       ----    -----           -----
+
+

Note the command ::struct::tree::prune. This command can be used +in the walk script to force the command to ignore the children of the +node we are currently at. It will throw an error if the order of +traversal is either post or in as these modes visit +the children before their parent, making pruning non-sensical.

+
treeName walkproc node ?-order order? ?-type type? cmdprefix
+

This method is like method walk in all essentials, except the +interface to the user code. This method invokes a command prefix with +three additional arguments (tree, node, and action), instead of +evaluating a script and passing the node via a loop variable.

+
+
+

Changes for 2.0

+

The following noteworthy changes have occurred:

+
    +

  1. The API for accessing attributes and their values has been +simplified.

    +

    All functionality regarding the default attribute "data" has been +removed. This default attribute does not exist anymore. All accesses +to attributes have to specify the name of the attribute in +question. This backward incompatible change allowed us to +simplify the signature of all methods handling attributes.

    +

    Especially the flag -key is not required anymore, even more, +its use is now forbidden. Please read the documentation for the +methods set, get, getall, unset, +append, lappend, keyexists +and keys for a description of the new API's.

    2. +

  2. The methods keys and getall now take an optional +pattern argument and will return only attribute data for keys matching +this pattern.

    3. +

  3. Nodes can now be renamed. See the documentation for the method +rename.

    4. +

  4. The structure has been extended with API's for the serialization and +deserialization of tree objects, and a number of operations based on +them (tree assignment, copy construction).

    +

    Please read the documentation for the methods serialize, +deserialize, =, and -->, and the +documentation on the construction of tree objects.

    +

    Beyond the copying of whole tree objects these new API's also enable +the transfer of tree objects over arbitrary channels and for easy +persistence.

    5. +

  5. The walker API has been streamlined and made more similar to the +command foreach. In detail:

    +
      +

    • The superfluous option -command has been removed.

      • +

    • Ditto for the place holders. Instead of the placeholders two loop +variables have to be specified to contain node and action information.

      • +

    • The old command argument has been documented as a script now, which it +was in the past too.

      • +

    • The fact that enter actions are called before the walker looks +at the children of a node has been documented now. In other words it +is now officially allowed to manipulate the list of children for a +node under these circumstances. It has been made clear that +changes under any other circumstances will have undefined results, +from silently computing the wrong result to erroring out.

      • +
    +
    6. +

  6. A new method, attr, was added allowing the query and +retrieval of attribute data without regard to the node relationship.

    7. +

  7. The method children has been extended with the ability to +select from the children of the node based on an arbitrary filtering +criterium. Another extension is the ability to look not only at the +immediate children of the node, but the whole tree below it.

    8. +
+
+
+

EXAMPLES

+

The following example demonstrates the creation of new nodes:

+
+    mytree insert root end 0   ; # Create node 0, as child of the root
+    mytree insert root end 1 2 ; # Ditto nodes 1 & 2
+    mytree insert 0    end 3   ; # Now create node 3 as child of node 0
+    mytree insert 0    end     ; # Create another child of 0, with a
+    #                              generated name. The name is returned
+    #                              as the result of the command.
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: tree of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_tree1.html Index: embedded/www/tcllib/files/modules/struct/struct_tree1.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/struct/struct_tree1.html @@ -0,0 +1,351 @@ + + +struct::tree_v1 - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

struct::tree_v1(n) 1.2.2 tcllib "Tcl Data Structures"

+

Name

+

struct::tree_v1 - Create and manipulate tree objects

+
+ + +

Description

+

The ::struct::tree command creates a new tree object with an +associated global Tcl command whose name is treeName. This +command may be used to invoke various operations on the tree. It has +the following general form:

+
+
treeName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that +places a hierarchical structure on the nodes. (Data Structures and +Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In +addition to maintaining the node relationships, this tree +implementation allows any number of keyed values to be associated with +each node.

+

The element names can be arbitrary strings.

+

A tree is thus similar to an array, but with three important +differences:

+
    +

  1. Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.)

    2. +

  2. Trees have a hierarchical structure, whereas an array is just an +unordered collection.

    3. +

  3. Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary.

    4. +
+

The following commands are possible for tree objects:

+
+
treeName append node ?-key key? value
+

Appends a value to one of the keyed values associated with an +node. If no key is specified, the key data is assumed.

+
treeName children node
+

Return a list of the children of node.

+
treeName cut node
+

Removes the node specified by node from the tree, but not its +children. The children of node are made children of the parent +of the node, at the index at which node was located.

+
treeName delete node ?node ...?
+

Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes.

+
treeName depth node
+

Return the number of steps from node node to the root node.

+
treeName destroy
+

Destroy the tree, including its storage space and associated command.

+
treeName exists node
+

Returns true if the specified node exists in the tree.

+
treeName get node ?-key key?
+

Return the value associated with the key key for the node +node. If no key is specified, the key data is assumed.

+
treeName getall node
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the node.

+
treeName keys node
+

Returns a list of keys for the node.

+
treeName keyexists node ?-key key?
+

Return true if the specified key exists for the node. If +no key is specified, the key data is assumed.

+
treeName index node
+

Returns the index of node in its parent's list of children. For +example, if a node has nodeFoo, nodeBar, and +nodeBaz as children, in that order, the index of +nodeBar is 1.

+
treeName insert parent index ?child ?child ...??
+

Insert one or more nodes into the tree as children of the node +parent. The nodes will be added in the order they are given. If +parent is root, it refers to the root of the tree. The +new nodes will be added to the parent node's child list at the +index given by index. The index can be end in +which case the new nodes will be added after the current last child.

+

If any of the specified children already exist in treeName, +those nodes will be moved from their original location to the new +location indicated by this command.

+

If no child is specified, a single node will be added, and a +name will be generated for the new node. The generated name is of the +form nodex, where x is a number. If names are +specified they must neither contain whitespace nor colons (":").

+

The return result from this command is a list of nodes added.

+
treeName isleaf node
+

Returns true if node is a leaf of the tree (if node has no +children), false otherwise.

+
treeName lappend node ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an node. If no key is specified, the key +data is assumed.

+
treeName move parent index node ?node ...?
+

Make the specified nodes children of parent, inserting them into +the parent's child list at the index given by index. Note that +the command will take all nodes out of the tree before inserting them +under the new parent, and that it determines the position to place +them into after the removal, before the re-insertion. This behaviour +is important when it comes to moving one or more nodes to a different +index without changing their parent node.

+
treeName next node
+

Return the right sibling of node, or the empty string if +node was the last child of its parent.

+
treeName numchildren node
+

Return the number of immediate children of node.

+
treeName parent node
+

Return the parent of node.

+
treeName previous node
+

Return the left sibling of node, or the empty string if +node was the first child of its parent.

+
treeName set node ?-key key? ?value?
+

Set or get one of the keyed values associated with a node. If no key +is specified, the key data is assumed. Each node that is +added to a tree has the value "" assigned to the key data +automatically. A node may have any number of keyed values associated +with it. If value is not specified, this command returns the +current value assigned to the key; if value is specified, this +command assigns that value to the key.

+
treeName size ?node?
+

Return a count of the number of descendants of the node node; if +no node is specified, root is assumed.

+
treeName splice parent from ?to? ?child?
+

Insert a node named child into the tree as a child of the node +parent. If parent is root, it refers to the root +of the tree. The new node will be added to the parent node's child +list at the index given by from. The children of parent +which are in the range of the indices from and to are made +children of child. If the value of to is not specified it +defaults to end. If no name is given for child, a name +will be generated for the new node. The generated name is of the form +nodex, where x is a number. The return result +from this command is the name of the new node.

+
treeName swap node1 node2
+

Swap the position of node1 and node2 in the tree.

+
treeName unset node ?-key key?
+

Removes a keyed value from the node node. If no key is +specified, the key data is assumed.

+
treeName walk node ?-order order? ?-type type? -command cmd
+

Perform a breadth-first or depth-first walk of the tree starting at +the node node. The type of walk, breadth-first or depth-first, +is determined by the value of type; bfs indicates +breadth-first, dfs indicates depth-first. Depth-first is the +default. The order of the walk, pre-, post-, both- or in-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order and in indicates in-order. Pre-order is the +default.

+

Pre-order walking means that a parent node is visited before any of +its children. For example, a breadth-first search starting from the +root will visit the root, followed by all of the root's children, +followed by all of the root's grandchildren. Post-order walking means +that a parent node is visited after any of its children. Both-order +walking means that a parent node is visited before and after +any of its children. In-order walking means that a parent node is +visited after its first child and before the second. This is a +generalization of in-order walking for binary trees and will do the +right thing if a binary is walked. The combination of a breadth-first +walk with in-order is illegal.

+

As the walk progresses, the command cmd will be evaluated at +each node. Percent substitution will be performed on cmd before +evaluation, just as in a bind script. The following +substitutions are recognized:

+
+
%%
+

Insert the literal % character.

+
%t
+

Name of the tree object.

+
%n
+

Name of the current node.

+
%a
+

Name of the action occurring; one of enter, leave, +or visit. enter actions occur during pre-order +walks; leave actions occur during post-order walks; +visit actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +enter for the first evaluation, and leave for the +second.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: tree of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/tar/tar.html Index: embedded/www/tcllib/files/modules/tar/tar.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tar/tar.html @@ -0,0 +1,263 @@ + + +tar - Tar file handling + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tar(n) 0.7 tcllib "Tar file handling"

+

Name

+

tar - Tar file creation, extraction & manipulation

+
+ + +

Description

+
+
::tar::contents tarball ?-chan?
+

Returns a list of the files contained in tarball. The order is not sorted and depends on the order +files were stored in the archive.

+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::stat tarball ?file? ?-chan?
+

Returns a nested dict containing information on the named ?file? in tarball, +or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys +"mode uid gid size mtime type linkname uname gname + devmajor devminor"

+
+% ::tar::stat tarball.tar
+foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
+
+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::untar tarball args
+

Extracts tarball. -file and -glob limit the extraction +to files which exactly match or pattern match the given argument. No error is +thrown if no files match. Returns a list of filenames extracted and the file +size. The size will be null for non regular files. Leading path seperators are +stripped so paths will always be relative.

+
+
-dir dirName
+

Directory to extract to. Uses pwd if none is specified

+
-file fileName
+

Only extract the file with this name. The name is matched against the complete path +stored in the archive including directories.

+
-glob pattern
+

Only extract files patching this glob style pattern. The pattern is matched against the complete path +stored in the archive.

+
-nooverwrite
+

Dont overwrite files that already exist

+
-nomtime
+

Leave the file modification time as the current time instead of setting it to the value in the archive.

+
-noperms
+

In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive.

+
-chan
+

If this option is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
+
+% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
+puts "Extracted $file ($size bytes)"
+}
+
+
+
::tar::get tarball fileName ?-chan?
+

Returns the contents of fileName from the tarball

+
+% set readme [::tar::get tarball.tar doc/README] {
+% puts $readme
+}
+
+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::create tarball files args
+

Creates a new tar file containing the files. files must be specified +as a single argument which is a proper list of filenames.

+
+
-dereference
+

Normally create will store links as an actual link pointing at a file that may +or may not exist in the archive. Specifying this option will cause the actual file point to + by the link to be stored instead.

+
-chan
+

If this option is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for writing, and configured for binary output. +The command will not close the channel.

+
+
+% ::tar::create new.tar [glob -nocomplain file*]
+% ::tar::contents new.tar
+file1 file2 file3
+
+
+
::tar::add tarball files args
+

Appends files to the end of the existing tarball. files must be specified +as a single argument which is a proper list of filenames.

+
+
-dereference
+

Normally add will store links as an actual link pointing at a file that may +or may not exist in the archive. Specifying this option will cause the actual file point to + by the link to be stored instead.

+
-prefix string
+

Normally add will store files under exactly the name specified as +argument. Specifying a ?-prefix? causes the string to be +prepended to every name.

+
-quick
+

The only sure way to find the position in the tarball where new +files can be added is to read it from start, but if tarball was +written with a "blocksize" of 1 (as this package does) then one can +alternatively find this position by seeking from the end. The +?-quick? option tells add to do the latter.

+
+
::tar::remove tarball files
+

Removes files from the tarball. No error will result if the file does not exist in the +tarball. Directory write permission and free disk space equivalent to at least the size of the tarball +will be needed.

+
+% ::tar::remove new.tar {file2 file3}
+% ::tar::contents new.tar
+file3
+
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tar of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+
ADDED embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html Index: embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html @@ -0,0 +1,589 @@ + +tepam::argument_dialogbox - Tcl's Enhanced Procedure and Argument Manager + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tepam::argument_dialogbox(n) 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual

+
+ + + +

ARGUMENT DIALOGBOX CALL

+

TEPAM's argument_dialogbox is a flexible and easily usable data entry form generator. Each data entry element of a form is defined via a data entry item that can be provided to argument_dialogbox in two formats:

+
+
tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...?
+

Using this first format, each data entry item is defined via a pair of two arguments. The first one is the item name that defines the entry widget that has to be used in the form. The second argument, called item attributes, specifies the variable which is attributed to the data entry element as well as eventual formatting and context information.

+

The argument_dialogbox returns ok if the entered data have been acknowledged (via the OK button) and validated by a data checker. If the entered data have been rejected (via the Cancel button) the argument_dialogbox returns cancel.

+

A small example illustrates how the argument_dialogbox can be employed:

+
set DialogResult [tepam::argument_dialogbox \
+   -title "Itinerary selection" \
+   -file {-label "Itinerary report" -variable report_file} \
+   -frame {-label "Itinerary start"} \
+      -comment {-text "Specify your itinerary start location"} \
+      -entry {-label "City" -variable start_city -type string} \
+      -entry {-label "Street" -variable start_street -type string -optional 1} \
+      -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
+   -frame {-label "Itinerary destination"} \
+      -comment {-text "Specify your itinerary destination"} \
+      -entry {-label "City" -variable dest_city -type string} \
+      -entry {-label "Street" -variable dest_street -type string -optional 1} \
+      -entry {-label "Street number" -variable dest_street_nbr -type integer -optional 1} \
+   -frame {} \
+   -checkbutton {-label "Don't use highways" -variable no_highway}]
+

This example opens a dialog box that has the title Itinerary selection. A first entry widget in this box allows selecting a report file. It follows two frames to define respectively an itinerary start and end location. Each of these locations that are described with a comment has three entry widgets to specify respectively the city, street and the street number. Bellow the second frame there is a check button that allows specifying if eventual highways should be ignored.

+
tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?}
+

Sometimes it is simpler to provide all the data entry item definitions in form of a single list to argument_dialogbox, and not as individual arguments. The second format that is supported by argument_dialogbox corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to argument_dialogbox. The previous example can therefore also be written in the following way:

+
set DialogResult [tepam::argument_dialogbox {
+   -title "Itinerary selection"
+   -file {-label "Itinerary report" -variable report_file}
+   ...
+   -checkbutton {-label "Don't use highways" -variable no_highway} }]
+
+
+

The commands argument_dialogbox as well as procedure are exported from the namespace tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to import them into the main namespace:

+
namespace import tepam::*
+ 
+set DialogResult [argument_dialogbox \
+   -title "Itinerary selection"
+   ...
+

The following subsections explain the different argument item types that are accepted by the argument_dialogbox, classified into three groups. The first data entry item definition format will be used in the remaining document, knowing that this format can always be transformed into the second format by putting all arguments into a single list that is then provided to argument_dialogbox.

+

Context Definition Items

+

The first item group allows specifying some context aspects of an argument dialog box. These items are taking a simple character string as item attribute:

+
tepam::argument_dialogbox \
+   -<argument_name> string \
+   ...
+

The following items are classified into this group:

+
+
-title string
+

The dialog box window's 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's state, e.g. the entered data as well as the window size and position, is saved and restored then the next time the argument dialog box is called. The assignment of a context allows saving the dialog box' state in its context to distinguish between different usages of the argument dialog box.

+
tepam::argument_dialogbox \
+   -context destination_definitions \
+   ...
+
+
+
+

Formatting and Display Options

+

Especially for big, complex forms it becomes important that the different data entry widgets are graphically well organized and commented to provide an immediate and clear overview to the user. A couple of items allow structuring and commenting the dialog boxes.

+

The items of this classification group require as item attributes a definition list, which contains itself attribute name and value pairs:

+
tepam::argument_dialogbox \
+   ...
+   -<argument_name> { 
+      ?-<attribute_name> <attribute_value>?
+      ?-<attribute_name> <attribute_value>?
+      ?...?
+   }
+   ...
+

The following items are classified into this group:

+
+
-frame list
+

The -frame item allows packing all following entry widgets into a labeled frame, until a next frame item is defined or until the last entry widget has been defined. It recognizes the following attributes inside the item attribute list:

+
+
-label string
+

An optional frame label can be specified with the -label statement.

+
+

Example:

+
tepam::argument_dialogbox \
+   ...
+   -frame {-label "Destination address"}
+   ...
+

To close an open frame without opening a new one, an empty list has to be provided to the -frame statement.

+
tepam::argument_dialogbox \
+   ...
+   -frame {}
+   ...
+
+
-sep [const {{}}]
+

Entry widgets can be separated with the -sep statement which doesn't require additional definitions. The related definition list has to exist, but its content is ignored.

+
tepam::argument_dialogbox \
+   ...
+   -sep {}
+   ...
+
+
-comment string
+

Comments and descriptions can be added with the -text attribute of the -comment item. Please note that each entry widget itself can also contain a -text attribute for comments and descriptions. But the -comment item allows for example adding a description between two frames.

+
tepam::argument_dialogbox \
+   ...
+   -comment {-text "Specify bellow the destination address"}
+   ...
+
+
-yscroll 0|1|auto
+

This attribute allows controlling an eventual vertical scrollbar. Setting it to 0 will permanently disable the scrollbar, setting it to 1 will enable it. By default it is set to auto. The scrollbar is enabled in this mode only if the vertical data entry form size exceeds 66% of the screen height.

+
tepam::argument_dialogbox \
+   ...
+   -yscroll auto
+   ...
+
+
+
+

Data Entry Widget Items

+

Data entry widgets are created with the widget items. These items require as item attributes a definition list, which contains itself attribute name and value pairs:

+
tepam::argument_dialogbox \
+   ...
+   -<argument_name> { 
+      ?-<attribute_name> <attribute_value>?
+      ?-<attribute_name> <attribute_value>?
+      ?...?
+   }
+   ...
+

The attribute list can contain various attributes to describe and comment an entry widget and to constrain its entered value. All entry widgets are accepting a common set of attributes that are described in the section Entry Widget Item Attributes.

+

TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional application specific entry widgets (see APPLICATION SPECIFIC ENTRY WIDGETS):

+
+
-entry list
+

The -entry item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings.

+
tepam::argument_dialogbox \
+   -entry {-label Name -variable Entry}
+
+
-text list
+

The -text item generates a multi line text entry widget. The widget's 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 check boxes' labels 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 radio boxes' labels should differ from the option values, their labels can be defined with the -choicelabels attribute:

+
tepam::argument_dialogbox \
+   -radiobox {-label "Text adjustment" -variable Adjustment \
+              -choices {left center right} \
+              -choicelabels {Left Center Right} -default left}
+
+
-checkbutton list
+

The -checkbutton entry widget allows activating or deactivating a single choice option. The result written into the variable will either be 0 if the check button was not activated or 1 if it was activated. An eventually provided default value has also to be either 0 or 1.

+
tepam::argument_dialogbox \
+   -checkbutton {-label Capitalize -variable Capitalize -default 1}
+
+
+

Several types of list and combo boxes are available to handle selection lists.

+
+
-combobox list
+

The combobox is a combination of a normal entry widget together with a drop-down list box. The combobox allows selecting from this drop-down list box a single element. The list of the available elements can be provided either as a list to the -choices attribute, or via a variable that is specified with the -choicevariable attribute.

+
tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
+

And here is an example of using a variable to define the selection list:

+
set TextSizes {8 9 10 12 15 18}
+tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
+
+
-listbox list
+

In contrast to the combo box, the list box is always displayed by the listbox entry widget. Only one element is selectable unless the -multiple_selection attribute is set. The list box height can be selected with the -height attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box' size. +The first example uses a variable to define the available choices:

+
set set AvailableSizes
+for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
+ 
+tepam::argument_dialogbox \
+   -listbox {-label "Distance" -variable Distance \
+             -choicevariable AvailableSizes -default 6 -height 5}
+

Here is a multi-element selection example. Please note that also the default selection can contain multiple elements:

+
tepam::argument_dialogbox \
+   -listbox {-label "Text styles" -variable Styles \
+             -choices {bold italic underline overstrike} \
+             -choicelabels {Bold Italic Underline Overstrike} \
+             -default {bold underline} -multiple_selection 1 \
+             -height 3}
+
+
-disjointlistbox list
+

A disjoint list box has to be used instead of a normal list box if the selection order is important. The disjoint list box entry widget has in fact two list boxes, one to select elements and one to display the selected elements in the chosen order.

+

Disjoint listboxes allow always selecting multiple elements. With the exception of the -multiple_selection attribute, disjointed list boxes are accepting the same attributes as the normal listbox, e.g. -height, -choices, -choicevariable, -default.

+
tepam::argument_dialogbox \
+   -disjointlistbox {-label "Preferred scripting languages" -variable Languages \
+             -comment "Please select your preferred languages in the order" \
+             -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
+             -default {Tcl Perl Python}}
+
+
+

The file and directory selectors are building a next group of data entry widgets. A paragraph of section Entry Widget Item Attributes explains the widget specific attributes that allow specifying the targeted file types, active directory etc.

+
+
-file list
+

The item -file creates a group composed by an entry widget together with a button that allows opening a file browser. The data type file is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -file {-label "Image file" -variable ImageF \
+          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
+          -initialfile "picture.gif"}
+
+
-existingfile list
+

The item -existingfile creates a group composed by an entry widget together with a button that allows opening a browser to select an existing file. The data type existingfile is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -existingfile {-label "Image file" -variable ImageF \
+                  -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
+                  -initialfile "picture.gif"}
+
+
-directory list
+

The item -directory creates a group composed by an entry widget together with a button that allows opening a directory browser. The data type directory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -directory {-label "Report directory" -variable ReportDir}
+
+
-existingdirectory list
+

The item -existingdirectory creates a group composed by an entry widget together with a button that allows opening a browser to select an existing directory. The data type existingdirectory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -existingdirectory {-label "Report directory" -variable ReportDir}
+
+
+

Finally, there is a last group of some other special data entry widgets.

+
+
-color list
+

The color selector is composed by an entry widget together with a button that allows opening a color browser. The data type color is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -color {-label "Background color" -variable Color -default red}
+
+
-font list
+

The font selector is composed by an entry widget together with a button that allows opening a font browser. The data type font is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute. The entry widget displays an example text in the format of the selected font.

+

The font browser allows selecting by default the font families provided by the font families Tk command as well as a reasonable set of different font sizes between 6 points and 40 points. Different sets of font families and font sizes can be specified respectively via the -font_families or -font_sizes attributes.

+

If no default font is provided via the -default attribute, the default font of the label widget to display the selected font will be used as default selected font. If the font family of this label widget is not part of the available families the first available family is used as default. If the font size of this label widget is not part of the available sizes the next close available size is selected as default size.

+
tepam::argument_dialogbox \
+   -font {-label "Font" -variable Font \
+          -font_sizes {8 10 12 16} \
+          -default {Arial 20 italic}}
+
+
+
+

Entry Widget Item Attributes

+

All the entry widget items are accepting the following attributes:

+
+
-text string
+

Eventual descriptions and comments specified with the -text attribute are displayed above the entry widget.

+
tepam::argument_dialogbox \
+   -entry {-text "Please enter your name bellow" -variable Name}
+
+
-label string
+

The label attribute creates left to the entry widget a label using the provided string as label text:

+
tepam::argument_dialogbox \
+   -entry {-label Name -variable Name}
+
+
-variable string
+

All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget's data are stored inside the defined variables.

+
tepam::argument_dialogbox \
+   -existingdirectory {-label "Report directory" -variable ReportDir}
+
+
-default string
+

Eventual default data for the entry widgets can be provided via the -default attribute. The default value is overridden if an argument dialog box with a defined context is called another time. The value acknowledged in a previous call will be used in this case as default value.

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+               -choices {bold italic underline} -default italic}
+
+
-optional 0|1
+

Data can be specified as optional or mandatory with the -optional attribute that requires either 0 (mandatory) or 1 (optional) as attribute data.

+

In case an entry is optional and no data has been entered, e.g. the entry contains an empty character string, the entry will be considered as undefined and the assigned variable will not be defined.

+
tepam::argument_dialogbox \
+   -entry {-label "City" -variable start_city -type string} \
+   -entry {-label "Street" -variable start_street -type string -optional 0} \
+   -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
+
+
-type string
+

If the data type is defined with the -type attribute the argument dialog box will automatically perform a data type check after acknowledging the entered values and before the dialog box is closed. If a type incompatible value is found an error message box appears and the user can correct the value.

+

The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by tepam::procedure (see the tepam::procedure reference manual).

+

Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the -type attribute.

+
tepam::argument_dialogbox \
+   -entry {-label "Street number" -variable start_street_nbr -type integer} \
+
+
-range string
+

Values can be constrained with the -range attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value.

+

The -range attribute has to be used only for numerical arguments, like integers and doubles.

+
tepam::argument_dialogbox \
+   -entry {-label Month -variable Month -type integer -range {1 12}}
+
+
-validatecommand string
+

More complex value validations than type checks can be performed via specific validation commands that are declared with the -validatecommand attribute. +The provided validation command can be a script (command sequence) in which the pattern %P is replaced by the value that has to be checked.

+
tepam::argument_dialogbox \
+   -entry {-label "Your comment" -variable YourCom \
+           -validatecommand "IllegalWordDetector %P"} ]
+
+
+

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 check and radio boxes' labels should differ from the option values, they can be defined with the -choicelabels attribute:

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+              -choices {bold italic underline} \
+              -choicelabels {Bold Italic Underline}
+
+
-choicevariable string
+

Another way to define the choice lists is using the -choicevariable attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists.

+
set TextSizes {8 9 10 12 15 18}
+tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choicevariable TextSizes}
+
+
-multiple_selection 0|1
+

The list box item (-listbox) allows by default selecting only one list element. By setting the -multiple_selection attribute to 1, multiple elements can be selected.

+
tepam::argument_dialogbox \
+   -listbox {-label "Text styles" -variable Styles \
+             -choices {bold italic underline} -default underline \
+             -multiple_selection 1 -height 3}
+
+
+

Some additional attributes are supported by the file and directory selection widgets.

+
+
-filetypes string
+

The file type attribute is used by the -file and -existingfile items to define the file endings that are searched by the file browser.

+
tepam::argument_dialogbox \
+   -file {-label "Image file" -variable ImageF \
+          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}
+
+
-initialfile string
+

The initial file used by the file browsers of the -file and -existingfile widgets are by default the file defined with the -default attribute, unless a file is specified with the -initialfile attribute.

+
tepam::argument_dialogbox \
+   -file {-variable ImageF -initialfile "picture.gif"}
+
+
-activedir string
+

The -activedir attribute will override the default active search directory used by the file browsers of all file and directory entry widgets. The default active search directory is defined by the directory of a specified initial file (-initialfile) if defined, and otherwise by the directory of the default file/directory, specified with the -default attribute.

+
tepam::argument_dialogbox \
+   -file "-variable ImageF -activedir $pwd"
+
+
+

Finally, there is a last attribute supported by some widgets:

+
+
-height string
+

All widgets containing a selection list (-listbox, -disjointlistbox, -font) as well as the multi line -text widget are accepting the -height attribute that defines the number of displayed rows of the selection lists.

+
tepam::argument_dialogbox \
+   -listbox {-label "Text size" -variable Size \
+             -choices {8 9 10 12 15 18} -default 12 -height 3}
+

If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box' size.

+
+
+
+

APPLICATION SPECIFIC ENTRY WIDGETS

+

An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the tepam namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes:

+
proc tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
+   upvar Option Option; # if required
+   variable argument_dialogbox; # if required
+   switch $Command {
+      "create" <CreateCommandSequence>
+      "set_choice" <SetChoiceCommandSequence>
+      "set" <SetCommandv>
+      "get" <GetCommandSequence>
+   }
+}
+

Argument_dialogbox takes care about the -label and -text attributes for all entry widgets. For any data entry widget it creates a frame into which the data entry widget components can be placed. The path to this frame is provided via the W argument.

+

The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument Command:

+
+
create
+

The entry widget is called a first time with the command create to build the data entry widget.

+

The frames that are made available by argument_dialogbox for the entry widgets are by default only extendable in the X direction. To make them also extendable in the Y direction, for example for extendable list boxes, the command ad_form(make_expandable) $W has to be executed when an entry widget is built.

+
set_choice
+

The entry widget procedure is only called with the set_choice command if the -choices or -choicevariable has been specified. The command is therefore only relevant for list and combo boxes.

+

The available selection list that is either specified with the -choices or -choicevariable attribute is provided via the Par argument to the entry widget procedure. This list can be used to initialize an available choice list.

+
set
+

If a default value is either defined via the -default attribute or via a preceding call the entry widget procedure is called with the set command. The argument Par contains in this case the value to which the entry widget has to be initialized.

+
get
+

The entry widget procedure's command get has to return the current value of the entry widget.

+
+

Eventually specified entry widget item attributes are available via the Option array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the upvar command.

+

There may be a need to store some information in a variable. The array variable argument_dialogbox has to be used for this purpose together with array indexes starting with "$W,", e.g. argument_dialogbox($W,values).

+

Examples of entry widget procedures are directly provided by the TEPAM package source file that specifies the standard entry widget procedures. The simplest procedure is the one for the basic entry widget:

+
proc tepam::ad_form(entry) {W Command {Par ""}} {
+   switch $Command {
+      "create" {pack [entry \$W.entry] -fill x \
+                        -expand yes -pady 4 -side left}
+      "set" {\$W.entry insert 0 $Par}
+      "get" {return [\$W.entry get]}
+   }
+}
+

It is also possible to relay on an existing entry widget procedure to derive a new, more specific one. The radiobox widget is used for example, to create a new entry widget that allows selecting either left, center or right. The original radiobox widget is called with the set_choice command immediately after the create command, to define the fixed list of selection options.

+
proc tepam::ad_form(rcl) {W Command {Par ""}} {
+   set Res [ad_form(radiobox) $W $Command $Par]
+   if {$Command=="create"} {
+      ad_form(radiobox) $W set_choice {left center right}
+   }
+   return $Res
+}
+

Please consult the TEPAM package source file to find additional and more complex examples of entry widget procedures.

+
+

VARIABLES

+

The argument_dialogbox is using two variables inside the namespace ::tepam:

+
+
argument_dialogbox
+

Application specific entry widget procedures can use this array variable to store their own data, using as index the widget path provided to the procedure, e.g. argument_dialogbox($W,<sub_index>).

+
last_parameters
+

This array variable is only used by an argument dialog box if its context has been specified via the -context attribute. The argument dialog box' position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time.

+

To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the last_parameter array variable contents in a configuration file which is loaded the next time an application is launched.

+
+
+ + +

Category

+

Argument entry form, mega widget

+
+ +
ADDED embedded/www/tcllib/files/modules/tepam/tepam_introduction.html Index: embedded/www/tcllib/files/modules/tepam/tepam_introduction.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tepam/tepam_introduction.html @@ -0,0 +1,364 @@ + +tepam - Tcl's Enhanced Procedure and Argument Manager + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tepam(n) 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

+
+ +

Description

+

This document is an informal introduction into TEPAM, the Tcl's Enhanced Procedure and Argument Manager. Detailed information to the TEPAM package is provided in the tepam::procedure and tepam::argument_dialogbox reference manuals.

+
+

OVERVIEW

+

This package provides a new Tcl procedure declaration syntax that simplifies the implementation of procedure subcommands and the handling of the different types of procedure arguments like flags or switches, options, unnamed arguments, optional and mandatory options and arguments, default values, etc. Procedure declarations can be enriched with detailed information about the procedure and its arguments. This information is used for the following purposes:

+

First of all, a preamble is added in front of the body of a procedure that is declared with TEPAM. This preamble calls an argument manager that that uses the provided information to check the validity of the argument types and values before the procedure body is executed. Then, the information is used to generate help and usage texts if requested, or to generate clear error message in case an argument validation fails. The information also allows generating automatically graphical forms that allows an interactive definition of all arguments, in case a procedure is called interactively. And finally, the additional information helps self-commenting in a clean way the declaration of a procedure and of all its arguments.

+

The graphical form generator that creates the necessary argument specification forms for the interactive procedure calls is also available for other purposes than for procedure argument specifications. It allows creating code efficiently complex parameter entry forms that are usable independently from TEPAM's new procedure definition method.

+

Here is a short overview about all major TEPAM features:

+
    +

  • New self-documenting procedure declaration syntax: The additional information to declare properly a procedure has not to be provided with additional statements, but can be added in a natural syntax directly into the procedure header.

    • +

  • Easy way to specify subcommands: A subcommand is declared like a procedure, simply with a procedure name composed by a base name followed by a subcommand name. Sub-subcommands are created identically using simply procedure names composed by 3 words.

    • +

  • Flexible usage of flags (switches), options (named arguments) and unnamed arguments. Option names are optionally automatically completed.

    • +

  • Support for default values, mandatory/optional options and arguments, choice lists, value ranges, multiple usable options/arguments.

    • +

  • Choice of a named arguments first, unnamed arguments later procedure calling style (typical for Tcl commands) or of an unnamed arguments first, named arguments later procedure calling style (typical for Tk commands).

    • +

  • In case the named arguments first, unnamed arguments later style (Tcl) is selected: Clear separation between options and arguments via the "--" flag. The unnamed arguments can optionally be accessed as options (named arguments).

    • +

  • Automatic type and value check before the procedure body is executed, taking into account validation ranges, choice lists and custom validation commands. Generation of clear error message if necessary.

    • +

  • Many predefined types exist (integer, boolean, double, color, file, font, ...). Other application specific types can easily be added.

    • +

  • Automatic help and usage text generation if a procedure is called with the -help flag.

    • +

  • Automatic generation of an interactive argument definition form, in case a procedure is called with the -interactive flag.

    • +

  • Procedure calls can be logged which is useful to get for interactively called procedures the command call lines.

    • +

  • Powerful and code efficient generation of complex parameter definition forms.

    • +
+
+

PROCEDURE DECLARATION

+

TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word proc, a procedure is declared with the TEPAM command procedure which takes as proc also 3 arguments: The procedure name, the procedure header and the procedure body.

+

The following example declares the subcommand message of the procedure display. This command has several named and unnamed arguments:

+
tepam::procedure {display message} {
+   -return            -
+   -short_description "Displays a simple message box"
+   -description       "This procedure allows displaying a configurable message box.
+   -args {
+      {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
+      {-font -type font -default {Arial 10 italic} -description "Message text font"}
+      {-level -type integer -optional -range {1 10} -description "Message level"}
+      {-fg -type color -default black -description "Message color"}
+      {-bg -type color -optional -description "Background color"}
+      {-no_border -type none -description "Use a splash window style (no border)"}
+      {-log_file -type file -optional -description "Optional message log file"}
+      {text -type string -multiple -description "Multiple text lines to display"}
+   }
+} {
+   puts "display message:"
+   foreach var {mtype font level fg bg no_border log_file text} {
+      if {[info exists $var]} {
+         puts  "  $var=[set $var]"
+      }
+   }
+}
+

A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the error.

+

As the example above shows, the TEPAM command procedure accepts subcommand definitions as procedure name and allows defining much more information than just the argument list inside the procedure header. The procedure body on the other hand is identical between a command declared with proc and a command declared with procedure.

+

The procedure header allows defining in addition to the arguments some procedure attributes, like a description, information concerning the return value, etc. This information is basically used for the automatic generation of comprehensive help and usage texts.

+

A list of argument definition statements assigned to the -args argument is defining the procedure arguments. Each argument definition statement starts with the argument name, optionally followed by some argument attributes.

+

Three types of arguments can be defined: Unnamed arguments, named arguments and flags. The distinction between the named and unnamed arguments is made by the first argument name character which is simply "-" for named arguments. A flag is defined as named argument that has the type none.

+

Named and unnamed arguments are mandatory, unless they are declared with the -optional flag and unless they have a default value specified with the -default option. Named arguments and the last unnamed argument can have the attribute -multiple, which means that they can be defined multiple times. The expected argument data type is specified with the -type option. TEPAM defines a large set of standard data types which can easily be completed with application specific data types.

+

The argument declaration order has only an importance for unnamed arguments that are by default parsed after the named arguments (Tcl style). A variable allows changing this behavior in a way that unnamed arguments are parsed first, before the named arguments (Tk style).

+
+

PROCEDURE HELP

+

The declared procedure can simply be called with the -help option to get the information about the usage of the procedure and its arguments:

+
display message -help
+  ->
+NAME
+      display message - Displays a simple message box
+SYNOPSYS
+      display message
+            [-mtype <mtype>] :
+               Message type, default: "Warning", choices: {Info Warning Error}
+            [-font <font>] :
+               Message text font, type: font, default: Arial 10 italic
+            [-level <level>] :
+               Message level, type: integer, range: 1..10
+            [-fg <fg>] :
+               Message color, type: color, default: black
+            [-bg <bg>] :
+               Background color, type: color
+            [-no_border ] :
+               Use a splash window style (no border)
+            [-log_file <log_file>] :
+               Optional message log file, type: file
+            <text> :
+               Multiple text lines to display, type: string
+DESCRIPTION
+      This procedure allows displaying a configurable message box.
+
+

PROCEDURE CALL

+

The specified procedure can be called in many ways. The following listing shows some valid procedure calls:

+
display message "The document hasn't yet been saved!"
+-> display message:
+     mtype=Warning
+     font=Arial 10 italic
+     fg=black
+     no_border=0
+     text={The document hasn't yet been saved!}
+ 
+display message -fg red -bg black "Please save first the document"
+-> display message:
+     mtype=Warning
+     font=Arial 10 italic
+     fg=red
+     bg=black
+     no_border=0
+     text={Please save first the document}
+ 
+display message -mtype Error -no_border "Why is here no border?"
+-> display message:
+     mtype=Error
+     font=Arial 10 italic
+     fg=black
+     no_border=1
+     text={Why is here no border?}
+ 
+display message -font {Courier 12} -level 10 \
+   "Is there enough space?" "Reduce otherwise the font size!"
+-> display message:
+     mtype=Warning
+     font=Courier 12
+     level=10
+     fg=black
+     no_border=0
+     text={Is there enough space?} {Reduce otherwise the font size!}
+

The next lines show how wrong arguments are recognized. The text argument that is mandatory is missing in the first procedure call:

+
display message -font {Courier 12}
+  -> display message: Required argument is missing: text
+

Only known arguments are accepted:

+
display message -category warning Hello
+  -> display message: Argument '-category' not known
+

Argument types are automatically checked and an error message is generated in case the argument value has not the expected type:

+
display message -fg MyColor "Hello"
+  -> display message: Argument 'fg' requires type 'color'. \ 
+            Provided value: 'MyColor'
+

Selection choices have to be respected ...

+
display message -mtype Fatal Hello
+  -> display message: Argument (mtype) has to be one of the \ 
+            following elements: Info, Warning, Error
+

... as well as valid value ranges:

+
display message -level 12 Hello
+  -> display message: Argument (level) has to be between 1 and 10
+
+

INTERACTIVE PROCEDURE CALLS

+

The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively. This form will automatically be generated if the declared procedure is called with the -interactive flag.

+
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. TEPAM's provided argument dialog box allows crating complex parameter definition forms in a very efficient way.

+

The following example tries to illustrate the simplicity to create complex data entry forms. It creates an input mask that allows specifying a file to copy, a destination folder as well as a checkbox that allows specifying if an eventual existing file can be overwritten. Comfortable browsers can be used to select files and directories. And finally, the form offers also the possibility to accept and decline the selection. Here is the code snippet that is doing all this:

+
tepam::argument_dialogbox \
+   -existingfile {-label "Source file" -variable SourceFile} \
+   -existingdirectory {-label "Destination folder" -variable DestDir} \
+   -checkbutton {-label "Overwrite existing file" -variable Overwrite}
+

The argument_dialogbox returns ok if the entered data are validated. It will return cancel if the data entry has been canceled. After the validation of the entered data, the argument_dialogbox defines all the specified variables with the entered data inside the calling context.

+

An argument_dialogbox requires a pair of arguments for each variable that it has to handle. The first argument defines the entry widget type used to select the variable's value and the second one is a lists of attributes related to the variable and the entry widget.

+

Many entry widget types are available: Beside the simple generic entries, there are different kinds of list and combo boxes available, browsers for existing and new files and directories, check and radio boxes and buttons, as well as color and font pickers. If necessary, additional entry widgets can be defined.

+

The attribute list contains pairs of attribute names and attribute data. The primary attribute is -variable used to specify the variable in the calling context into which the entered data has to be stored. Another often used attribute is -label that allows adding a label to the data entry widget. Other attributes are available that allow specifying default values, the expected data types, valid data ranges, etc.

+

The next example of a more complex argument dialog box provides a good overview about the different available entry widget types and parameter attributes. The example contains also some formatting instructions like -frame and -sep which allows organizing the different entry widgets in frames and sections:

+
set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
+ 
+set Result [tepam::argument_dialogbox \
+   -title "System configuration" \
+   -context test_1 \
+   -frame {-label "Entries"} \
+      -entry {-label Entry1 -variable Entry1} \
+      -entry {-label Entry2 -variable Entry2 -default "my default"} \
+   -frame {-label "Listbox & combobox"} \
+      -listbox {-label "Listbox, single selection" -variable Listbox1 \
+                -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
+      -listbox {-label "Listbox, multiple selection" -variable Listbox2 
+                -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} 
+                -multiple_selection 1 -height 3} \
+      -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox 
+                        -choicevariable ChoiceList \
+                        -default {"Choice 3" "Choice 5"} -height 3} \
+      -combobox {-label "Combobox" -variable Combobox \
+                 -choices {1 2 3 4 5 6 7 8} -default 3} \
+   -frame {-label "Checkbox, radiobox and checkbutton"} \
+      -checkbox {-label Checkbox -variable Checkbox 
+                 -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
+                 -default italic} \
+      -radiobox {-label Radiobox -variable Radiobox 
+                 -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
+                 -default underline} \
+      -checkbutton {-label CheckButton -variable Checkbutton -default 1} \
+   -frame {-label "Files & directories"} \
+      -existingfile {-label "Input file" -variable InputFile} \
+      -file {-label "Output file" -variable OutputFile} \
+      -sep {} \
+      -existingdirectory {-label "Input directory" -variable InputDirectory} \
+      -directory {-label "Output irectory" -variable OutputDirectory} \
+   -frame {-label "Colors and fonts"} \
+      -color {-label "Background color" -variable Color -default red} \
+      -sep {} \
+      -font {-label "Font" -variable Font -default {Courier 12 italic}}]
+

The argument_dialogbox defines all the specified variables with the entered data and returns ok if the data have been validated via the Ok button. If the data entry is cancelled by activating the Cancel button, the argument_dialogbox returns cancel.

+
if {$Result=="cancel"} {
+   puts "Canceled"
+} else { # $Result=="ok"
+   puts "Arguments: "
+   foreach Var {
+      Entry1 Entry2
+      Listbox1 Listbox2 DisJntListbox 
+      Combobox Checkbox Radiobox Checkbutton
+      InputFile OutputFile InputDirectory OutputDirectory
+      Color Font
+   } {
+      puts "  $Var: '[set $Var]'"
+   }
+}
+-> Arguments:
+   Entry1: 'Hello, this is a trial'
+   Entry2: 'my default'
+   Listbox1: '1'
+   Listbox2: '{Choice 2} {Choice 3}'
+   DisJntListbox: '{Choice 3} {Choice 5}'
+   Combobox: '3'
+   Checkbox: 'italic'
+   Radiobox: 'underline'
+   Checkbutton: '1'
+   InputFile: 'c:\tepam\in.txt'
+   OutputFile: 'c:\tepam\out.txt'
+   InputDirectory: 'c:\tepam\input'
+   OutputDirectory: 'c:\tepam\output'
+   Color: 'red'
+   Font: 'Courier 12 italic'
+
+ + +

Category

+

Procedures, arguments, parameters, options

+
+ +
ADDED embedded/www/tcllib/files/modules/tepam/tepam_procedure.html Index: embedded/www/tcllib/files/modules/tepam/tepam_procedure.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tepam/tepam_procedure.html @@ -0,0 +1,802 @@ + +tepam::procedure - Tcl's Enhanced Procedure and Argument Manager + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tepam::procedure(n) 0.4.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam::procedure - TEPAM procedure, reference manual

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require tepam ?0.4?
    • +
+ +
+
+

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's 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's 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.

+

This is the usual Tcl style (exceptions exist) which is referred in the TEPAM documentation as named arguments first, unnamed arguments later style.

+
Unnamed arguments first, named arguments later
+

In contrast to most Tcl commands, Tk uses generally (exceptions exist also here) a different calling style where the unnamed arguments have to be provided first, before the named arguments have to be provided:

+
pack .ent1 .ent2 -fill x -expand yes -side left
+

This style is referred in the TEPAM documentation as unnamed arguments first, named arguments later style.

+
+
+

PROCEDURE DECLARATION

+

TEPAM allows declaring new Tcl procedures with the command tepam::procedure that has similar to the standard Tcl command proc also 3 arguments:

+
+
tepam::procedure name attributes body
+
+
+

The TEPAM procedure declaration syntax is demonstrated by the following example:

+
tepam::procedure {display message} {
+   -short_description
+      "Displays a simple message box"
+   -description
+      "This procedure allows displaying a configurable\
+       message box. The default message type that is\
+       created is a warning, but also errors and info can\
+       be generated.
+       The procedure accepts multiple text lines."
+   -example
+      {display message -mtype Warning "Save first your job"}
+   -args {
+      {-mtype -choices {Info Warning Error} \
+              -default Warning -description "Message type"}
+      {text   -type string -multiple \
+              -description "Multiple text lines to display"}
+   }
+} {
+   puts "Message type: $mtype"
+   puts "Message: $text"
+}
+

The 3 arguments of procedure are:

+
+
name
+

The procedure name can be used in very flexible ways. Procedure names can have namespace qualifiers. By providing a two element name list as procedure name, a subcommand of a procedure will be declared. It is even possible to declare sub-sub-commands of a procedure by providing name lists with three elements.

+

Here are some valid procedure declarations using different procedure names (the attribute and body arguments are empty for simplicity):

+
# Simple procedure name:
+tepam::procedure display_message {} {}
+
+# Procedure declared in the main namespace:
+tepam::procedure ::display_message {} {}
+
+# Procedure in the namespace ::ns:
+tepam::procedure ::ns::display_message {} {}
+
+# Declaration of the subcommand message of the procedure display:
+tepam::procedure {display message} {} {}
+
+
attributes
+

All procedure attributes are provided in form of an option list that contains pairs of option names and option values. The example above has as procedure attribute a short and a normal description, but also the procedure arguments are defined in form of a procedure attribute.

+

Most procedure attributes are providing information for documentation purposes. But some of them affect also the way how the procedure can be called. The section Procedure Attributes discusses in detail the available procedure attributes.

+

The procedure arguments are defined in form of a special procedure attribute. Most of the information provided in the argument definition is not just used for documentation purposes. This information is in fact used by the TEPAM argument manager to handle and validate the various forms of arguments that are provided during the procedure calls. The section Argument Declaration discusses in detail all the argument definition attributes.

+
body
+

This is the normal procedure body. The declared arguments will be available to the procedure body in form of variables.

+

The procedure body will only be executed if the provided set of arguments could be validated by the TEPAM argument manager.

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -default Warning -choices {Warning Error}}
+      {text -type string}
+   }
+} {
+   puts "Message type: $mtype"
+   puts "Message: $text"
+}
+
+
+

The commands procedure as well as argument_dialogbox are exported from the namespace tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to import them into the main namespace:

+
namespace import tepam::*
+ 
+procedure {display_message} {
+   -args {
+      ...
+

Procedure Attributes

+

The first group of procedure attributes is not affecting the behavior of the declared procedure. These attributes are 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.

+
+

The following attributes are not relevant for the documentation and help text generation, but they 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 procedure's -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's 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 procedure's -args attribute.

+

The argument definition syntax will be described more in detail in the following sub section.

+
+

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).

+
+
+

Argument Declaration

+

The following example shows the structure that is used for the argument definitions in the context of a procedure declaration:

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
+      {-font -type font -default {Arial 10 italic} -description "Message text font"}
+      {-level -type integer -optional -range {1 10} -description "Message level"}
+      {-fg -type color -optional -description "Message color"}
+      {-log_file -type file -optional -description "Optional message log file"}
+      {text -type string -multiple -description "Multiple text lines to display"}
+   }
+} {
+}
+

Each of the procedure arguments is declared with a list that has as first element the argument name, followed by eventual attributes. The argument definition syntax can be formalized in the following way:

+
tepam::procedure <name> {
+   -args {
+      {<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> \ 
+                         <arg_attr_name_1b> <arg_attr_value_1b> ...}
+      {<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> \ 
+                         <arg_attr_name_2b> <arg_attr_value_2b> ...}
+      ...
+   }
+} <body>
+

The argument names and attributes have to be used in the following way:

+
+
Argument name (<argument_name_<n>>)
+

The provided argument name specifies whether the argument is an unnamed argument or a named argument. In addition to this, an argument name can also be blank to indicate an argument comment, or it can start with # to indicate a section comment.

+
+
"<Name>"
+

This is the simplest form of an argument name: An argument whose name is not starting with '-' is an unnamed argument. The parameter provided during a procedure call will be assigned to a variable with the name <Name>.

+
tepam::procedure {print_string} {
+   -args {
+      {text -type string -description "This is an unnamed argument"}
+   }
+} {
+   puts $text
+}
+print_string "Hello"
+ -> Hello
+
+
"-<Name>"
+

An argument whose name starts with '-' is a named argument (also called option). The parameter provided during a procedure call will be assigned to a variable with the name <Name> (not -<Name>).

+
tepam::procedure {print_string} {
+   -args {
+      {-text -type string -description "This is a named argument"}
+   }
+} {
+   puts $text
+}
+print_string -text "Hello"
+ -> Hello
+
+
"--"
+

This flag allows clearly specifying the end of the named arguments and the beginning of the unnamed arguments, in case the named arguments first, unnamed arguments later style (Tcl) has been selected.

+

If the unnamed arguments first, named arguments later style (Tk) style is selected, this flag is ignored if the unnamed arguments have already been parsed. Otherwise it will be assigned to the corresponding unnamed argument.

+
"-" or ""
+

A blank argument name (either '-' or '') starts a comment for the following arguments.

+
tepam::procedure {print_time} {
+   -interactive_display_format short
+   -args {
+      {hours -type integer -description "Hour"}
+      {minutes -type integer -description "Minute"}
+ 
+      {- The following arguments are optional:}
+      {seconds -type integer -default 0 -description "Seconds"}
+      {milliseconds -type integer -default 0 -description "Milliseconds"}
+   }
+} {
+   puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
+}
+

Argument comments are basically used in the graphical argument definition forms that are created if a procedure is called interactively.

+
"#*"
+

An argument definition list that starts with '#' is considered as a section comment. The argument definition list will be trimmed from the '#' characters and the remaining string will be used as section comment.

+

Section comments can be used to structure visually the argument definition code. Section comments are also used to structure the generated help texts and the interactive argument definition forms.

+
tepam::procedure {complex_multiply} {
+   -description "This function perform a complex multiplication"
+   -args {
+      {#### First complex number ####}
+      {-r0 -type double -description "First number's real part"}
+      {-i0 -type double -description "First number's imaginary part"}
+      
+      {#### Second complex number ####}
+      {-r1 -type double -description "Second number's real part"}
+      {-i1 -type double -description "Second number's imaginary part"}
+   }
+} {
+   return [expr $r0*$r1 - $i0*$i1]
+}
+
+
+
Argument attributes (<arg_attr_name_<mn>> <arg_attr_value_<mn>>)
+

The following argument attributes are supported:

+
+
-description string
+

The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument.

+
-type type
+

The type argument attribute allows assigning the argument either to a predefined data type, or to an application specific data type. The argument values that are provided during a procedure call are automatically checked with respect to the defined argument type.

+

The section ARGUMENT TYPES provides a list of predefined data types and explains how application specific types can be specified.

+

The argument type none has a special meaning. An argument that has the type none is handled as a flag. A flag is always optional and its related variable contains the logical value 1 if the flag has been defined during the procedure call, or otherwise 0.

+
-default value
+

Eventual default values can be defined with the -default argument attribute. Arguments with default values are automatically optional arguments.

+
-optional|-mandatory
+

Arguments are by default mandatory, unless a default value is defined. The flag -optional transforms an argument into an optional argument.

+

In case an optional argument is not defined during a procedure call, the corresponding variable will not be defined. +The flag -mandatory is the opposite to -optional. This flag exists only for completion reason, since an argument is anyway mandatory by default.

+
-multiple
+

Arguments that have the -multiple attribute can be defined multiple times during a procedure call. The values that are provided during a procedure call for such an argument are stored in a list variable. This is even the case if such an argument is only defined once during a procedure call.

+

The -multiple attribute can be attributed to unnamed arguments and to named arguments. The pair of argument name/argument value has to be repeated for each provided value in case of a named argument. +In case the argument with the -multiple attribute is an unnamed argument, this one has to be the absolute last one of all unnamed arguments.

+
-choices list
+

A possible set of valid argument values can be attributed to an argument via the -choices attribute. The argument value provided during a procedure call will be checked against the provided choice values.

+
-choicelabels list
+

An eventual short description can be attributed to each choice option with the -choicelabels attribute. These descriptions will be used in the generated help texts and as radio and check box labels for the interactive calls.

+

The -choicelabels attribute is optional, but if it is defined, its list needs to have the identical size as the -choices argument list.

+
-range {double double}
+

Another argument constraint can be defined with the -range attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. The -range attribute has to be used only for numerical arguments, like integers and doubles.

+
-validatecommand script
+

Eventual more complex argument value validations can be performed via specific validation commands that are assigned to 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. +An example of a validation command declaration is:

+
tepam::procedure {display_message} {
+   -args {
+      {text -type string -description "Message text" \ 
+            -validatecommand "IllegalWordDetector %P"}
+} {
+}
+
+
-widget string
+

The widgets that allow defining the different arguments in case of an interactive procedure call are normally selected automatically in function of the argument type. The -widget attribute allows specifying explicitly a certain widget type for an argument.

+
-auxargs list
+

In case a procedure is called interactively, additional argument attributes can be provided to the interactive argument definition form via the -auxargs attribute that is itself a list of attribute name/attribute value pairs:

+
-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \ 
+          -<arg_attr_name_1b> <arg_attr_value_1b>
+          ...
+}
+

For example, if a procedure takes as argument a file name it may be beneficial to specify the required file type for the interactive argument definition form. This information can be provided via the -auxargs attribute to the argument definition form:

+
tepam::procedure LoadPicture {
+   -args {
+      {FileName -type existingfile -description "Picture file" \ 
+                 -auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}
+   }
+} {
+}
+
+
-auxargs_commands script
+

If the auxiliary argument attributes are not static but have to be dynamically adaptable, the -auxargs_commands allows defining them via commands that are executed during a procedure call. A list of pairs of auxiliary attribute names and commands has to be provided to the -auxargs_commands attribute. The provided commands are executed in the context of the calling procedure.

+
-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \ 
+                   -<arg_attr_name_1b> <arg_attr_command_1b>
+                   ...
+}
+
+
+
+
+
+

VARIABLES

+

Several variables defined inside the ::tepam namespace are impacting the mode of operation of the procedures that have been declared with 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

+

A comprehensive set of procedure argument types that is already predefined by TEPAM can easily be completed with additional types that are required for a specific application.

+

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 exception 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 blank type.

    • +
+

Several numerical types are defined by TEPAM. The type validation procedures are using the string is <type> -strict commands to check the validity of the provided arguments, which assures that no empty strings are accepted as argument value. The type validation expression for the numerical types and the argument types to which this expression is applied are:

+
string is <type_to_check> -strict <argument_value>
+
    +

  • boolean

    • +

  • integer

    • +

  • double

    • +
+

Empty strings are accepted as argument value for all the alpha numeric argument types. The argument types that are falling into this category and validation expression used for them are:

+
string is <type_to_check> <argument_value>
+
    +

  • alnum

    • +

  • alpha

    • +

  • ascii

    • +

  • control

    • +

  • digit

    • +

  • graph

    • +

  • lower

    • +

  • print

    • +

  • punct

    • +

  • space

    • +

  • upper

    • +

  • wordchar

    • +

  • xdigit

    • +
+

In addition to the data types checked with the string is <type> commands, TEPAM specifies some other useful data types:

+
    +

  • char

    +

    Each string that has a length of 1 character meets the character type. The type check is made with the following expression:

    +
    expr [string length <argument_value>]==1
    +
    • +

  • color

    +

    Any character strings that are accepted by Tk as a color are considered as valid color argument. Please note that the Tk package has to be loaded to use the type color. TEPAM is using the following command to validate the color type:

    +
    expr ![catch {winfo rgb . <argument_value>}]
    +
    • +

  • font

    +

    Any character strings that are accepted by Tk as a font are considered as valid font argument. Please note that the Tk package has to be loaded to use the font type. TEPAM is using the following command to validate the color type:

    +
    expr ![catch {font measure <argument_value> ""}]
    +
    • +

  • file

    +

    Any strings that are not containing one of the following characters are considered as valid file names: * ? " < >. It is not necessary that the file and its containing directory exist. Zero-length strings are not considered as valid file names.

    +

    The following expression is used to validate the file names:

    +
    expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]
    +
    • +

  • existingfile

    +

    The argument is valid if it matches with an existing file. The following check is performed to validate the arguments of this type:

    +
    file exists <argument_value>
    +
    • +

  • directory

    +

    The directory argument is validated exactly in the same way as the file arguments.

    • +

  • existingdirectory

    +

    The argument is valid if it matches with an existing directory. The following check is performed to validate the arguments of this type:

    +
    file isdirectory <argument_value>
    +
    • +
+
+

Defining Application Specific Argument Types

+

To add support for a new application specific argument type it is just necessary to add into the namespace tepam a validation function Validation(<type>). This function requires one argument. It has to returns 1 if the provided argument matches with the relevant data type. The function has to return otherwise 0.

+

The validation command section of the "tepam.tcl" package provides sufficient examples of validation functions, since it implements the ones for the standard TEPAM types.

+

The following additional code snippet shows the validation function for a custom argument type that requires values that have a character string length of exactly 2:

+
proc tepam::Validate(two_char) {v} {expr [string length $v]==2}
+
+
+

PROCEDURE CALLS

+

Help

+

Each procedure can be called with the -help flag. The procedure will then print a generated help text to stdout and will then return without performing any additional actions.

+

Taking the first procedure declared in PROCEDURE CALLS, the help request and the printed help text would be:

+
display message -help
+->
+NAME
+      display message - Displays a simple message box
+SYNOPSIS
+      display message
+            [-mtype <mtype>]
+               Message type, default: "Warning", choices: {Info, Warning, Error}
+            <text>
+               Multiple text lines to display, type: string
+DESCRIPTION
+      This procedure allows displaying a configurable message box. The default
+      message type that is created is a warning, but also errors and info can
+      be generated.
+      The procedure accepts multiple text lines.
+EXAMPLE
+      display message -mtype Warning "Save first your job"
+

The argument manager is checking if the last provided argument is -help and generates the requested help message if this is the case. So, also the following example will print the help message:

+
display message -mtype Info "It is 7:00" -help
+

On the other hand, the following call will result in an error:

+
display message -help -mtype Info "It is 7:00"
+->
+display message: Argument '-help' not known
+
+

Interactive Procedure Call

+

Calling a procedure with the -interactive flag will open a graphical form that allows specifying interactively all procedure arguments. The Tk library has to be loaded to use the interactive call. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in PROCEDURE CALLS:

+
package require Tk
+display message -interactive
+

Also the -interactive flag has to be placed at the last argument position as this is also required for the -help flag. Arguments defined before the -interactive flag will be ignored. The following example is therefore also a valid interactive procedure call:

+
display message -mtype Info "It is 7:00" -interactive
+
+

Unnamed Arguments

+

Unnamed arguments are typically provided to the called procedure as simple parameters. This procedure calling form requires that the provided arguments are strictly following the order of the specified arguments. Several parameters can be assigned to the last argument if this one has the -multiple attribute. So, the following declared procedure ...

+
tepam::procedure {display_message} {
+   -args {
+      {mtype -choices {Info Warning Error}}
+      {text -type string -multiple}
+   }
+} {
+   puts "$mtype: [join $text]"
+}
+

... can for example be called in the following ways:

+
display_message Info "It is PM 7:00."
+-> Info: It is PM 7:00.
+ 
+display_message Info "It is PM 7:00." "You should go home."
+-> Info: It is PM 7:00. You should go home.
+

The nice thing is that unnamed arguments can also be called as named arguments, which can be handy, for example if the exact specified argument order is not known to a user:

+
display_message -mtype Info -text "It is PM 7:00."
+-> Info: It is PM 7:00.
+ 
+display_message -text "It is PM 7:00." -mtype Info
+-> Info: It is PM 7:00.
+ 
+display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
+-> Info: It is PM 7:00. You should go home.
+ 
+display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
+-> Info: It is PM 7:00. You should go home.
+
+

Named Arguments

+

Named arguments have to be provided to a procedure in form of a parameter pairs composed by the argument names and the argument values. The order how they are provided during a procedure call is irrelevant and has not to match with the argument specification order.

+

The following declared procedure ...

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -choices {Info Warning Error}}
+      {-text -type string -multiple}
+   }
+} {
+   puts "$mtype: [join $text]"
+}
+

... can be called in the following ways:

+
display_message -mtype Info -text "It is PM 7:00."
+-> Info: It is PM 7:00.
+ 
+display_message -text "It is PM 7:00." -mtype Info
+-> Info: It is PM 7:00.
+ 
+display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
+-> Info: It is PM 7:00. You should go home.
+ 
+display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
+-> Info: It is PM 7:00. You should go home.
+

Also named arguments that have not the -multiple attribute can be provided multiple times. Only the last provided argument will be retained in such a case:

+
display_message -mtype Info -text "It is PM 7:00." -mtype Warning
+-> Warning: It is PM 7:00.
+
+

Unnamed Arguments First, Named Arguments Later (Tk Style)

+

A procedure that has been defined while the variable tepam::named_arguments_first was set to 1, or with the procedure attribute -named_arguments_first set to 1 has to be called in the Tcl style. The following procedure declaration will be used in this section to illustrate the meaning of this calling style:

+
set tepam::named_arguments_first 1
+tepam::procedure my_proc {
+   -args {
+      {-n1 -default ""}
+      {-n2 -default ""}
+      {u1 -default ""}
+      {u2 -default ""}
+   }
+} {
+   puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
+}
+

The unnamed arguments are placed at the end of procedure call, after the named arguments:

+
my_proc -n1 N1 -n2 N2 U1 U2
+-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'
+

The argument parser considers the first argument that doesn't start with the '-' character as well as all following arguments as unnamed argument:

+
my_proc U1 U2
+-> n1:'', n2:'', u1:'U1', u2:'U2'
+

Named arguments can be defined multiple times. If the named argument has the -multiply attribute, all argument values will be collected in a list. Otherwise, only the last provided attribute value will be retained:

+
my_proc -n1 N1 -n2 N2 -n1 M1 U1 U2
+-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'
+

The name of the first unnamed argument has therefore not to start with the '-' character. The unnamed argument is otherwise considered as name of another named argument. This is especially important if the first unnamed argument is given by a variable that can contain any character strings:

+
my_proc -n1 N1 -n2 N2 "->" "<-"
+-> my_proc: Argument '->' not known
+ 
+set U1 "->"
+my_proc -n1 N1 -n2 N2 $U1 U2}]
+my_proc: Argument '->' not known
+

The '--' flag allows separating unambiguously the unnamed arguments from the named arguments. All data after the '--' flag will be considered as unnamed argument:

+
my_proc -n1 N1 -n2 N2 -- "->" "<-"
+-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
+ 
+set U1 "->"
+my_proc -n1 N1 -n2 N2 -- $U1 U2
+-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
+
+

Named Arguments First, Unnamed Arguments Later (Tcl Style)

+

The Tk calling style will be chosen if a procedure is defined while the variable tepam::named_arguments_first is set to 0, or if the procedure attribute -named_arguments_first has been set to 0. The following procedure will be used in this section to illustrate this calling style:

+
set tepam::named_arguments_first 0
+tepam::procedure my_proc {
+   -args {
+      {-n1 -default ""}
+      {-n2 -default ""}
+      {u1}
+      {u2 -default "" -multiple}
+   }
+} {
+   puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
+}
+

The unnamed arguments have to be provided first in this case. The named arguments are provided afterwards:

+
my_proc U1 U2 -n1 N1 -n2 N2
+-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'
+

The argument parser will assign to each defined unnamed argument a value before it switches to read the named arguments. This default behavior changes a bit if there are unnamed arguments that are optional or that can take multiple values.

+

An argument value will only be assigned to an unnamed argument that is optional (that has either the -optional attribute or that has a default value), if the value is not beginning with the '-' character or if no named arguments are defined. The value that starts with '-' is otherwise considered as the name of a named argument.

+

Argument values are assigned to an argument that has the -multiple attribute as long as the parameter value doesn't starts with the '-' character.

+

Values that start with the '-' character can therefore not be assigned to optional unnamed arguments, which restricts the usage of the Tcl procedure calling style. The Tk style may be preferable in some cases, since it allows separating unambiguously the named arguments from the unnamed ones with the '--' flag.

+

Let's explore in a bit less theoretically the ways how the previously defined procedure can be called: The first example calls the procedure without any parameters, which leads to an error since u1 is a mandatory argument:

+
my_proc
+-> my_proc: Required argument is missing: u1
+

The procedure call is valid if one parameter is provided for u1:

+
my_proc U1
+-> n1:'', n2:'', u1:'U1', u2:''
+

If more parameters are provided that are not starting with the '-' character, they will be attributed to the unnamed arguments. U2 will receive 3 of these parameters, since it accepts multiple values:

+
my_proc U1 U2 U3 U4
+-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'
+

As soon as one parameter starts with '-' and all unnamed arguments have been assigned, the argument manager tries to interpret the parameter as name of a named argument. The procedure call will fail if a value beginning with '-' is assigned to an unnamed argument:

+
my_proc U1 U2 U3 U4 -U5
+-> my_proc: Argument '-U5' not known
+

The attribution of a parameter to a named argument will fail if there are undefined unnamed (non optional) arguments. The name specification will in this case simply be considered as a parameter value that is attributed to the next unnamed argument. This was certainly not the intention in the following example:

+
my_proc -n1 N1
+-> n1:'', n2:'', u1:'-n1', u2:'N1'
+

The situation is completely different if values have already been assigned to all mandatory unnamed arguments. A parameter beginning with the '-' character will in this case be considered as a name identifier for a named argument:

+
my_proc U1 -n1 N1
+-> n1:'N1', n2:'', u1:'U1', u2:''
+

No unnamed arguments are allowed behind the named arguments:

+
my_proc U1 -n1 N1 U2
+-> my_proc: Argument 'U2' is not an option
+

The '--' flag has no special meaning if not all mandatory arguments have got assigned a value. This flag will simply be attributed to one of the unnamed arguments:

+
my_proc -- -n1 N1
+-> n1:'N1', n2:'', u1:'--', u2:''
+

But the '--' flag is simply ignored if the argument parser has started to handle the named arguments:

+
my_proc U1 -- -n1 N1
+-> n1:'N1', n2:'', u1:'U1', u2:''
+ 
+my_proc U1 -n1 N1 -- -n2 N2
+-> n1:'N1', n2:'N2', u1:'U1', u2:''
+
+

Raw Argument List

+

It may be necessary sometimes that the procedure body is able to access the entire list of arguments provided during a procedure call. This can happen via the args variable that contains always the unprocessed argument list:

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -choices {Warning Error} -default Warning}
+      {text -type string -multiple}
+   }
+} {
+   puts "args: $args"
+}
+display_message -mtype Warning "It is 7:00"
+-> args: -mtype Warning {It is 7:00}
+
+
+ + +

Category

+

Procedures, arguments, parameters, options

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cattr.html Index: embedded/www/tcllib/files/modules/term/ansi_cattr.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_cattr.html @@ -0,0 +1,288 @@ + + +term::ansi::code::attr - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::code::attr(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code::attr - ANSI attribute sequences

+
+ + +

Description

+

This package provides symbolic names for the ANSI attribute control +codes. For each control code a single command is provided which +returns this code as its result. None of the commands of this package +write to a channel; that is handled by higher level packages, like +term::ansi::send.

+
+

API

+

Introspection

+
+
::term::ansi::code::attr::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::attr::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace attr. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Attributes

+
+
::term::ansi::code::attr::fgblack
+

Set text color to Black.

+
::term::ansi::code::attr::fgred
+

Set text color to Red.

+
::term::ansi::code::attr::fggreen
+

Set text color to Green.

+
::term::ansi::code::attr::fgyellow
+

Set text color to Yellow.

+
::term::ansi::code::attr::fgblue
+

Set text color to Blue.

+
::term::ansi::code::attr::fgmagenta
+

Set text color to Magenta.

+
::term::ansi::code::attr::fgcyan
+

Set text color to Cyan.

+
::term::ansi::code::attr::fgwhite
+

Set text color to White.

+
::term::ansi::code::attr::fgdefault
+

Set default text color (Black).

+
::term::ansi::code::attr::bgblack
+

Set background to Black.

+
::term::ansi::code::attr::bgred
+

Set background to Red.

+
::term::ansi::code::attr::bggreen
+

Set background to Green.

+
::term::ansi::code::attr::bgyellow
+

Set background to Yellow.

+
::term::ansi::code::attr::bgblue
+

Set background to Blue.

+
::term::ansi::code::attr::bgmagenta
+

Set background to Magenta.

+
::term::ansi::code::attr::bgcyan
+

Set background to Cyan.

+
::term::ansi::code::attr::bgwhite
+

Set background to White.

+
::term::ansi::code::attr::bgdefault
+

Set default background (Transparent).

+
::term::ansi::code::attr::bold
+

Bold on.

+
::term::ansi::code::attr::dim
+

Dim on.

+
::term::ansi::code::attr::italic
+

Italics on.

+
::term::ansi::code::attr::underline
+

Underscore on.

+
::term::ansi::code::attr::blink
+

Blink on.

+
::term::ansi::code::attr::revers
+

Reverse on.

+
::term::ansi::code::attr::hidden
+

Hidden on.

+
::term::ansi::code::attr::strike
+

Strike-through on.

+
::term::ansi::code::attr::nobold
+

Bold off.

+
::term::ansi::code::attr::noitalic
+

Italics off.

+
::term::ansi::code::attr::nounderline
+

Underscore off.

+
::term::ansi::code::attr::noblink
+

Blink off.

+
::term::ansi::code::attr::norevers
+

Reverse off.

+
::term::ansi::code::attr::nohidden
+

Hidden off.

+
::term::ansi::code::attr::nostrike
+

Strike-through off.

+
::term::ansi::code::attr::reset
+

Reset all attributes to their default values.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cctrl.html Index: embedded/www/tcllib/files/modules/term/ansi_cctrl.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_cctrl.html @@ -0,0 +1,468 @@ + + +term::ansi::code::ctrl - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::code::ctrl(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code::ctrl - ANSI control sequences

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::ansi::code ?0.1?
    • +
  • package require term::ansi::code::ctrl ?0.1.1?
    • +
+ +
+
+

Description

+

This package provides symbolic names for the ANSI control +sequences. For each sequence a single command is provided which +returns the sequence as its result. None of the commands of this +package write to a channel; that is handled by higher level packages, +like term::ansi::send.

+
+

API

+

Introspection

+
+
::term::ansi::code::ctrl::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::ctrl::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace ctrl. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Sequences

+
+
::term::ansi::code::ctrl::eeol
+

Erase (to) End Of Line

+
::term::ansi::code::ctrl::esol
+

Erase (to) Start Of Line

+
::term::ansi::code::ctrl::el
+

Erase (current) Line

+
::term::ansi::code::ctrl::ed
+

Erase Down (to bottom)

+
::term::ansi::code::ctrl::eu
+

Erase Up (to top)

+
::term::ansi::code::ctrl::es
+

Erase Screen

+
::term::ansi::code::ctrl::sd
+

Scroll Down

+
::term::ansi::code::ctrl::su
+

Scroll Up

+
::term::ansi::code::ctrl::ch
+

Cursor Home

+
::term::ansi::code::ctrl::sc
+

Save Cursor

+
::term::ansi::code::ctrl::rc
+

Restore Cursor (Unsave)

+
::term::ansi::code::ctrl::sca
+

Save Cursor + Attributes

+
::term::ansi::code::ctrl::rca
+

Restore Cursor + Attributes

+
::term::ansi::code::ctrl::st
+

Set Tab (@ current position)

+
::term::ansi::code::ctrl::ct
+

Clear Tab (@ current position)

+
::term::ansi::code::ctrl::cat
+

Clear All Tabs

+
::term::ansi::code::ctrl::qdc
+

Query Device Code

+
::term::ansi::code::ctrl::qds
+

Query Device Status

+
::term::ansi::code::ctrl::qcp
+

Query Cursor Position

+
::term::ansi::code::ctrl::rd
+

Reset Device

+
::term::ansi::code::ctrl::elw
+

Enable Line Wrap

+
::term::ansi::code::ctrl::dlw
+

Disable Line Wrap

+
::term::ansi::code::ctrl::eg
+

Enter Graphics Mode

+
::term::ansi::code::ctrl::lg
+

Exit Graphics Mode

+
::term::ansi::code::ctrl::scs0 tag
+

Set default character set

+
::term::ansi::code::ctrl::scs1 tag
+

Set alternate character set +Select Character Set.

+

Choose which character set is used for either default (scs0) or +alternate font (scs1). This does not change whether default or +alternate font are used, only their definition.

+

The legal tags, and their meanings, are:

+
+
A
+

United Kingdom Set

+
B
+

ASCII Set

+
0
+

Special Graphics

+
1
+

Alternate Character ROM Standard Character Set

+
2
+

Alternate Character ROM Special Graphics

+
+
::term::ansi::code::ctrl::sda arg...
+

Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package term::ansi::code::attr. For +convenience this package also provides additional commands each setting a single +specific attribute.

+
::term::ansi::code::ctrl::sda_fgblack
+

Set text color to Black.

+
::term::ansi::code::ctrl::sda_fgred
+

Set text color to Red.

+
::term::ansi::code::ctrl::sda_fggreen
+

Set text color to Green.

+
::term::ansi::code::ctrl::sda_fgyellow
+

Set text color to Yellow.

+
::term::ansi::code::ctrl::sda_fgblue
+

Set text color to Blue.

+
::term::ansi::code::ctrl::sda_fgmagenta
+

Set text color to Magenta.

+
::term::ansi::code::ctrl::sda_fgcyan
+

Set text color to Cyan.

+
::term::ansi::code::ctrl::sda_fgwhite
+

Set text color to White.

+
::term::ansi::code::ctrl::sda_fgdefault
+

Set default text color (Black).

+
::term::ansi::code::ctrl::sda_bgblack
+

Set background to Black.

+
::term::ansi::code::ctrl::sda_bgred
+

Set background to Red.

+
::term::ansi::code::ctrl::sda_bggreen
+

Set background to Green.

+
::term::ansi::code::ctrl::sda_bgyellow
+

Set background to Yellow.

+
::term::ansi::code::ctrl::sda_bgblue
+

Set background to Blue.

+
::term::ansi::code::ctrl::sda_bgmagenta
+

Set background to Magenta.

+
::term::ansi::code::ctrl::sda_bgcyan
+

Set background to Cyan.

+
::term::ansi::code::ctrl::sda_bgwhite
+

Set background to White.

+
::term::ansi::code::ctrl::sda_bgdefault
+

Set default background (Transparent).

+
::term::ansi::code::ctrl::sda_bold
+

Bold on.

+
::term::ansi::code::ctrl::sda_dim
+

Dim on.

+
::term::ansi::code::ctrl::sda_italic
+

Italics on.

+
::term::ansi::code::ctrl::sda_underline
+

Underscore on.

+
::term::ansi::code::ctrl::sda_blink
+

Blink on.

+
::term::ansi::code::ctrl::sda_revers
+

Reverse on.

+
::term::ansi::code::ctrl::sda_hidden
+

Hidden on.

+
::term::ansi::code::ctrl::sda_strike
+

Strike-through on.

+
::term::ansi::code::ctrl::sda_nobold
+

Bold off.

+
::term::ansi::code::ctrl::sda_noitalic
+

Italics off.

+
::term::ansi::code::ctrl::sda_nounderline
+

Underscore off.

+
::term::ansi::code::ctrl::sda_noblink
+

Blink off.

+
::term::ansi::code::ctrl::sda_norevers
+

Reverse off.

+
::term::ansi::code::ctrl::sda_nohidden
+

Hidden off.

+
::term::ansi::code::ctrl::sda_nostrike
+

Strike-through off.

+
::term::ansi::code::ctrl::sda_reset
+

Reset all attributes to their default values.

+
::term::ansi::send::fcp row col
+

Force Cursor Position (aka Go To).

+
::term::ansi::code::ctrl::cu ?n?
+

Cursor Up. n defaults to 1.

+
::term::ansi::code::ctrl::cd ?n?
+

Cursor Down. n defaults to 1.

+
::term::ansi::code::ctrl::cf ?n?
+

Cursor Forward. n defaults to 1.

+
::term::ansi::code::ctrl::cb ?n?
+

Cursor Backward. n defaults to 1.

+
::term::ansi::code::ctrl::ss ?s e?
+

Scroll Screen (entire display, or between rows start end, inclusive).

+
::term::ansi::code::ctrl::skd code str
+

Set Key Definition.

+
::term::ansi::code::ctrl::title str
+

Set the terminal title.

+
::term::ansi::code::ctrl::gron
+

Switch to character/box graphics. I.e. switch to the alternate font.

+
::term::ansi::code::ctrl::groff
+

Switch to regular characters. I.e. switch to the default font.

+
::term::ansi::code::ctrl::tlc
+

Character graphics, Top Left Corner.

+
::term::ansi::code::ctrl::trc
+

Character graphics, Top Right Corner.

+
::term::ansi::code::ctrl::brc
+

Character graphics, Bottom Right Corner.

+
::term::ansi::code::ctrl::blc
+

Character graphics, Bottom Left Corner.

+
::term::ansi::code::ctrl::ltj
+

Character graphics, Left T Junction.

+
::term::ansi::code::ctrl::ttj
+

Character graphics, Top T Junction.

+
::term::ansi::code::ctrl::rtj
+

Character graphics, Right T Junction.

+
::term::ansi::code::ctrl::btj
+

Character graphics, Bottom T Junction.

+
::term::ansi::code::ctrl::fwj
+

Character graphics, Four-Way Junction.

+
::term::ansi::code::ctrl::hl
+

Character graphics, Horizontal Line.

+
::term::ansi::code::ctrl::vl
+

Character graphics, Vertical Line.

+
::term::ansi::code::ctrl::groptim str
+

Optimize character graphics. The generator commands above create way to many +superfluous commands shifting into and out of the graphics mode. This command +removes all shifts which are not needed. To this end it also knows which +characters will look the same in both modes, to handle strings created outside +of this package.

+
::term::ansi::code::ctrl::clear
+

Clear screen. In essence a sequence of CursorHome + EraseDown.

+
::term::ansi::code::ctrl::init
+

Initialize default and alternate fonts to ASCII and box graphics.

+
::term::ansi::code::ctrl::showat row col text
+

Format the block of text for display at the specified location.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cmacros.html Index: embedded/www/tcllib/files/modules/term/ansi_cmacros.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_cmacros.html @@ -0,0 +1,197 @@ + + +term::ansi::code::macros - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::code::macros(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code::macros - Macro sequences

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require textutil::repeat
    • +
  • package require textutil::tabify
    • +
  • package require term::ansi::code::macros ?0.1?
    • +
+ +
+
+

Description

+

This package provides higher level control sequences for more complex +shapes.

+
+

API

+

Introspection

+
+
::term::ansi::code::macros::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::macros::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace macros. Note that +this is relative namespace name, placing the imported command into a +child of the current namespace. By default all commands are imported, +this can howver be restricted by listing the names of the wanted +commands after the namespace argument.

+
+
+

Sequences

+
+
::term::ansi::code::macros::menu menu
+

The description of a menu is converted into a formatted rectangular +block of text, with the menu command characters highlighted using bold +red text. The result is returned as the result of the command.

+

The description, menu, is a dictionary mapping from menu label +to command character.

+
::term::ansi::code::macros::frame string
+

The paragraph of text contained in the string is padded with spaces at +the right margin, after normalizing internal tabs, and then put into a +frame made of box-graphics. The result is returned as the result of +the command.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_code.html Index: embedded/www/tcllib/files/modules/term/ansi_code.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_code.html @@ -0,0 +1,173 @@ + + +term::ansi::code - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::code(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code - Helper for control sequences

+
+ + +

Description

+

This package provides commands enabling the definition of control +sequences in an easy manner.

+
+
::term::ansi::code::esc str
+

This command returns the argument string, prefixed with the ANSI +escape character, "\033."

+
::term::ansi::code::escb str
+

This command returns the argument string, prefixed with a common ANSI +escape sequence, "\033[".

+
::term::ansi::code::define name escape code
+

This command defines a procedure name which returns the control +sequence code, beginning with the specified escape sequence, +either esc, or escb.

+
::term::ansi::code::const name code
+

This command defines a procedure name which returns the control +sequence code.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_ctrlu.html Index: embedded/www/tcllib/files/modules/term/ansi_ctrlu.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_ctrlu.html @@ -0,0 +1,205 @@ + + +term::ansi::ctrl::unix - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::ctrl::unix(n) 0.1.1 tcllib "Terminal control"

+

Name

+

term::ansi::ctrl::unix - Control operations and queries

+
+ + +

Description

+

WARNING: This package is unix-specific and depends on the +availability of two unix system commands for terminal control, +i.e. stty and tput, both of which have to be found +in the $PATH. If any of these two commands is missing the +loading of the package will fail.

+

The package provides commands to switch the standard input of the +current process between raw and cooked input modes, and +to query the size of terminals, i.e. the available number of columns +and lines.

+
+

API

+

Introspection

+
+
::term::ansi::ctrl::unix::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace ctrl. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Operations

+
+
::term::ansi::ctrl::unix::raw
+

This command switches the standard input of the current process to +raw input mode. This means that from then on all characters +typed by the user are immediately reported to the application instead +of waiting in the OS buffer until the Enter/Return key is received.

+
::term::ansi::ctrl::unix::raw
+

This command switches the standard input of the current process to +cooked input mode. This means that from then on all characters +typed by the user are kept in OS buffers for editing until the +Enter/Return key is received.

+
::term::ansi::ctrl::unix::columns
+

This command queries the terminal connected to the standard input for +the number of columns available for display.

+
::term::ansi::ctrl::unix::rows
+

This command queries the terminal connected to the standard input for +the number of rows (aka lines) available for display.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_send.html Index: embedded/www/tcllib/files/modules/term/ansi_send.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ansi_send.html @@ -0,0 +1,452 @@ + + +term::ansi::send - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::ansi::send(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::send - Output of ANSI control sequences to terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::ansi::send ?0.1?
    • +
+ +
+
+

Description

+

This package provides commands to send ANSI terminal control sequences to a +terminal. All commands come in two variants, one for sending to any channel, +the other for sending to stdout.

+

The commands are defined using the control sequences provided by the package +term::ansi::code::ctrl. They have the same arguments as the commands +they are based on, with the exception of the variant for sending to any channel. +Their first argument is always a channel handle, then followed by the original +arguments. Below we will list only the variant sending to stdout.

+
+
::term::ansi::send::import ?ns? ...
+

Imports the commands of this package into the namespace ns. If not specified +it defaults to send. Note that this default is a relative namespace name, +i.e. the actual namespace will be created under the current namespace.

+

By default all commands will be imported, this can however be restricted to specific +commands, by listing them after the namespace to import them into.

+
::term::ansi::send::eeol
+

Erase (to) End Of Line.

+
::term::ansi::send::esol
+

Erase (to) Start Of Line.

+
::term::ansi::send::el
+

Erase (current) Line.

+
::term::ansi::send::ed
+

Erase Down (to bottom).

+
::term::ansi::send::eu
+

Erase Up (to top).

+
::term::ansi::send::es
+

Erase Screen.

+
::term::ansi::send::sd
+

Scroll Down.

+
::term::ansi::send::su
+

Scroll Up.

+
::term::ansi::send::ch
+

Cursor Home.

+
::term::ansi::send::sc
+

Save Cursor. Note: Only one saved position can be handled. +This is no unlimited stack. Saving before restoring will +overwrite the saved data.

+
::term::ansi::send::rc
+

Restore Cursor (Unsave).

+
::term::ansi::send::sca
+

Save Cursor + Attributes.

+
::term::ansi::send::rca
+

Restore Cursor + Attributes.

+
::term::ansi::send::st
+

Set Tab (@ current position).

+
::term::ansi::send::ct
+

Clear Tab (@ current position).

+
::term::ansi::send::cat
+

Clear All Tabs.

+
::term::ansi::send::qdc
+

Query Device Code.

+
::term::ansi::send::qds
+

Query Device Status.

+
::term::ansi::send::qcp
+

Query Cursor Position.

+
::term::ansi::send::rd
+

Reset Device.

+
::term::ansi::send::elw
+

Enable Line Wrap.

+
::term::ansi::send::dlw
+

Disable Line Wrap.

+
::term::ansi::send::eg
+

Enter Graphics Mode.

+
::term::ansi::send::lg
+

Exit Graphics Mode.

+
::term::ansi::send::scs0 tag
+
+
::term::ansi::send::scs1 tag
+

Select Character Set.

+

Choose which character set is used for default (scs0) and alternate font (scs1). +This does not change whether default or alternate font are used, just their +definitions.

+

The legal tags, and their meanings, are:

+
+
A
+

United Kingdom Set

+
B
+

ASCII Set

+
0
+

Special Graphics

+
1
+

Alternate Character ROM Standard Character Set

+
2
+

Alternate Character ROM Special Graphics

+
+
::term::ansi::send::sda arg...
+

Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package term::ansi::code::attr. For +convenience this package also provides additional commands each setting a single +specific attribute.

+
::term::ansi::send::sda_fgblack
+

Set text color to Black.

+
::term::ansi::send::sda_fgred
+

Set text color to Red.

+
::term::ansi::send::sda_fggreen
+

Set text color to Green.

+
::term::ansi::send::sda_fgyellow
+

Set text color to Yellow.

+
::term::ansi::send::sda_fgblue
+

Set text color to Blue.

+
::term::ansi::send::sda_fgmagenta
+

Set text color to Magenta.

+
::term::ansi::send::sda_fgcyan
+

Set text color to Cyan.

+
::term::ansi::send::sda_fgwhite
+

Set text color to White.

+
::term::ansi::send::sda_fgdefault
+

Set default text color (Black).

+
::term::ansi::send::sda_bgblack
+

Set background to Black.

+
::term::ansi::send::sda_bgred
+

Set background to Red.

+
::term::ansi::send::sda_bggreen
+

Set background to Green.

+
::term::ansi::send::sda_bgyellow
+

Set background to Yellow.

+
::term::ansi::send::sda_bgblue
+

Set background to Blue.

+
::term::ansi::send::sda_bgmagenta
+

Set background to Magenta.

+
::term::ansi::send::sda_bgcyan
+

Set background to Cyan.

+
::term::ansi::send::sda_bgwhite
+

Set background to White.

+
::term::ansi::send::sda_bgdefault
+

Set default background (Transparent).

+
::term::ansi::send::sda_bold
+

Bold on.

+
::term::ansi::send::sda_dim
+

Dim on.

+
::term::ansi::send::sda_italic
+

Italics on.

+
::term::ansi::send::sda_underline
+

Underscore on.

+
::term::ansi::send::sda_blink
+

Blink on.

+
::term::ansi::send::sda_revers
+

Reverse on.

+
::term::ansi::send::sda_hidden
+

Hidden on.

+
::term::ansi::send::sda_strike
+

Strike-through on.

+
::term::ansi::send::sda_nobold
+

Bold off.

+
::term::ansi::send::sda_noitalic
+

Italics off.

+
::term::ansi::send::sda_nounderline
+

Underscore off.

+
::term::ansi::send::sda_noblink
+

Blink off.

+
::term::ansi::send::sda_norevers
+

Reverse off.

+
::term::ansi::send::sda_nohidden
+

Hidden off.

+
::term::ansi::send::sda_nostrike
+

Strike-through off.

+
::term::ansi::send::sda_reset
+

Reset all attributes to their default values.

+
::term::ansi::send::fcp row col
+

Force Cursor Position (aka Go To).

+
::term::ansi::send::cu ?n?
+

Cursor Up. n defaults to 1.

+
::term::ansi::send::cd ?n?
+

Cursor Down. n defaults to 1.

+
::term::ansi::send::cf ?n?
+

Cursor Forward. n defaults to 1.

+
::term::ansi::send::cb ?n?
+

Cursor Backward. n defaults to 1.

+
::term::ansi::send::ss ?s e?
+

Scroll Screen (entire display, or between rows start end, inclusive).

+
::term::ansi::send::skd code str
+

Set Key Definition.

+
::term::ansi::send::title str
+

Set the terminal title.

+
::term::ansi::send::gron
+

Switch to character/box graphics. I.e. switch to the alternate font.

+
::term::ansi::send::groff
+

Switch to regular characters. I.e. switch to the default font.

+
::term::ansi::send::tlc
+

Character graphics, Top Left Corner.

+
::term::ansi::send::trc
+

Character graphics, Top Right Corner.

+
::term::ansi::send::brc
+

Character graphics, Bottom Right Corner.

+
::term::ansi::send::blc
+

Character graphics, Bottom Left Corner.

+
::term::ansi::send::ltj
+

Character graphics, Left T Junction.

+
::term::ansi::send::ttj
+

Character graphics, Top T Junction.

+
::term::ansi::send::rtj
+

Character graphics, Right T Junction.

+
::term::ansi::send::btj
+

Character graphics, Bottom T Junction.

+
::term::ansi::send::fwj
+

Character graphics, Four-Way Junction.

+
::term::ansi::send::hl
+

Character graphics, Horizontal Line.

+
::term::ansi::send::vl
+

Character graphics, Vertical Line.

+
::term::ansi::send::groptim str
+

Optimize character graphics. The generator commands above create way to many +superfluous commands shifting into and out of the graphics mode. This command +removes all shifts which are not needed. To this end it also knows which +characters will look the same in both modes, to handle strings created outside +of this package.

+
::term::ansi::send::clear
+

Clear screen. In essence a sequence of CursorHome + EraseDown.

+
::term::ansi::send::init
+

Initialize default and alternate fonts to ASCII and box graphics.

+
::term::ansi::send::showat row col text
+

Show the block of text at the specified location.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/imenu.html Index: embedded/www/tcllib/files/modules/term/imenu.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/imenu.html @@ -0,0 +1,258 @@ + + +term::interact::menu - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::interact::menu(n) 0.1 tcllib "Terminal control"

+

Name

+

term::interact::menu - Terminal widget, menu

+
+ + +

Description

+

This package provides a class for the creation of a simple menu +control.

+
+

Class API

+

The package exports a single command, the class command, enabling the +creation of menu instances. Its API is:

+
+
term::interact::menu object dict ?options...?
+

This command creates a new menu object with the name object, +initializes it, and returns the fully qualified name of the object +command as its result.

+

The argument is the menu to show, possibly followed by configuration +options and their values. The options are explained in the section +Configuration. The menu is a dictionary maping labels +to symbolic action codes.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object interact
+

Shows the menu in the screen at the configured location and starts +interacting with it. This opens its own event loop for the processing +of incoming characters. The method returns when the interaction has +completed. See section Interaction for a description of the +possible interaction.

+

The method returns the symbolic action of the menu item selected by +the user at the end of the interaction.

+
object done
+

This method can be used by user supplied actions to terminate the +interaction with the object.

+
object clear
+

This method can be used by user supplied actions to remove the menu +from the terminal.

+
object configure
+
+
object configure option
+
+
object configure option value...
+
+
object cget option
+

Standard methods to retrieve and configure the options of the menu.

+
+
+

Configuration

+

A menu instance recognizes the following options:

+
+
-in chan
+

Specifies the channel to read character sequences from. Defaults to +stdin.

+
-out chan
+

Specifies the channel to write the menu contents to. Defaults to +stdout.

+
-column int
+

Specifies the column of the terminal where the left margin of the +menu display should appear. Defaults to 0, i.e. the left-most +column.

+
-line int
+

Specifies the line of the terminal where the top margin of the menu +display should appear. Defaults to 0, i.e. the top-most line.

+
-height int
+

Specifies the number of lines of text to show at most in the +display. Defaults to 25.

+
-actions dict
+

Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section Interaction.

+
-hilitleft int
+
+
-hilitright int
+

By default the entire selected menu entry is highlighted in revers +output. However, when present these two options restrict revers dispay +to the specified sub-range of the entry.

+
-framed bool
+

By default the menu is shown using only header and footer out of +characters box graphics. If this flag is set the menu is fully +enclosed in a box.

+
+
+

Interaction

+

A menu object recognizes the control sequences listed below and acts +as described. The user can supply more control sequences to act on via +the configuration, but is not able to overide these defaults.

+
+
Cursor Up
+

The selection is moved up one entry, except if the first entry of the +menu is already selected.

+
Cursor Down
+

The selection is moved down one entry, except if the last entry of the +menu is already selected.

+
Enter/Return
+

The interaction with the object is terminated.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ipager.html Index: embedded/www/tcllib/files/modules/term/ipager.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/ipager.html @@ -0,0 +1,258 @@ + + +term::interact::pager - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::interact::pager(n) 0.1 tcllib "Terminal control"

+

Name

+

term::interact::pager - Terminal widget, paging

+
+ + +

Description

+

This package provides a class for the creation of a simple paging +text display.

+
+

Class API

+

The package exports a single command, the class command, enabling the +creation of pager instances. Its API is:

+
+
term::interact::pager object text ?options...?
+

This command creates a new pager object with the name object, +initializes it, and returns the fully qualified name of the object +command as its result.

+

The argument is the text to show, possibly followed by configuration +options and their values. The options are explained in the section +Configuration.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object interact
+

Show the pager in the screen at the configured location and start +interacting with it. This opens its own event loop for the processing +of incoming characters. The method returns when the interaction has +completed. See section Interaction for a description of the +possible interaction.

+
object done
+

This method can be used by user supplied actions to terminate the +interaction with the object.

+
object clear
+

This method can be used by user supplied actions to remove the pager +from the terminal.

+
object text text
+

This method can be used to change the text shown by the pager. +The pager will reset the dispay to show the first line of the +text at the top.

+
object configure
+
+
object configure option
+
+
object configure option value...
+
+
object cget option
+

Standard methods to retrieve and configure the options of the pager.

+
+
+

Configuration

+

A pager instance recognizes the following options:

+
+
-in chan
+

Specifies the channel to read character sequences from. Defaults to +stdin.

+
-out chan
+

Specifies the channel to write the pager contents to. Defaults to +stdout.

+
-column int
+

Specifies the column of the terminal where the left margin of the +pager display should appear. Defaults to 0, i.e. the left-most +column.

+
-line int
+

Specifies the line of the terminal where the top margin of the pager +display should appear. Defaults to 0, i.e. the top-most line.

+
-height int
+

Specifies the number of lines of text to show at most in the +display. Defaults to 25.

+
-actions dict
+

Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section Interaction.

+
+
+

Interaction

+

A pager object recognizes the control sequences listed below and acts +as described. The user can supply more control sequences to act on via +the configuration, but is not able to overide these defaults.

+
+
Cursor Up
+

The text is scrolled down a single line, making one more line visible +at the top. The pager will not react if the first line of the text is +already shown.

+
Cursor Down
+

The text is scrolled up a single line, making one more line visible at +the bottom. The pager will not react if the last line of the text is +already shown.

+
Page Up
+

The text is scrolled down a page. The pager will not react if the +first line of the text is already shown.

+
Page Down
+

The text is scrolled up a page. The pager will not react if the last +line of the text is already shown.

+
Enter/Return
+

The interaction with the object is terminated.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/receive.html Index: embedded/www/tcllib/files/modules/term/receive.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/receive.html @@ -0,0 +1,187 @@ + + +term::receive - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::receive(n) 0.1 tcllib "Terminal control"

+

Name

+

term::receive - General input from terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::receive ?0.1?
    • +
+ +
+
+

Description

+

This package provides the most primitive commands for receiving +characters to a terminal. They are in essence convenient wrappers +around the builtin commands read and fileevent.

+
+
::term::receive::getch ?chan?
+

This command reads a single character from the channel with handle +chan and returns it as the result of the command.

+

If not specified chan defaults to stdin.

+

It is the responsibility of the caller to make sure that the channel +can provide single characters. On unix this can be done, for example, +by using the command of package term::ansi::ctrl::unix.

+
::term::receive::listen cmd ?chan?
+

This command sets up a filevent listener for the channel with handle +chan and invokes the command prefix cmd whenever +characters have been received, or EOF was reached.

+

If not specified chan defaults to stdin.

+

The signature of the command prefix is

+
+
cmd process string
+

This method is invoked when characters were received, and string +holds them for processing.

+
cmd eof
+

This method is invoked when EOF was reached on the channel we listen +on. It will be the last call to be received by the callback.

+
+
::term::receive::unlisten ?chan?
+

This command disables the filevent listener for the channel with handle +chan.

+

If not specified chan defaults to stdin.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term.html Index: embedded/www/tcllib/files/modules/term/term.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/term.html @@ -0,0 +1,154 @@ + + +term - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term(n) 0.1 tcllib "Terminal control"

+

Name

+

term - General terminal control

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term ?0.1?
    • +
+
+
+

Description

+

It is planned to have this package provide highlevel general terminal control +commands, in the vein of ncurses or similar packages. Currently nothing has +been implemented however. I.e. this package is empty. It can be loaded, yet +provides nothing.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term_bind.html Index: embedded/www/tcllib/files/modules/term/term_bind.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/term_bind.html @@ -0,0 +1,231 @@ + + +term::receive::bind - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::receive::bind(n) 0.1 tcllib "Terminal control"

+

Name

+

term::receive::bind - Keyboard dispatch from terminals

+
+ + +

Description

+

This package provides a class for the creation of simple dispatchers +from character sequences to actions. Internally each dispatcher is in +essence a deterministic finite automaton with tree structure.

+
+

Class API

+

The package exports a single command, the +class command, enabling the creation of +dispatcher instances. Its API +is:

+
+
term::receive::bind object ?map?
+

This command creates a new dispatcher object with the name +object, initializes it, and returns the fully qualified name of +the object command as its result.

+

The argument is a dictionary mapping from strings, i.e. character +sequences to the command prefices to invoke when the sequence is found +in the input stream.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object map str cmd
+

This method adds an additional mapping from the string str to +the action cmd. The mapping will take effect immediately +should the processor be in a prefix of str, or at the next +reset operation. The action is a command prefix and will be invoked +with one argument appended to it, the character sequence causing +the invokation. It is executed in the global namespace.

+
object default cmd
+

This method defines a default action cmd which will be invoked +whenever an unknown character sequence is encountered. The command +prefix is handled in the same as the regular action defined via +method map.

+
object listen ?chan?
+

This methods sets up a filevent listener for the channel with handle +chan and invokes the dispatcher object whenever characters have +been received, or EOF was reached.

+

If not specified chan defaults to stdin.

+
object unlisten ?chan?
+

This methods removes the filevent listener for the channel with handle +chan.

+

If not specified chan defaults to stdin.

+
object reset
+

This method resets the character processor +to the beginning of the tree.

+
object next char
+

This method causes the character processor to process the character +c. This may simply advance the internal state, or invoke an +associated action for a recognized sequence.

+
object process str
+

This method causes the character processor to process the character +sequence str, advancing the internal state and invoking action +as necessary. This is a callback for listen.

+
object eof
+

This method causes the character processor to handle EOF on the +input. This is currently no-op. +This is a callback for listen.

+
+
+

Notes

+

The simplicity of the DFA means that it is not possible to recognize a +character sequence with has a another recognized character sequence as +its prefix.

+

In other words, the set of recognized strings has to form a +prefix code.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term_send.html Index: embedded/www/tcllib/files/modules/term/term_send.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/term/term_send.html @@ -0,0 +1,168 @@ + + +term::send - Terminal control + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

term::send(n) 0.1 tcllib "Terminal control"

+

Name

+

term::send - General output to terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::send ?0.1?
    • +
+ +
+
+

Description

+

This package provides the most primitive commands for sending characters +to a terminal. They are in essence convenient wrappers around the +builtin command puts.

+
+
::term::send::wrch chan str
+

Send the text str to the channel specified by the handle chan. +In contrast to the builtin command puts this command does not +terminate the string with a line terminator. It also forces an flush of +Tcl internal and OS buffers to ensure that the characters are processed +immediately.

+
::term::send::wr str
+

This convenience command is like ::term::send::wrch, except that the +destination channel is fixed to stdout.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/textutil/adjust.html Index: embedded/www/tcllib/files/modules/textutil/adjust.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/adjust.html @@ -0,0 +1,272 @@ + +textutil::adjust - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::adjust(n) 0.7.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::adjust - Procedures to adjust, indent, and undent paragraphs

+
+ + +

Description

+

The package textutil::adjust provides commands that manipulate +strings or texts (a.k.a. long strings or string with embedded newlines +or paragraphs), adjusting, or indenting them.

+

The complete set of procedures is described below.

+
+
::textutil::adjust::adjust string ?option value...?
+

Do a justification on the string according to the options. The +string is taken as one big paragraph, ignoring any newlines. Then the +line is formatted according to the options used, and the command +returns a new string with enough lines to contain all the printable +chars in the input string. A line is a set of characters between the +beginning of the string and a newline, or between 2 newlines, or +between a newline and the end of the string. If the input string is +small enough, the returned string won't contain any newlines.

+

Together with ::textutil::adjust::indent it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+

By default, any occurrence of space or tabulation characters are +replaced by a single space so that each word in a line is separated +from the next one by exactly one space character, and this forms a +real line. +Each real line is placed in a logical line, which has +exactly a given length (see the option -length below). +The real line may be shorter. Again by default, trailing spaces +are ignored before returning the string (see the option -full +below).

+

The following options may be used after the string parameter, +and change the way the command places a real line in a +logical line.

+
+
-full boolean
+

If set to false (default), trailing space characters are +deleted before returning the string. If set to true, any +trailing space characters are left in the string.

+
-hyphenate boolean
+

If set to false (default), no hyphenation will be done. If set +to true, the command will try to hyphenate the last word of a +line. Note: Hyphenation patterns must be loaded prior, using +the command ::textutil::adjust::readPatterns.

+
-justify center|left|plain|right
+

Sets the justification of the returned string to either left +(default), center, plain or right. The +justification means that any line in the returned string but the last +one is build according to the value. +If the justification is set to plain and the number of +printable chars in the last line is less than 90% of the length of a +line (see the option -length), then this line is justified +with the left value, avoiding the expansion of this line when +it is too small. The meaning of each value is:

+
+
center
+

The real line is centered in the logical line. If needed, a set of +space characters are added at the beginning (half of the needed set) +and at the end (half of the needed set) of the line if required (see +the option -full).

+
left
+

The real line is set on the left of the logical line. It means that +there are no space chars at the beginning of this line. If required, +all needed space chars are added at the end of the line (see the +option -full).

+
plain
+

The real line is exactly set in the logical line. It means that there +are no leading or trailing space chars. All the needed space chars are +added in the real line, between 2 (or more) words.

+
right
+

The real line is set on the right of the logical line. It means that +there are no space chars at the end of this line, and there may be +some space chars at the beginning, despite of the -full option.

+
+
-length integer
+

Set the length of the logical line in the string to +integer. integer must be a positive integer +value. Defaults to 72.

+
-strictlength
+

boolean] +If set to false (default), a line can exceed the specified +-length if a single word is longer than -length. If +set to true, words that are longer than -length are +split so that no line exceeds the specified -length.

+
+
::textutil::adjust::readPatterns filename
+

Loads the internal storage for hyphenation patterns with the contents +of the file filename. This has to be done prior to calling +command ::textutil::adjust::adjust with "-hyphenate +true", or the hyphenation process will not work correctly.

+

The package comes with a number of predefined pattern files, and the +command ::textutil::adjust::listPredefined can be used to find +out their names.

+
::textutil::adjust::listPredefined
+

This command returns a list containing the names of the hyphenation +files coming with this package.

+
::textutil::adjust::getPredefined filename
+

Use this command to query the package for the full path name of the +hyphenation file filename coming with the package. Only the +filenames found in the list returned by +::textutil::adjust::listPredefined are legal arguments for this +command.

+
::textutil::adjust::indent string prefix ?skip?
+

Each line in the string is indented by adding the string +prefix at its beginning. The modified string is returned +as the result of the command.

+

If skip is specified the first skip lines are left +untouched. The default for skip is 0, causing the +modification of all lines. Negative values for skip are treated +like 0. In other words, skip > 0 creates a +hanging indentation.

+

Together with ::textutil::adjust::adjust it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+
::textutil::adjust::undent string
+

The command computes the common prefix for all lines in string +consisting solely out of whitespace, removes this from each line and +returns the modified string.

+

Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove.

+

Together with ::textutil::adjust::adjust it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/expander.html Index: embedded/www/tcllib/files/modules/textutil/expander.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/expander.html @@ -0,0 +1,512 @@ + + +textutil::expander - Text and string utilities, macro processing + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::expander(n) 1.3.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::expander - Procedures to process templates and expand text.

+
+ + +

Description

+

The Tcl subst command is often used to support a kind of +template processing. Given a string with embedded variables or +function calls, subst will interpolate the variable and function +values, returning the new string:

+
+    % set greeting "Howdy"
+    Howdy
+    % proc place {} {return "World"}
+    % subst {$greeting, [place]!}
+    Howdy, World!
+    %
+
+

By defining a suitable set of Tcl commands, subst can be used to +implement a markup language similar to HTML.

+

The subst command is efficient, but it has three drawbacks for +this kind of template processing:

+
    +

  • There's no way to identify and process the plain text between two +embedded Tcl commands; that makes it difficult to handle plain text in +a context-sensitive way.

    • +

  • Embedded commands are necessarily bracketed by [ and +]; it's convenient to be able to choose different brackets +in special cases. Someone producing web pages that include a large +quantity of Tcl code examples might easily prefer to use << +and >> as the embedded code delimiters instead.

    • +

  • There's no easy way to handle incremental input, as one might wish to +do when reading data from a socket.

    • +
+

At present, expander solves the first two problems; eventually it will +solve the third problem as well.

+

The following section describes the command API to the expander; this +is followed by the tutorial sections, see TUTORIAL.

+
+

EXPANDER API

+

The textutil::expander package provides only one command, +described below. The rest of the section is taken by a description of +the methods for the expander objects created by this command.

+
+
::textutil::expander expanderName
+

The command creates a new expander object with an associated Tcl +command whose name is expanderName. This command may be used to +invoke various operations on the graph. If the expanderName is +not fully qualified it is interpreted as relative to the current +namespace. The command has the following general form:

+
+expanderName option ?arg arg ...?
+
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for expander objects:

+
+
expanderName cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
expanderName cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
expanderName cis cname
+

Determines whether or not the name of the current context is +cname.

+
expanderName cname
+

Returns the name of the current context.

+
expanderName cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
expanderName ctopandclear
+

Returns the output currently captured in the topmost context and +clears that buffer. This is similar to a combination of cpop +followed by cpush, except that internal state (brackets) is +preserved here.

+
expanderName cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
expanderName cset varname value
+

Sets variable varname to value in the current context.

+
expanderName cvar varname
+

Retrieves the internal variable name of context variable +varname; this allows the variable to be passed to commands like +lappend.

+
expanderName errmode newErrmode
+

Sets the macro expansion error mode to one of nothing, +macro, error, or fail; the default value is +fail. The value determines what the expander does if an +error is detected during expansion of a macro.

+
+
fail
+

The error propagates normally and can be caught or ignored by the +application.

+
error
+

The macro expands into a detailed error message, and expansion +continues.

+
macro
+

The macro expands to itself; that is, it is passed along to the output +unchanged.

+
nothing
+

The macro expands to the empty string, and is effectively ignored.

+
+
expanderName evalcmd ?newEvalCmd?
+

Returns the current evaluation command, which defaults to +uplevel #0. If specified, newEvalCmd will be saved for +future use and then returned; it must be a Tcl command expecting one +additional argument: the macro to evaluate.

+
expanderName expand string ?brackets?
+

Expands the input string, replacing embedded macros with their +expanded values, and returns the expanded string.

+

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 expander
+    1.2
+    % ::expander::expander myexp
+    ::myexp
+    %
+
+

The created ::myexp object can be used to expand text strings +containing embedded Tcl commands. By default, embedded commands are +delimited by square brackets. Note that expander doesn't attempt to +interpolate variables, since variables can be referenced by embedded +commands:

+
+    % set greeting "Howdy"
+    Howdy
+    % proc place {} {return "World"}
+    % ::myexp expand {[set greeting], [place]!}
+    Howdy, World!
+    %
+
+
+

Embedding Macros

+

An expander macro is simply a Tcl script embedded within a text +string. Expander evaluates the script in the global context, and +replaces it with its result string. For example,

+
+    % set greetings {Howdy Hi "What's up"}
+    Howdy Hi "What's up"
+    % ::myexp expand {There are many ways to say "Hello, World!":
+    [set result {}
+    foreach greeting $greetings {
+	append result "$greeting, World!\\n"
+    }
+    set result]
+    And that's just a small sample!}
+    There are many ways to say "Hello, World!":
+    Howdy, World!
+    Hi, World!
+    What's up, World!
+    And that's just a small sample!
+    %
+
+
+

Writing Macro Commands

+

More typically, macro commands are used to create a markup +language. A macro command is just a Tcl command that returns an +output string. For example, expand can be used to implement a generic +document markup language that can be retargeted to HTML or any other +output format:

+
+    % proc bold {} {return "<b>"}
+    % proc /bold {} {return "</b>"}
+    % ::myexp expand {Some of this text is in [bold]boldface[/bold]}
+    Some of this text is in <b>boldface</b>
+    %
+
+

The above definitions of bold and /bold returns HTML, but +such commands can be as complicated as needed; they could, for +example, decide what to return based on the desired output format.

+
+

Changing the Expansion Brackets

+

By default, embedded macros are enclosed in square brackets, +[ and ]. If square brackets need to be +included in the output, the input can contain the lb and +rb commands. Alternatively, or if square brackets are +objectionable for some other reason, the macro expansion brackets can +be changed to any pair of non-empty strings.

+

The setbrackets command changes the brackets permanently. +For example, you can write pseudo-html by change them to < +and >:

+
+    % ::myexp setbrackets < >
+    % ::myexp expand {<bold>This is boldface</bold>}
+    <b>This is boldface</b>
+
+

Alternatively, you can change the expansion brackets temporarily by +passing the desired brackets to the expand command:

+
+    % ::myexp setbrackets "\\[" "\\]"
+    % ::myexp expand {<bold>This is boldface</bold>} {< >}
+    <b>This is boldface</b>
+    %
+
+
+

Customized Macro Expansion

+

By default, macros are evaluated using the Tcl uplevel #0 +command, so that the embedded code executes in the global context. +The application can provide a different evaluation command using +evalcmd; this allows the application to use a safe +interpreter, for example, or even to evaluated something other than +Tcl code. There is one caveat: to be recognized as valid, a macro +must return 1 when passed to Tcl's "info complete" command.

+

For example, the following code "evaluates" each macro by returning +the macro text itself.

+
+    proc identity {macro} {return $macro}
+    ::myexp evalcmd identity
+
+
+

Using the Context Stack

+

Often it's desirable to define a pair of macros which operate in some +way on the plain text between them. Consider a set of macros for +adding footnotes to a web page: one could have implement something +like this:

+
+    Dr. Pangloss, however, thinks that this is the best of all
+    possible worlds.[footnote "See Candide, by Voltaire"]
+
+

The footnote macro would, presumably, assign a number to this +footnote and save the text to be formatted later on. However, this +solution is ugly if the footnote text is long or should contain +additional markup. Consider the following instead:

+
+    Dr. Pangloss, however, thinks that this is the best of all
+    possible worlds.[footnote]See [bookTitle "Candide"], by
+    [authorsName "Voltaire"], for more information.[/footnote]
+
+

Here the footnote text is contained between footnote and +/footnote macros, continues onto a second line, and contains +several macros of its own. This is both clearer and more flexible; +however, with the features presented so far there's no easy way to do +it. That's the purpose of the context stack.

+

All macro expansion takes place in a particular context. Here, the +footnote macro pushes a new context onto the context stack. +Then, all expanded text gets placed in that new context. +/footnote retrieves it by popping the context. Here's a +skeleton implementation of these two macros:

+
+    proc footnote {} {
+        ::myexp cpush footnote
+    }
+    proc /footnote {} {
+        set footnoteText [::myexp cpop footnote]
+        # Save the footnote text, and return an appropriate footnote
+        # number and link.
+    }
+
+

The cpush command pushes a new context onto the stack; the +argument is the context's name. It can be any string, but would +typically be the name of the macro itself. Then, cpop +verifies that the current context has the expected name, pops it off +of the stack, and returns the accumulated text.

+

Expand provides several other tools related to the context stack. +Suppose the first macro in a context pair takes arguments or computes +values which the second macro in the pair needs. After calling +cpush, the first macro can define one or more context +variables; the second macro can retrieve their values any time before +calling cpop. For example, suppose the document must specify +the footnote number explicitly:

+
+    proc footnote {footnoteNumber} {
+        ::myexp cpush footnote
+        ::myexp csave num $footnoteNumber
+        # Return an appropriate link
+    }
+    proc /footnote {} {
+        set footnoteNumber [::myexp cget num]
+        set footnoteText [::myexp cpop footnote]
+        # Save the footnote text and its footnoteNumber for future
+        # output.
+    }
+
+

At times, it might be desirable to define macros that are valid only +within a particular context pair; such macros should verify that they +are only called within the correct context using either cis +or cname.

+
+
+

HISTORY

+

expander was written by William H. Duquette; it is a repackaging +of the central algorithm of the expand macro processing tool.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil :: expander of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/textutil/repeat.html Index: embedded/www/tcllib/files/modules/textutil/repeat.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/repeat.html @@ -0,0 +1,167 @@ + +textutil::repeat - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::repeat(n) 0.7.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::repeat - Procedures to repeat strings.

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil::repeat ?0.7?
    • +
+ +
+
+

Description

+

The package textutil::repeat provides commands to generate +long strings by repeating a shorter string many times.

+

The complete set of procedures is described below.

+
+
::textutil::repeat::strRepeat text num
+

This command returns a string containing the text repeated +num times. The repetitions are joined without characters between +them. A value of num <= 0 causes the command to return an empty +string.

+

Note: If the Tcl core the package is loaded in provides the +command string repeat then this command will be implemented in +its terms, for maximum possible speed. Otherwise a fast implementation +in Tcl will be used.

+
::textutil::repeat::blank num
+

A convenience command. Returns a string of num spaces.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/tabify.html Index: embedded/www/tcllib/files/modules/textutil/tabify.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/tabify.html @@ -0,0 +1,187 @@ + +textutil::tabify - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::tabify(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::tabify - Procedures to (un)tabify strings

+
+ + +

Description

+

The package textutil::tabify provides commands that convert +between tabulation and ordinary whitespace in strings.

+

The complete set of procedures is described below.

+
+
::textutil::tabify::tabify string ?num?
+

Tabify the string by replacing any substring of num space +chars by a tabulation and return the result as a new string. num +defaults to 8.

+
::textutil::tabify::tabify2 string ?num?
+

Similar to ::textutil::tabify this command tabifies the +string and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +num spaces this command works more like an editor. num +defaults to 8.

+

Each line of the text in string is treated as if there are +tabstops every num columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs.

+
::textutil::tabify::untabify string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of num space chars and return the result as a new +string. num defaults to 8.

+
::textutil::tabify::untabify2 string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of at most num space chars and return the result as a +new string. Unlike textutil::tabify::untabify each tab is not +replaced by a fixed number of space characters. The command overlays +each line in the string with tabstops every num columns +instead and replaces tabs with just enough space characters to reach +the next tabstop. This is the complement of the actions taken by +::textutil::tabify::tabify2. num defaults to 8.

+

There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil.html Index: embedded/www/tcllib/files/modules/textutil/textutil.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/textutil.html @@ -0,0 +1,420 @@ + +textutil - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil(n) 0.7.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil - Procedures to manipulate texts and strings.

+
+ + +

Description

+

The package textutil provides commands that manipulate +strings or texts (a.k.a. long strings or string with embedded newlines +or paragraphs). +It is actually a bundle providing the commands of the six packages

+
+
textutil::adjust
+
+
textutil::repeat
+
+
textutil::split
+
+
textutil::string
+
+
textutil::tabify
+
+
textutil::trim
+
+
+

in the namespace textutil.

+

The bundle is deprecated, and it will be removed in a future +release of Tcllib, after the next release. It is recommended to use the +relevant sub packages instead for whatever functionality is needed by +the using package or application.

+

The complete set of procedures is described below.

+
+
::textutil::adjust string args
+

Do a justification on the string according to args. The +string is taken as one big paragraph, ignoring any newlines. Then the +line is formatted according to the options used, and the command +return a new string with enough lines to contain all the printable +chars in the input string. A line is a set of chars between the +beginning of the string and a newline, or between 2 newlines, or +between a newline and the end of the string. If the input string is +small enough, the returned string won't contain any newlines.

+

Together with ::textutil::indent it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+

By default, any occurrence of spaces characters or tabulation are +replaced by a single space so each word in a line is separated from +the next one by exactly one space char, and this forms a real +line. Each real line is placed in a logical line, which +have exactly a given length (see -length option below). The +real line may have a lesser length. Again by default, any +trailing spaces are ignored before returning the string (see +-full option below). The following options may be used after the +string parameter, and change the way the command place a +real line in a logical line.

+
+
-full boolean
+

If set to false, any trailing space chars are deleted before +returning the string. If set to true, any trailing space +chars are left in the string. Default to false.

+
-hyphenate boolean
+

if set to false, no hyphenation will be done. If set to +true, the last word of a line is tried to be hyphenated. +Defaults to false. Note: hyphenation patterns must be loaded +prior, using the command ::textutil::adjust::readPatterns.

+
-justify center|left|plain|right
+

Set the justification of the returned string to center, +left, plain or right. By default, it is set to +left. The justification means that any line in the returned +string but the last one is build according to the value. If the +justification is set to plain and the number of printable +chars in the last line is less than 90% of the length of a line (see +-length), then this line is justified with the left +value, avoiding the expansion of this line when it is too small. The +meaning of each value is:

+
+
center
+

The real line is centered in the logical line. If needed, a set of +space characters are added at the beginning (half of the needed set) +and at the end (half of the needed set) of the line if required (see +the option -full).

+
left
+

The real line is set on the left of the logical line. It means that +there are no space chars at the beginning of this line. If required, +all needed space chars are added at the end of the line (see the +option -full).

+
plain
+

The real line is exactly set in the logical line. It means that there +are no leading or trailing space chars. All the needed space chars are +added in the real line, between 2 (or more) words.

+
right
+

The real line is set on the right of the logical line. It means that +there are no space chars at the end of this line, and there may be +some space chars at the beginning, despite of the -full option.

+
+
-length integer
+

Set the length of the logical line in the string to +integer. integer must be a positive integer +value. Defaults to 72.

+
-strictlength boolean
+

If set to false, a line can exceed the specified +-length if a single word is longer than -length. If +set to true, words that are longer than -length are +split so that no line exceeds the specified -length. Defaults +to false.

+
+
::textutil::adjust::readPatterns filename
+

Loads the internal storage for hyphenation patterns with the contents +of the file filename. This has to be done prior to calling +command ::textutil::adjust with +"-hyphenate true", or the hyphenation process will +not work correctly.

+

The package comes with a number of predefined pattern files, and the +command ::textutil::adjust::listPredefined can be used to find +out their names.

+
::textutil::adjust::listPredefined
+

This command returns a list containing the names of the hyphenation +files coming with this package.

+
::textutil::adjust::getPredefined filename
+

Use this command to query the package for the full path name of the +hyphenation file filename coming with the package. Only the +filenames found in the list returned by +::textutil::adjust::listPredefined are legal arguments for this +command.

+
::textutil::indent string prefix ?skip?
+

Each line in the string indented by adding the string +prefix at its beginning. The modified string is returned +as the result of the command.

+

If skip is specified the first skip lines are left +untouched. The default for skip is 0, causing the +modification of all lines. Negative values for skip are treated +like 0. In other words, skip > 0 creates a +hanging indentation.

+

Together with ::textutil::adjust it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+
::textutil::undent string
+

The command computes the common prefix for all +lines in string consisting solely out of whitespace, +removes this from each line and returns the modified string.

+

Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove.

+

Together with ::textutil::adjust it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+
::textutil::splitn string ?len?
+

This command splits the given string into chunks of len +characters and returns a list containing these chunks. The argument +len defaults to 1 if none is specified. A negative +length is not allowed and will cause the command to throw an +error. Providing an empty string as input is allowed, the command will +then return an empty list. If the length of the string is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than len.

+
::textutil::splitx string ?regexp?
+

Split the string and return a list. The string is split +according to the regular expression regexp instead of a simple +list of chars. Note that if you add parenthesis into the regexp, +the parentheses part of separator would be added into list as +additional element. If the string is empty the result is the +empty list, like for split. If regexp is empty the +string is split at every character, like split does. +The regular expression regexp defaults to "[\\t \\r\\n]+".

+
::textutil::tabify string ?num?
+

Tabify the string by replacing any substring of num space +chars by a tabulation and return the result as a new string. num +defaults to 8.

+
::textutil::tabify2 string ?num?
+

Similar to ::textutil::tabify this command tabifies the +string and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +num spaces this command works more like an editor. num +defaults to 8.

+

Each line of the text in string is treated as if there are +tabstops every num columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs.

+
::textutil::trim string ?regexp?
+

Remove in string any leading and trailing substring according to +the regular expression regexp and return the result as a new +string. This apply on any line in the string, that is any +substring between 2 newline chars, or between the beginning of the +string and a newline, or between a newline and the end of the string, +or, if the string contain no newline, between the beginning and the +end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimleft string ?regexp?
+

Remove in string any leading substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimright string ?regexp?
+

Remove in string any trailing substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimPrefix string prefix
+

Removes the prefix from the beginning of string and +returns the result. The string is left unchanged if it doesn't +have prefix at its beginning.

+
::textutil::trimEmptyHeading string
+

Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the string and removes it. The modified +string is returned as the result of the command.

+
::textutil::untabify string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of num space chars and return the result as a new +string. num defaults to 8.

+
::textutil::untabify2 string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of at most num space chars and return the result as a +new string. Unlike textutil::untabify each tab is not replaced +by a fixed number of space characters. The command overlays each line +in the string with tabstops every num columns instead and +replaces tabs with just enough space characters to reach the next +tabstop. This is the complement of the actions taken by +::textutil::tabify2. num defaults to 8.

+

There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around.

+
::textutil::strRepeat text num
+

The implementation depends on the core executing the package. Used +string repeat if it is present, or a fast tcl implementation +if it is not. Returns a string containing the text repeated +num times. The repetitions are joined without characters between +them. A value of num <= 0 causes the command to return an empty +string.

+
::textutil::blank num
+

A convenience command. Returns a string of num spaces.

+
::textutil::chop string
+

A convenience command. Removes the last character of string and +returns the shortened string.

+
::textutil::tail string
+

A convenience command. Removes the first character of string and +returns the shortened string.

+
::textutil::cap string
+

Capitalizes the first character of string and returns the modified string.

+
::textutil::uncap string
+

The complementary operation to ::textutil::cap. Forces the first +character of string to lower case and returns the modified +string.

+
::textutil::longestCommonPrefixList list
+
+
::textutil::longestCommonPrefix ?string...?
+

Computes the longest common prefix for either the strings given +to the command, or the strings specified in the single list, and +returns it as the result of the command.

+

If no strings were specified the result is the empty string. If only +one string was specified, the string itself is returned, as it is its +own longest common prefix.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil_split.html Index: embedded/www/tcllib/files/modules/textutil/textutil_split.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/textutil_split.html @@ -0,0 +1,175 @@ + +textutil::split - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::split(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::split - Procedures to split texts

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil::split ?0.7?
    • +
+ +
+
+

Description

+

The package textutil::split provides commands that split +strings by size and arbitrary regular expressions.

+

The complete set of procedures is described below.

+
+
::textutil::split::splitn string ?len?
+

This command splits the given string into chunks of len +characters and returns a list containing these chunks. The argument +len defaults to 1 if none is specified. A negative +length is not allowed and will cause the command to throw an +error. Providing an empty string as input is allowed, the command will +then return an empty list. If the length of the string is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than len.

+
::textutil::split::splitx string ?regexp?
+

This command splits the string and return a list. The string is +split according to the regular expression regexp instead of a +simple list of chars. +Note that if you parentheses are added into the regexp, the +parentheses part of separator will be added into the result list as +additional element. If the string is empty the result is the +empty list, like for split. If regexp is empty the +string is split at every character, like split does. +The regular expression regexp defaults to "[\\t \\r\\n]+".

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil_string.html Index: embedded/www/tcllib/files/modules/textutil/textutil_string.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/textutil_string.html @@ -0,0 +1,182 @@ + +textutil::string - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::string(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::string - Procedures to manipulate texts and strings.

+
+ + +

Description

+

The package textutil::string provides miscellaneous string +manipulation commands.

+

The complete set of procedures is described below.

+
+
::textutil::string::chop string
+

A convenience command. Removes the last character of string and +returns the shortened string.

+
::textutil::string::tail string
+

A convenience command. Removes the first character of string and +returns the shortened string.

+
::textutil::string::cap string
+

Capitalizes the first character of string and returns the +modified string.

+
::textutil::string::uncap string
+

The complementary operation to ::textutil::string::cap. Forces +the first character of string to lower case and returns the +modified string.

+
::textutil::string::longestCommonPrefixList list
+
+
::textutil::string::longestCommonPrefix ?string...?
+

Computes the longest common prefix for either the strings given +to the command, or the strings specified in the single list, and +returns it as the result of the command.

+

If no strings were specified the result is the empty string. If only +one string was specified, the string itself is returned, as it is its +own longest common prefix.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/trim.html Index: embedded/www/tcllib/files/modules/textutil/trim.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/textutil/trim.html @@ -0,0 +1,192 @@ + +textutil::trim - Text and string utilities, macro processing + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

textutil::trim(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::trim - Procedures to trim strings

+
+ + +

Description

+

The package textutil::trim provides commands that trim +strings using arbitrary regular expressions.

+

The complete set of procedures is described below.

+
+
::textutil::trim::trim string ?regexp?
+

Remove in string any leading and trailing substring according to +the regular expression regexp and return the result as a new +string. This is done for all lines in the string, that is any +substring between 2 newline chars, or between the beginning of the +string and a newline, or between a newline and the end of the string, +or, if the string contain no newline, between the beginning and the +end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimleft string ?regexp?
+

Remove in string any leading substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimright string ?regexp?
+

Remove in string any trailing substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimPrefix string prefix
+

Removes the prefix from the beginning of string and +returns the result. The string is left unchanged if it doesn't +have prefix at its beginning.

+
::textutil::trim::trimEmptyHeading string
+

Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the string and removes it. The modified +string is returned as the result of the command.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/tie/tie.html Index: embedded/www/tcllib/files/modules/tie/tie.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tie/tie.html @@ -0,0 +1,505 @@ + +tie - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tie(n) 1.1 tcllib "Tcl Data Structures"

+

Name

+

tie - Array persistence

+
+ + +

Description

+

The tie package provides a framework for the creation of +persistent Tcl array variables. It should be noted that the provided +mechanism is generic enough to also allow its usage for the +distribution of the contents of Tcl arrays over multiple threads and +processes, i.e. communication.

+

This, persistence and communication, is accomplished by tying) +a Tcl array variable to a data source. Examples of data +sources are other Tcl arrays and files.

+

It should be noted that a single Tcl array variable can be tied to +more than one data source. It is this feature which allows +the framework to be used for communication as well. Just tie several +Tcl arrays in many client processes to a Tcl array in a server and all +changes to any of them will be distributed to all. Less centralized +variants of this are of course possible as well.

+
+

USING TIES

+

TIE API

+

This section describes the basic API used to establish and remove ties +between Tcl array variables and data sources. This interface is the +only one a casual user has to be concerned about. The following +sections about the various internal interfaces can be safely skipped.

+
+
::tie::tie arrayvarname options... dstype dsname...
+

This command establishes a tie between the Tcl array whose name is +provided by the argument arrayvarname and the +data source identified by the dstype and its series of +dsname arguments. All changes made to the Tcl array after this +command returns will be saved to the data source for +safekeeping (or distribution).

+

The result of the command is always a token which identifies the new +tie. This token can be used later to destroy this specific tie.

+
+
varname arrayvarname (in)
+

The name of the Tcl array variable to connect the new tie to.

+
name|command dstype (in)
+

This argument specifies the type of the data source we wish +to access. +The dstype can be one of log, array, +remotearray, file, growfile, or +dsource; in addition, the programmer can register additional +data source types. +Each dstype is followed by one or more arguments that identify +the data source to which the array is to be tied.

+
string dsname (in)
+

The series of dsname arguments coming after the dstype +identifies the data source we wish to connect to, and has to +be appropriate for the chosen type.

+
+

The command understands a number of additional options which guide the +process of setting up the connection between Tcl array and +data source.

+
+
-open
+

The Tcl array for the new tie is loaded from the +data source, and the previously existing contents of the Tcl +array are erased. Care is taken to not erase the previous +contents should the creation of the tie fail.

+

This option and the option -save exclude each other. If +neither this nor option -save are specified then this option +is assumed as default.

+
-save
+

The Tcl array for the new tie is saved to the +data source, and the previously existing contents of the +data source are erased.

+

This option and the option -open exclude each other. If +neither this nor option -open are specified then option +-open is assumed as default.

+
-merge
+

Using this option prevents the erasure of any previously existing +content and merges the data instead. It can be specified in +conjunction with either -open or -save. They +determine how data existing in both Tcl array and +data source, i.e duplicates, are dealt with.

+

When used with -open data in the data source has +precedence. +In other words, for duplicates the data in the data source is +loaded into the Tcl array.

+

When used with -save data in the Tcl array has precedence. In +other words, for duplicates the data in the Tcl array is saved into +the data source.

+
+
::tie::untie arrayvarname ?token?
+

This command dissolves one or more ties associated with the Tcl array +named by arrayvarname. If no token is specified then all +ties to that Tcl array are dissolved. Otherwise only the tie the token +stands for is removed, if it is actually connected to the +array. Trying to remove a specific tie not belonging to the provided +array will cause an error.

+

It should be noted that while severing a tie will destroy management +information internal to the package the data source which was +handled by the tie will not be touched, only closed.

+

After the command returns none of changes made to the array will be +saved to the data source anymore.

+

The result of the command is an empty string.

+
+
varname arrayname (in)
+

The name of a Tcl array variable which may have ties.

+
handle token (in)
+

A handle representing a specific tie. This argument is optional.

+
+
::tie::info ties arrayvarname
+

This command returns a list of ties associated with the Tcl array +variable named by arrayvarname. The result list will be empty if +the variable has no ties associated with it.

+
::tie::info types
+

This command returns a dictionary of registered types, and the class +commands they are associated with.

+
::tie::info type dstype
+

This command returns the fully resolved class command for a type +name. This means that the command will follow a chain of type +definitions ot its end.

+
+
+

STANDARD DATA SOURCE TYPES

+

This package provides the six following types as examples and standard +data sources.

+
+
log
+

This data source does not maintain any actual data, nor +persistence. It does not accept any identifying arguments. All changes +are simply logged to stdout.

+
array
+

This data source uses a regular Tcl array as the origin of +the persistent data. It accepts a single identifying argument, the +name of this Tcl array. All changes are mirrored to that array.

+
remotearray
+

This data source is similar to array. The difference +is that the Tcl array to which we are mirroring is not directly +accessible, but through a send-like command.

+

It accepts three identifying arguments, the name of the other Tcl +array, the command prefix for the send-like accessor command, +and an identifier for the remote entity hosting the array, in this +order. All changes are mirrored to that array, via the command +prefix. All commands will be executed in the context of the global +namespace.

+

send-like means that the command prefix has to have send +syntax and semantics. I.e. it is a channel over which we can send +arbitrary commands to some other entity. +The remote array data source however uses only the commands +set, unset, array exists, array names, array set, and +array get to retrieve and set values in the remote array.

+

The command prefix and the entity id are separate to allow the data +source to use options like -async when assembling the actual +commands.

+

Examples of command prefixes, listed with the id of the remote entity, +without options. In reality only the part before the id is the command +prefix:

+
+
send tkname
+

The Tcl array is in a remote interpreter and is accessed via Tk's X +communication.

+
comm::comm send hostportid
+

The Tcl array is in a remote interpreter and is accessed through a +socket.

+
thread::send threadid
+

The Tcl array is in a remote interpreter in a different thread of this +process.

+
+
file
+

This data source uses a single file as origin of the +persistent data. It accepts a single identifying argument, the path to +this file. The file has to be both readable and writable. It may not +exist, the data source will create it in that case. This (and +only this) situation will require that the directory for the file +exists and is writable as well.

+

All changes are saved in the file, as proper Tcl commands, one command +per operation. In other words, the file will always contain a proper +Tcl script.

+

If the file exists when the tie using it is set up, then it will be +compacted, i.e. superfluous operations are removed, if the operations +log stored in it contains either at least one operation clearing the +whole array, or at least 1.5 times more operations than entries in the +loaded array.

+
growfile
+

This data source is like file in terms of the storage +medium for the array data, and how it is configured. In constrast to +the former it however assumes and ensures that the tied array will +never shrink. I.e. the creation of new array entries, and the +modification of existing entries is allowed, but the deletion of +entries is not, and causes the data source to throw errors.

+

This restriction allows us to simplify both file format and access to +the file radically. For one, the file is read only once and the +internal cache cannot be invalidated. Second, writing data is reduced +to a simple append, and no compaction step is necessary. The format of +the contents is the string representation of a dictionary which can be +incrementally extended forever at the end.

+
dsource
+

This data source uses an explicitly specified +data source object as the source for the persistent +data. It accepts a single identifying argument, the command prefix, +i.e. object command.

+

To use this type it is necessary to know how the framework manages +ties and what data source objects are.

+

All changes are delegated to the specified object.

+
+
+
+

CREATING NEW DATA SOURCES

+

This section is of no interest to the casual user of ties. Only +developers wishing to create new data sources have to know the +information provided herein.

+

DATA SOURCE OBJECTS

+

All ties are represented internally by an in-memory object which +mediates between the tie framework and the specific +data source, like an array, file, etc. +This is the data source object.

+

Its class, the data source class is not generic, +but specific to the type of the data source. Writing a new +data source requires us to write such a class, and then +registering it with the framework as a new type.

+

The following subsections describe the various APIs a +data source class and the objects it generates will have +to follow to be compatible with the tie framework.

+

Data source objects are normally automatically created and destroyed +by the framework when a tie is created, or removed. This management +can be explicitly bypassed through the usage of the "dsource" type. +The data source for this type is a +data source object itself, and this object is outside of the +scope of the tie framework and not managed by it. +In other words, this type allows the creation of ties which talk to +pre-existing data source objects, and these objects will +survive the removal of the ties using them as well.

+
+

REGISTERING A NEW DATA SOURCE CLASS

+

After a data source class has been written it is necessary +to register it as a new type with the framework.

+
+
::tie::register dsclasscmd as dstype
+

Using this command causes the tie framework to remember the class +command dsclasscmd of a data source class under the +type name dstype.

+

After the call the argument dstype of the basic user command +::tie::tie will accept dstype as a type name and translate +it internally to the appropriate class command for the creation of +data source objects for the new data source.

+
+
+

DATA SOURCE CLASS

+

Each data source class is represented by a single command, also called +the class command, or object creation command. Its +syntax is

+
+
dsclasscmd objname ?dsname...?
+

The first argument of the class command is the name of the +data source object to create. +The framework itself will always supply the string %AUTO%, to +signal that the class command has to generate not only the object, but +the object name as well.

+

This is followed by a series of arguments identifying the data source +the new object is for. These are the same dsname arguments which +are given to the basic user command ::tie::tie. Their actual +meaning is dependent on the data source class.

+

The result of the class command has to be the fully-qualified name of +the new data source object, i.e. the name of the +object command. +The interface this command has to follow is described in the section +DATA SOURCE OBJECT API

+
+
+

DATA SOURCE OBJECT API

+

Please read the section DATA SOURCE CLASS first, to know +how to generate new object commands.

+

Each object command for a data source object has to +provide at least the methods listed below for proper inter-operation +with the tie framework. Note that the names of most of the methods +match the subcommands of the builtin array command.

+
+
ds destroy
+

This method is called when the object ds is destroyed. It now +has to release all its internal resources associated with the external +data source.

+
ds names
+

This command has to return a list containing the names of all keys +found in the data source the object talks to. This is +equivalent to array names.

+
ds size
+

This command has to return an integer number specifying the number of +keys found in the data source the object talks to. This is +equivalent to array size.

+
ds get
+

This command has to return a dictionary containing the data found in +the data source the object talks to. This is equivalent to +array get.

+
ds set dict
+

This command takes a dictionary and adds its contents to the data +source the object talks to. This is equivalent to array set.

+
ds unset ?pattern?
+

This command takes a pattern and removes all elements whose keys +matching it from the data source. If no pattern is specified +it defaults to *, causing the removal of all elements. This +is nearly equivalent to array unset.

+
ds setv index value
+

This command has to save the value in the data source +the object talks to, under the key index.

+

The result of the command is ignored. If an error is thrown then this +error will show up as error of the set operation which caused the +method call.

+
ds unsetv index
+

This command has to remove the value under the key index from +the data source the object talks to.

+

The result of the command is ignored. If an error is thrown then this +error will show up as error of the unset operation which caused the +method call.

+
ds getv index
+

This command has to return the value for the key index in the +data source the object talks to.

+
+

And here a small table comparing the data source methods to +the regular Tcl commands for accessing an array.

+
+        Regular Tcl             Data source
+        -----------             -----------
+        array names a           ds names
+        array size  a           ds size
+        array get   a           ds get
+        array set   a dict      ds set   dict
+        array unset a pattern   ds unset ?pattern?
+        -----------             -----------
+        set a($idx) $val        ds setv   idx val
+        unset a($idx)           ds unsetv idx
+        $a($idx)                ds getv   idx
+        -----------             -----------
+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tie of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/tie/tie_std.html Index: embedded/www/tcllib/files/modules/tie/tie_std.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tie/tie_std.html @@ -0,0 +1,161 @@ + +tie - Tcl Data Structures + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tie(n) 1.1 tcllib "Tcl Data Structures"

+

Name

+

tie - Array persistence, standard data sources

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require tie::std::log ?1.1?
    • +
  • package require tie::std::array ?1.1?
    • +
  • package require tie::std::rarray ?1.1?
    • +
  • package require tie::std::file ?1.1?
    • +
  • package require tie::std::growfile ?1.1?
    • +
  • package require tie::std::dsource ?1.1?
    • +
+
+
+

Description

+

The packages listed as requirements for this document are internal +packages providing the standard data sources of package tie, +as described in section STANDARD DATA SOURCE TYPES of +tie's documentation.

+

They are automatically loaded and registered by tie when it +itself is requested, and as such there is no need to request them on +their own, although it is possible to do so.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the packages it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tie of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/tiff/tiff.html Index: embedded/www/tcllib/files/modules/tiff/tiff.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/tiff/tiff.html @@ -0,0 +1,291 @@ + +tiff - TIFF image manipulation + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tiff(n) 0.2.1 tcllib "TIFF image manipulation"

+

Name

+

tiff - TIFF reading, writing, and querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query, modify, read, and write TIFF images. +TIFF stands for Tagged Image File Format and is a standard +for lossless storage of photographical images and associated metadata. +It is specified at http://partners.adobe.com/public/developer/tiff/index.html.

+

Multiple images may be stored in a single TIFF file. The ?image? options to the functions +in this package are for accessing images other than the first. Data in a TIFF image is +stored as a series of tags having a numerical value, which are represented in either a 4 digit +hexadecimal format or a string name. For a reference on defined tags and their meanings see +http://www.awaresystems.be/imaging/tiff/tifftags.html

+
+

COMMANDS

+
+
::tiff::isTIFF file
+

Returns a boolean value indicating if file is a +TIFF image.

+
::tiff::byteOrder file
+

Returns either big or little. +Throws an error if file is not a TIFF image.

+
::tiff::numImages file
+

Returns the number of images in file. +Throws an error if file is not a TIFF image.

+
::tiff::dimensions file ?image?
+

Returns the dimensions of image number ?image? in file as a list of the +horizontal and vertical pixel count. +Throws an error if file is not a TIFF image.

+
::tiff::imageInfo file ?image?
+

Returns a dictionary with keys ImageWidth, ImageLength, +BitsPerSample, Compression, PhotometricInterpretation, +ImageDescription, Orientation, XResolution, +YResolution, ResolutionUnit, DateTime, Artist, +and HostComputer. The values are the associated properties of +the TIFF ?image? in file. Values may be empty if the associated tag is not +present in the file.

+
+    puts [::tiff::imageInfo photo.tif]
+    ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1
+    PhotometricInterpretation 2 ImageDescription {} Orientation 1
+    XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45}
+    Artist {} HostComputer {}
+
+

There is nothing special about these tags, this is simply a convience procedure which calls +getEntry with common entries. +Throws an error if file is not a TIFF image.

+
::tiff::entries file ?image?
+

Returns a list of all entries in the given file and ?image? +in hexadecimal format. +Throws an error if file is not a TIFF image.

+
::tiff::getEntry file entry ?image?
+

Returns the value of entry from image ?image? in the TIFF file. +entry may be a list of multiple entries. If an entry does not exist, an +empty string is returned

+
+    set data [::tiff::getEntry photo.tif {0131 0132}]
+    puts "file was written at [lindex $data 0] with software [lindex $data 1]"
+
+

Throws an error if file is not a TIFF image.

+
::tiff::addEntry file entry ?image?
+

Adds the specified entries to the image named by ?image? (default 0), or optionally all. +entry must be a list where each element is a list of tag, type, and value. If a tag already +exists, it is overwritten.

+
+    ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}}
+
+

The data types are defined as follows

+
+
1
+

BYTE (8 bit unsigned integer)

+
2
+

ASCII

+
3
+

SHORT (16 bit unsigned integer)

+
4
+

LONG (32 bit unsigned integer)

+
5
+

RATIONAL

+
6
+

SBYTE (8 bit signed byte)

+
7
+

UNDEFINED (uninterpreted binary data)

+
8
+

SSHORT (signed 16 bit integer)

+
9
+

SLONG (signed 32 bit integer)

+
10
+

SRATIONAL

+
11
+

FLOAT (32 bit floating point number)

+
12
+

DOUBLE (64 bit floating point number)

+
+

Throws an error if file is not a TIFF image.

+
::tiff::deleteEntry file entry ?image?
+

Deletes the specified entries from the image named by ?image? (default 0), or optionally all. +Throws an error if file is not a TIFF image.

+
::tiff::getImage file ?image?
+

Returns the name of a Tk image containing the image at index ?image? from file +Throws an error if file is not a TIFF image, or if image is an unsupported format. +Supported formats are uncompressed 24 bit RGB and uncompressed 8 bit palette.

+
::tiff::writeImage image file ?entry?
+

Writes the contents of the Tk image image to a tiff file file. Files are +written in the 24 bit uncompressed format, with big endian byte order. Additional entries +to be added to the image may be specified, in the same format as tiff::addEntry

+
::tiff::nametotag names
+

Returns a list with names translated from string to 4 digit format. 4 digit names +in the input are passed through unchanged. Strings without a defined tag name will throw +an error.

+
::tiff::tagtoname tags
+

Returns a list with tags translated from 4 digit to string format. If a tag does +not have a defined name it is passed through unchanged.

+
::tiff::debug file
+

Prints everything we know about the given file in a nice format.

+
+
+

VARIABLES

+

The mapping of 4 digit tag names to string names uses the array ::tiff::tiff_tags. The reverse +mapping uses the array ::tiff::tiff_sgat.

+
+

LIMITATIONS

+
    +

  1. Cannot write exif ifd

    2. +

  2. Reading limited to uncompressed 8 bit rgb and 8 bit palletized images

    3. +

  3. Writing limited to uncompressed 8 bit rgb

    4. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tiff of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/connect.html Index: embedded/www/tcllib/files/modules/transfer/connect.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/connect.html @@ -0,0 +1,315 @@ + + +transfer::connect - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::connect(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::connect - Connection setup

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::connect ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects holding enough information to enable +them to either actively connect to a counterpart, or to passively wait +for a connection from said counterpart. +I.e. any object created by this packages is always in one of two +complementary modes, called active (the object initiates the +connection) and passive (the object receives the connection).

+

Of the two objects in a connecting pair one has to be configured for +active mode, and the other then has to be configured for +passive mode. This establishes which of the two partners +connects to whom (the active to the other), or, who is waiting +on whom (the passive on the other). +Note that this is completely independent of the direction of any data +transmission using the connection after it has been established. +An active object can, after establishing the connection, either +transmit or receive data. Equivalently the passive object can do the +same after the waiting for its partner has ended.

+
+

API

+

Package commands

+
+
transfer::connect objectName ?options...?
+

This command creates a new connection object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::connect command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. +This is safe to do for an active object when a connection has +been started, as the completion callback is synchronous. +For a passive object currently waiting for its partner to +establish the connection however this is not safe and will cause +errors later on, when the connection setup completes and tries to +access the now missing data structures of the destroyed object.

+
objectName connect command
+

This method starts the connection setup per the configuration of the +object. When the connection is established the callback command +will be invoked with one additional argument, the channel handle of +the socket over which data can be transfered.

+

The detailed behaviour of the method depends on the configured +mode.

+
+
active
+

The connection setup is done synchronously. The object waits until the +connection is established. The method returns the empty string as its +result.

+
passive
+

The connection setup is done asynchronously. The method returns +immediately after a listening socket has been set up. The connection +will be established in the background. +The method returns the port number of the listening socket, for use by +the caller. One important use is the transfer of this information to +the counterpart so that it knows where it has to connect to.

+

This is necessary as the object might have been configured for port +0, allowing the operating system to choose the actual port it +will listen on.

+

The listening port is closed immediately when the connection was +established by the partner, to keep the time interval small within +which a third party can connect to the port too. +Even so it is recommended to use additional measures in the protocol +outside of the connect and transfer object to ensure that a connection +is not used with an unidentified/unauthorized partner +One possibility for this is the use of SSL/TLS. +See the option -socketcmd and section +Secure connections for information on how to do this.

+
+
+
+

Options

+

Connection objects support the set of options listed below.

+
+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::connect C -socketcmd tls::socket ...
+    ...
+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/copyops.html Index: embedded/www/tcllib/files/modules/transfer/copyops.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/copyops.html @@ -0,0 +1,254 @@ + + +transfer::copy - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::copy(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::copy - Data transfer foundation

+
+ + +

Description

+

This package provides a number of commands for the asynchronous of +information contained in either a string or channel. The main point of +this package is that the commands here provide a nicer callback API +than the builtin command fcopy, making the use of these +facilities simpler than the builtin.

+
+

API

+
+
transfer::copy::do chan|string data outchannel ?options...?
+

This command transfers the information in data to the +outchannel, according to the options. The type of the +information in data is determined by the first argument.

+

The options available to this command are the same as are available to +the command transfer::copy::options, and explained there.

+
+
chan
+

The argument data contains the handle of a channel and the +actual infomration to transfer is read from that channel.

+
string
+

The argument data contains a string and this is the information +to be transfered.

+
+
transfer::copy::chan channel outchannel ?options...?
+

This command is a shorter and more direct form for the command +transfer::copy::do chan.

+
transfer::copy::string string outchannel ?options...?
+

This command is a shorter and more direct form for the command +transfer::copy::do string.

+
transfer::copy::doChan channel outchannel optvar
+

This command is an alternate form of transfer::copy::chan which +reads its options out of the array variable named by optvar +instead of from a variable length argument list.

+
transfer::copy::doString string outchannel optvar
+

This command is an alternate form of transfer::copy::string which +reads its options out of the array variable named by optvar +instead of from a variable length argument list.

+
transfer::copy::options outchannel optionlist optvar
+

This command is the option processor used by all the commands above +which read their options from a variable length argument list. It +first reads default settings from the channel handle outchannel, +then processes the list of options in optionlist, at last stores +the results in the array variable named by optvar. The contents +of that variable are in a format which is directly understood by all +the commands above which read their options out of an array variable.

+

The recognized options are:

+
+
-blocksize int
+

This option specifies the size of the chunks to transfer in one +operation. It is optional and defaults to the value of +-buffersize as configured for the output channel.

+

If specified its value has to be an integer number greater than zero.

+
-command commandprefix
+

This option specifies the completion callback of the operation. This +option has to be specified. An error will be thrown if it is not, or +if the empty list was specified as argument to it.

+

Its value has to be a command prefix, i.e. a list whose first word is +the command to execute, followed by words containing fixed +arguments. When the callback is invoked one or two additional +arguments are appended to the prefix. The first argument is the number +of bytes which were transfered. The optional second argument is an +error message and added if and only if an error occured during the the +transfer.

+
-progress commandprefix
+

This option specifies the progress callback of the operation. It is +optional and defaults to the empty list. This last possibility signals +that no feedback was asked for and disabled it.

+

Its value has to be a command prefix, see above, -command for +a more detailed explanation. When the callback is invoked a single +additional arguments is appended to the prefix. This argument is the +number of bytes which were transfered so far.

+
-size int
+

This option specifies the number of bytes to read from the input data +and transfer. It is optional and defaults to "Transfer everything". +Its value has to be an integer number and any value less than zero has +the same meaning, i.e. to transfer all available data. Any other value +is the amount of bytes to transfer.

+

All transfer commands will throw error an when their user tries to +transfer more data than is available in the input. This happens +immediately, before the transfer is actually started, should the input +be a string. Otherwise the, i.e. for a channel as input, the error is +thrown the moment the underflow condition is actually detected.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure and provide the settings for the output channel which +are to be active during the transfer, and only then. I.e. the settings +of the output channel before the transfer are saved, and restored at +the end of a transfer, regardless of its success or failure. None of +these options are required, and they default to the settings of the +output channel if not specified.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/ddest.html Index: embedded/www/tcllib/files/modules/transfer/ddest.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/ddest.html @@ -0,0 +1,254 @@ + + +transfer::data::destination - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::data::destination(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::data::destination - Data destination

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::data::destination ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects mainly describing the destination of a +data transfer. They are also able to initiate the reception of +information from a channel into the described destination.

+
+

API

+
+
transfer::data::destination objectName ?options...?
+

This command creates a new data destination object with an associated +Tcl command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+

Object command

+

All objects created by the ::transfer::data::destination command +have the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while the object is busy +with the reception of information from a channel will cause errors +later on, when the reception completes and tries to access the now +missing data structures of the destroyed object.

+
objectName put chunk
+

The main receptor method. Saves the received chunk of data into +the configured destination. It has to be called for each piece of data +received.

+
objectName done
+

The secondary receptor method. Finalizes the receiver. It has to be +called when the receiving channel signals EOF. Afterward neither +itself nor method put can be called anymore.

+
objectName valid msgvar
+

This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is True if the +object is valid, and False otherwise. In the latter case the +variable whose name is stored in msgvar is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched.

+
objectName receive channel done
+

This method initiates the reception of data from the specified +channel. The received data will be stored into the configured +destination, via calls to the methods put and done. +When the reception completes the command prefix done is invoked, +with the number of received characters appended to it as the sole +additional argument.

+
+
+

Options

+

All data destinations support the options listed below. It should be +noted that all are semi-exclusive, each specifying a different type of +destination and associated information. If these options are specified +more than once then the last option specified is used to actually +configure the object.

+
+
-channel handle
+

This option specifies that the destination of the data is a channel, +and its associated argument is the handle of the channel to write the +received data to.

+
-file path
+

This option specifies that the destination of the data is a file, and +its associated argument is the path of the file to write the received +data to.

+
-variable varname
+

This option specifies that the destination of the data is a variable, +and its associated argument contains the name of the variable to write +the received data to. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes received, allowing the user to monitor the progress of +the reception of the data. The callback is always invoked with one +additional argument, the number of bytes received so far.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/dsource.html Index: embedded/www/tcllib/files/modules/transfer/dsource.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/dsource.html @@ -0,0 +1,286 @@ + + +transfer::data::source - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::data::source(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::data::source - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::data::source ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects mainly describing the origin of some +data to transfer. They are also able to initiate transfers of the +described information to a channel using the foundation package +transfer::copy.

+
+

API

+

Package commands

+
+
transfer::data::source objectName ?options...?
+

This command creates a new data source object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::data::source command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a transfer initiated +by the object is active is safe as all data required for the transfer +itself was copied, and the completion of the transfer will not try to +access the initiating object anymore. i.e. the transfer is completely +separate from the source object itself.

+
objectName type
+

This method returns a string describing the type of the data the +object is refering to. The possible values and their meanings are:

+
+
undefined
+

No data was specified at all, or it was specified incompletely. The +object does not know the type.

+
string
+

The data to transfer is contained in a string.

+
channel
+

The data to transfer is contained in a channel.

+
+
objectName data
+

This method returns a value depending on the type of the data the +object refers to, through which the data can be accessed. +The method throws an error if the type is undefined. For type +string the returned result is the data itself, whereas for +type channel the returned result is the handle of the channel +containing the data.

+
objectName size
+

This method returns a value depending on the type of the data the +object refers to, the size of the data. +The method throws an error if the type is undefined. Return of +a negative value signals that the object is unable to determine an +absolute size upfront (like for data in a channel).

+
objectName valid msgvar
+

This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is True if the +object is valid, and False otherwise. In the latter case the +variable whose name is stored in msgvar is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched.

+
objectName transmit channel blocksize done
+

This method initiates a transfer of the referenced data to the +specified channel. +When the transfer completes the command prefix done is invoked, +per the rules for the option -command of command +transfer::copy::do in the package transfer::copy. +The blocksize specifies the size of the chunks to transfer in +one go. See the option -blocksize of command +transfer::copy::do in the package transfer::copy.

+
+
+

Options

+

All data sources support the options listed below. It should be noted +that the first four options are semi-exclusive, each specifying a +different type of data source and associated content. If these options +are specified more than once then the last option specified is used to +actually configure the object.

+
+
-string text
+

This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question.

+
-channel handle
+

This option specifies that the source of the data is a channel, and +its associated argument is the handle of the channel containing the +data.

+
-file path
+

This option specifies that the source of the data is a file, and its +associated argument is the path of the file containing the data.

+
-variable varname
+

This option specifies that the source of the data is a string stored +in a variable, and its associated argument contains the name of the +variable in question. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-size int
+

This option specifies the size of the data transfer. It is optional +and defaults to -1. This value, and any other value less than zero +signals to transfer all the data from the source.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes transmitted, allowing the user to monitor the progress +of the transmission of the data. The callback is always invoked with +one additional argument, the number of bytes transmitted so far.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/receiver.html Index: embedded/www/tcllib/files/modules/transfer/receiver.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/receiver.html @@ -0,0 +1,354 @@ + + +transfer::receiver - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::receiver(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::receiver - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::data::destination ?0.2?
    • +
  • package require transfer::connect ?0.2?
    • +
  • package require transfer::receiver ?0.2?
    • +
+ +
+
+

Description

+

This package pulls data destinations and connection setup together +into a combined object for the reception of information coming in over +a socket. +These objects understand all the options from objects created by the +packages transfer::data::destination and +transfer::connect.

+
+

API

+

Package commands

+
+
transfer::receiver object ?options...?
+

This command creates a new receiver object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
transfer::receiver stream channel chan host port ?arg...?
+

This method creates a fire-and-forget transfer for the data coming +from the source at host/port (details below) and writing to the +channel chan, starting at the current seek location. The channel +is configured to use binary translation and encoding for the transfer. +The channel is not closed when the transfer has completed. This +is left to the completion callback.

+

If both host and port are provided an active +connection to the data source is made. If only a port is +specified (with host the empty string) then a passive +connection is made instead, i.e. the receiver then waits for a +conneciton by the transmitter.

+

Any arguments after the port are treated as options and are used to +configure the internal receiver object. +See the section Options for a list of the supported options +and their meaning. +Note however that the signature of the command prefix specified +for the -command callback differs from the signature for the +same option of the receiver object. +This callback is only given the number of bytes and transfered, and +possibly an error message. No reference to the internally used +receiver object is made.

+

The result returned by the command is the empty string +if it was set to make an active connection, and the port the +internal receiver object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
transfer::receiver stream file path host port ?arg...?
+

This method is like stream channel, except that the +received data is written to the file path, replacing any prior +content.

+
+
+

Object command

+

All objects created by the ::transfer::receiver command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a reception is on +progress will cause errors later on, when the reception completes +and tries to access the now missing data structures of the destroyed +object.

+
objectName start
+

This method initiates the data reception, setting up the connection +first and then copying the received information into the +destination. +The method will throw an error if a reception is already/still in +progress. +I.e. it is not possible to run two receptions in parallel, only in +sequence. +Errors will also be thrown if the configuration of the data +destination is invalid, or if no completion callback was specified.

+

The result returned by the method is the empty string +for an object configured to make an active connection, and the port the + object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
objectName busy
+

This method returns a boolean value telling us whether a reception +is in progress (True), or not (False).

+
+
+

Options

+

All receiver objects support the union of the options supported by +their connect and data destination components, plus one of their own. +See also the documentation for the packages +transfer::data::destination and transfer::connect.

+
+ +
-command cmdprefix
+

This option specifies the command to invoke when the reception of +the information has been completed. +The arguments given to this command are the same as given to the +completion callback of the command transfer::copy::do provided +by the package transfer::copy.

+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
-channel handle
+

This option specifies that the destination of the data is a channel, +and its associated argument is the handle of the channel to write the +received data to.

+
-file path
+

This option specifies that the destination of the data is a file, and +its associated argument is the path of the file to write the received +data to.

+
-variable varname
+

This option specifies that the destination of the data is a variable, +and its associated argument contains the name of the variable to write +the received data to. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes received, allowing the user to monitor the progress of +the reception of the data. The callback is always invoked with one +additional argument, the number of bytes received so far.

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::receiver R -socketcmd tls::socket ...
+    ...
+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/tqueue.html Index: embedded/www/tcllib/files/modules/transfer/tqueue.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/tqueue.html @@ -0,0 +1,275 @@ + + +transfer::copy::queue - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::copy::queue(n) 0.1 tcllib "Data transfer facilities"

+

Name

+

transfer::copy::queue - Queued transfers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require struct::queue ?1.4?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::copy::queue ?0.1?
    • +
+ +
+
+

Description

+

This package provides objects which serialize transfer requests for a +single channel by means of a fifo queue. Accumulated requests are +executed in order of entrance, with the first request reaching an idle +object starting the execution in general. New requests can be added +while the object is active and are defered until all requests entered +before them have been completed successfully.

+

When a request causes a transfer error execution stops and all +requests coming after it are not served. Currently this means that +their completion callbacks are never triggered at all.

+

NOTE: + Not triggering the completion callbacks of the unserved + requests after an error stops the queue object is something I + am not fully sure that it makes sense. It forces the user of + the queue to remember the callbacks as well and run + them. Because otherwise everything in the system which depends + on getting a notification about the status of a request will + hang in the air. I am slowly convincing myself that it is more + sensible to trigger the relevant completion callbacks with an + error message about the queue abort, and 0 bytes transfered.

+

All transfer requests are of the form

+
+	{type data options...}
+
+

where type is in {chan, string}, and data +specifies the information to transfer. +For chan the data is the handle of the channel containing the +actual information to transfer, whereas for string data +contains directly the information to transfer. +The options are a list of them and their values, and are the +same as are accepted by the low-level copy operations of the package +transfer::copy. +Note how just prepending the request with transfer::copy::do and +inserting a channel handle in between data and options +easily transforms it from a pure data structure into a command whose +evaluation will perform the request.

+
+

API

+

Package commands

+
+
transfer::copy::queue objectName outchannel ?options...?
+

This command creates a new queue object for the management of the +channel outchannel, with an associated Tcl command whose name is +objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::copy::queue command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while the object is busy +will cause errors later on, when the currently executed request +completes and tries to access the now missing data structures of the +destroyed object.

+
objectName busy
+

This method returns a boolean value telling us if the object is +currently serving a request (i.e. busy, value True), or +not (i.e. idle, value False).

+
objectName pending
+

This method returns the number of requests currently waiting in the +queue for their execution. A request currently served is not counted +as waiting.

+
objectName put request
+

This method enters the transfer request into the object's queue +of waiting requests. +If the object is idle it will become busy, immediately +servicing the request. Otherwise servicing the new request will be +defered until all preceding requests have been served.

+
+
+
+

Options

+

The only option known is -on-status-change. It is optional +and defaults to the empty list, disabling the reporting of status +changes. Otherwise its argument is a command prefix which is invoked +whenever the internal status of the object changed. The callback is +invoked with two additional arguments, the result of the methods +pending and busy, in this order. This allows any +user to easily know, for example, when the object has processed all +outstanding requests.

+
+

Use

+

A possible application of this package and class is within a HTTP 1.1 +server, managing the results waiting for transfer to the client.

+

It should be noted that in this application the system also needs an +additional data structure which keeps track of outstanding results as +they may come back in a different order than the requests from the +client, and releases them to the actual queue in the proper order.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/transmitter.html Index: embedded/www/tcllib/files/modules/transfer/transmitter.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/transfer/transmitter.html @@ -0,0 +1,359 @@ + + +transfer::transmitter - Data transfer facilities + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

transfer::transmitter(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::transmitter - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::data::source ?0.2?
    • +
  • package require transfer::connect ?0.2?
    • +
  • package require transfer::transmitter ?0.2?
    • +
+ +
+
+

Description

+

This package pulls data sources and connection setup together into a +combined object for the transmission of information over a socket. +These objects understand all the options from objects created +by the packages transfer::data::source and +transfer::connect.

+
+

API

+

Package commands

+
+
transfer::transmitter objectName ?options...?
+

This command creates a new transmitter object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
transfer::transmitter stream channel chan host port ?arg...?
+

This method creates a fire-and-forget transfer for the data contained +in the channel chan, starting at the current seek location. The +channel is configured to use binary translation and encoding for the +transfer. +The channel is automatically closed when the transfer has completed.

+

If both host and port are provided an active +connection to the destination is made. If only a port is +specified (with host the empty string) then a passive +connection is made instead.

+

Any arguments after the port are treated as options and are used to +configure the internal transmitter object. +See the section Options for a list of the supported options +and their meaning. +Note however that the signature of the command prefix specified +for the -command callback differs from the signature for the +same option of the transmitter object. +This callback is only given the number of bytes and transfered, and +possibly an error message. No reference to the internally used +transmitter object is made.

+

The result returned by the command is the empty string +if it was set to make an active connection, and the port the +internal transmitter object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
transfer::transmitter stream file path host port ?arg...?
+

This method is like stream channel, except that the data +contained in the file path is transfered.

+
+
+

Object command

+

All objects created by the ::transfer::transmitter command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a transmission is in +progress will cause errors later on, when the transmission completes +and tries to access the now missing data structures of the destroyed +object.

+
objectName start
+

This method initiates the data transmission, setting up the connection +first and then copying the information. +The method will throw an error if a transmission is already/still in +progress. +I.e. it is not possible to run two transmissions in parallel on a +single object, only in sequence. Multiple transmitter objects are +needed to manage parallel transfers, one per transmission. +Errors will also be thrown if the configuration of the data source is +invalid, or if no completion callback was specified.

+

The result returned by the method is the empty string +for an object configured to make an active connection, and the port the + object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
objectName busy
+

This method returns a boolean value telling us whether a transmission +is in progress (True), or not (False).

+
+
+

Options

+

All transmitter objects support the union of the options supported +by their connect and data source components, plus two of their own. +See also the documentation for the packages +transfer::data::source and transfer::connect.

+
+
-blocksize int
+

This option specifies the size of the chunks to be transmitted in one +block. Usage is optional, its default value is 1024.

+
-command cmdprefix
+

This option specifies the command to invoke when the transmission of +the information has been completed. +The arguments given to this command are the same as given to the +completion callback of the command transfer::copy::do provided +by the package transfer::copy.

+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
-string text
+

This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question.

+
-channel handle
+

This option specifies that the source of the data is a channel, and +its associated argument is the handle of the channel containing the +data.

+
-file path
+

This option specifies that the source of the data is a file, and its +associated argument is the path of the file containing the data.

+
-variable varname
+

This option specifies that the source of the data is a string stored +in a variable, and its associated argument contains the name of the +variable in question. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-size int
+

This option specifies the size of the data transfer. It is optional +and defaults to -1. This value, and any other value less than zero +signals to transfer all the data from the source.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes transmitted, allowing the user to monitor the progress +of the transmission of the data. The callback is always invoked with +one additional argument, the number of bytes transmitted so far.

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::transmitter T -socketcmd tls::socket ...
+    ...
+
+
+

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 SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/treeql/treeql.html Index: embedded/www/tcllib/files/modules/treeql/treeql.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/treeql/treeql.html @@ -0,0 +1,654 @@ + + +treeql - Tree Query Language + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

treeql(n) 1.3.1 tcllib "Tree Query Language"

+

Name

+

treeql - Query tree objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require treeql ?1.3.1?
    • +
+ +
+
+

Description

+

This package provides objects which can be used to query and transform +tree objects following the API of tree objects created by the package +struct::tree.

+

The tree query and manipulation language used here, TreeQL, is +inspired by Cost (See section References for more +information).

+

treeql, the package, is a fairly thin query facility over +tree-structured data types. It implements an ordered set of nodes +(really a list) which are generated and filtered through the +application of TreeQL operators to each node in turn.

+
+

API

+

TreeQL CLASS API

+

The command treeql is a snit::type which implements +the Treeql Query Language. This means that it follows the API for +class commands as specified by the package snit. +Its general syntax is

+
+
treeql objectname -tree tree ?-query query? ?-nodes nodes? ?args...?
+

The command creates a new tree query object and returns the fully +qualified name of the object command as its result. +The API the returned command is following is described in the section +TreeQL OBJECT API

+

Each query object is associated with a single tree object. This +is the object all queries will be run against.

+

If the option -nodes was specified then its argument is +treated as a list of nodes. This list is used to initialize the node +set. It defaults to the empty list.

+

If the option -query was specified then its argument will be +interpreted as an object, the parent query of this query. It +defaults to the object itself. All queries will be interpreted in the +environment of this object.

+

Any arguments coming after the options are treated as a query and run +immediately, after the node set has been initialized. This +uses the same syntax for the query as the method query.

+

The operations of the TreeQL available for this are explained in the +section about The Tree Query Language. This section also +explains the term node set used above.

+
+
+

TreeQL OBJECT API

+

As treeql has been implemented in snit all the +standard methods of snit-based classes are available to the +user and therefore not listed here. Please read the documentation for +snit for what they are and what functionality they provide

+

The methods provided by the package treeql itself are listed +and explained below.

+
+
qo query args...
+

This method interprets its arguments as a series of TreeQL operators +and interpretes them from the left to right (i.e. first to last). +Note that the first operator uses the node set currently +known to the object to perform its actions. +In other words, the node set is not cleared, or +modified in other ways, before the query is run. This allows the user +to run several queries one after the other and have each use the +results of the last. Any initialization has to be done by any query +itself, using TreeQL operators. +The result of the method is the node set after the last +operator of the query has been executed.

+

Note that uncaught errors will leave the node set of +the object in an intermediate state, per the TreeQL operators which +were executed successfully before the error occurred.

+

The above means in detail that:

+
    +

  1. The first argument is interpreted as the name of a query operator, the +number of arguments required by that operator is then determined, and +taken from the immediately following arguments.

    +

    Because of this operators cannot have optional arguments, all +arguments have to be present as defined. Failure to do this will, at +least, confuse the query interpreter, but more likely cause errors.

    2. +

  2. The operator is applied to the current node set, yielding a new node +set, and/or manipulating the tree object the query object is connected +to.

    3. +

  3. The arguments used (i.e. operator name and arguments) are removed from +the list of method arguments, and then the whole process is repeated +from step [1], until the list of arguments is empty or an error +occurred.

    4. +
+
+    # q is the query object.
+    q query root children get data
+    # The above query
+    # - Resets the node set to the root node - root
+    # - Adds the children of root to the set - children
+    # - Replaces the node set with the       - get data
+    #   values for the attribute 'data',
+    #   for all nodes in the set which
+    #   have such an attribute.
+    # - And returns this information.
+    # Below we can see the same query, but rewritten
+    # to show the structure as it is seen by the query
+    # interpreter.
+    q query \\
+	    root \\
+	    children \\
+	    get data
+
+

The operators of the TreeQL language available for this are explained +in the section about The Tree Query Language. This section +also explains the term node set used above.

+
qo result
+

This method returns a list containing the current node set.

+
qo discard
+

This method returns the current node set (like method +result), but also destroys the query object (qo). +This is useful when constructing and using sub-queries (%AUTO% objects +immediately destroyed after use).

+
+
+
+

The Tree Query Language

+

This and the following sections specify the Tree Query Language used +by the query objects of this package in detail.

+

First we explain the general concepts underneath the language which +are required to comprehend it. This is followed by the specifications +for all the available query operators. They fall into eight +categories, and each category has its own section.

+
    +

  1. TreeQL Concepts

    2. +

  2. Structural generators

    3. +

  3. Attribute Filters

    4. +

  4. Attribute Mutators

    5. +

  5. Attribute String Accessors

    6. +

  6. Sub-queries

    7. +

  7. Node Set Operators

    8. +

  8. Node Set Iterators

    9. +

  9. Typed node support

    10. +
+

TreeQL Concepts

+

The main concept which has to be understood is that of the +node set. +Each query object maintains exactly one such node set, and +essentially all operators use it and input argument and for their +result. +This structure simply contains the handles of all nodes which are +currently of interest to the query object. +To name it a set is a bit of a misnomer, because

+
    +

  1. A node (handle) can occur in the structure more than once, and

    2. +

  2. the order of nodes in the structure is important as well. +Whenever an operator processes all nodes in the node set it will do so +in the order they occur in the structure.

    3. +
+

Regarding the possible multiple occurrence of a node, consider a node +set containing two nodes A and B, both having node P as their +immediate parent. Application of the TreeQL operator "parent" will +then add P to the new node set twice, once per node it was parent +of. I.e. the new node set will then be {P P}.

+
+

Structural generators

+

All tree-structural operators locate nodes in the tree based on a +structural relation ship to the nodes currently in the set and then +replace the current node set with the set of nodes found +Nodes which fulfill such a relationship multiple times are added to +the result as often as they fulfill the relationship.

+

It is important to note that the found nodes are collected in a +separate storage area while processing the node set, and are added to +(or replacing) the current node set only after the current node set +has been processed completely. +In other words, the new nodes are not processed by the operator +as well and do not affect the iteration.

+

When describing an operator the variable N will be used to refer +to any node in the node set.

+
+
ancestors
+

Replaces the current node set with the ancestors for all nodes N +in the node set, should N have a parent. In other words, nodes +without a parent do not contribute to the new node set. In other +words, uses all nodes on the path from node N to root, in this +order (root last), for all nodes N in the node set. This +includes the root, but not the node itself.

+
rootpath
+

Replaces the current node set with the ancestors for all nodes N +in the node set, should N have a parent. In other words, nodes +without a parent do not contribute to the new node set. +In contrast to the operator ancestors the nodes are added in +reverse order however, i.e. the root node first.

+
parent
+

Replaces the current node set with the parent of node N, for all +nodes N in the node set, should N have a parent. In other +words, nodes without a parent do not contribute to the new node set.

+
children
+

Replaces the current node set with the immediate children of node +N, for all nodes N in the node set, should N have +children. In other words, nodes without children do not contribute to +the new node set.

+
left
+

Replaces the current node set with the previous/left sibling for all +nodes N in the node set, should N have siblings to the +left. In other words, nodes without left siblings do not contribute to +the new node set.

+
right
+

Replaces the current node set with the next/right sibling for all +nodes N in the node set, should N have siblings to the +right. In other words, nodes without right siblings do not contribute +to the new node set.

+
prev
+

Replaces the current node set with all previous/left siblings of node +N, for all nodes N in the node set, should N have +siblings to the left. In other words, nodes without left siblings are +ignored. The left sibling adjacent to the node is added first, and the +leftmost sibling last (reverse tree order).

+
esib
+

Replaces the current node set with all previous/left siblings of node +N, for all nodes N in the node set, should N have +siblings to the left. In other words, nodes without left siblings are +ignored. The leftmost sibling is added first, and the left sibling +adjacent to the node last (tree order).

+

The method name is a shorthand for Earlier SIBling.

+
next
+

Replaces the current node set with all next/right siblings of node +N, for all nodes N in the node set, should N have +siblings to the right. In other words, nodes without right siblings do +not contribute to the new node set. The right sibling adjacent to the +node is added first, and the rightmost sibling last (tree order).

+
root
+

Replaces the current node set with a node set containing a single +node, the root of the tree.

+
tree
+

Replaces the current node set with a node set containing all nodes +found in the tree. The nodes are added in pre-order (parent first, +then children, the latter from left to right, first to last).

+
descendants
+

Replaces the current node set with the nodes in all subtrees rooted at +node N, for all nodes N in the node set, should N +have children. In other words, nodes without children do not +contribute to the new node set.

+

This is like the operator children, but covers the children +of children as well, i.e. all the proper descendants. "Rooted +at N" means that N itself is not added to the new set, +which is also implied by proper descendants.

+
subtree
+

Like operator descendants, but includes the node N. In +other words:

+

Replaces the current node set with the nodes of the subtree of node +N, for all nodes N in the node set, should N have +children. In other words, nodes without children do not contribute to +the new node set. I.e this is like the operator children, but +covers the children of children, etc. as well. "Of N" means that +N itself is added to the new set.

+
forward
+

Replaces the current node set with the nodes in the subtrees rooted at +the right siblings of node N, for all nodes N in the node +set, should N have right siblings, and they children. In other +words, nodes without right siblings, and them without children are +ignored.

+

This is equivalent to the operator sequence

+
next descendants
+
+
later
+

This is an alias for the operator forward.

+
backward
+

Replaces the current node set with the nodes in the flattened previous +subtrees, in reverse tree order.

+

This is nearly equivalent to the operator sequence

+
prev descendants
+

The only difference is that this uses the nodes in reverse order.

+
earlier
+

Replaces the current node set with the nodes in the flattened previous +subtrees, in tree order.

+

This is equivalent to the operator sequence

+
prev subtree
+
+
+
+

Attribute Filters

+

These operators filter the node set by reference to attributes of +nodes and their properties. Filter means that all nodes not fulfilling +the criteria are removed from the node set. In other words, the node +set is replaced by the set of nodes fulfilling the filter criteria.

+
+
hasatt attr
+

Reduces the node set to nodes which have an attribute named +attr.

+
withatt attr value
+

Reduces the node set to nodes which have an attribute named +attr, and where the value of that attribute is equal to +value (The "==" operator is string equal -nocase).

+
withatt! attr val
+

This is the same as withatt, but all nodes in the node set +have to have the attribute, and the "==" operator is +string equal, i.e. no -nocase. +The operator will fail with an error if they don't have the attribute.

+
attof attr vals
+

Reduces the node set to nodes which which have an attribute named +attr and where the value of that attribute is contained in the +list vals of legal values. The contained-in operator used here +does glob matching (using the attribute value as pattern) and ignores +the case of the attribute value, but not for the elements of +vals.

+
attmatch attr match
+

Same as withatt, but string match is used as the "==" +operator, and match is the pattern checked for.

+

Note that match is a interpreted as a partial argument +list for string match. This means that it is +interpreted as a list containing the pattern, and the pattern element +can be preceded by options understand by string match, like +-nocase. +This is especially important should the pattern contain spaces. It has +to be wrapped into a list for correct interpretation by this operator

+
+
+

Attribute Mutators

+

These operators change node attributes within the underlying tree. In +other words, all these operators have side effects.

+
+
set attr val
+

Sets the attribute attr to the value val, for all nodes +N in the node set. +The operator will fail if a node does not have an attribute named +attr. The tree will be left in a partially modified state.

+
unset attr
+

Unsets the attribute attr, for all nodes N in the node +set. +The operator will fail if a node does not have an attribute named +attr. The tree will be left in a partially modified state.

+
+
+

Attribute String Accessors

+

These operators retrieve the values of node attributes from the +underlying tree. The collected results are stored in the node set, but +are not actually nodes.

+

In other words, they redefine the semantics of the node set stored by +the query object to contain non-node data after their completion.

+

The query interpreter will terminate after it has finished processing +one of these operators, silently discarding any later query elements. +It also means that our talk about maintenance of a node set is not +quite true. It is a node set while the interpreter is processing +commands, but can be left as an attribute value set at the end of +query processing.

+
+
string op attr
+

Applies the string operator op to the attribute named +attr, for all nodes N in the node set, collects the +results of that application and places them into the node set.

+

The operator will fail if a node does not have an attribute named +attr.

+

The argument op is interpreted as partial argument list for the +builtin command string. Its first word has to be any of the +sub-commands understood by string. This has to be followed by +all arguments required for the subcommand, except the last. that last +argument is supplied by the attribute value.

+
get pattern
+

For all nodes N in the node set it determines all their +attributes with names matching the glob pattern, then the values +of these attributes, at last it replaces the node set with the list of +these attribute values.

+
attlist
+

This is a convenience definition for the operator +getvals *. In other words, it replaces the node set with a +list of the attribute values for all attributes for all nodes N +in the node set.

+
attrs glob
+

Replaces the current node set with a list of attribute lists, one +attribute list per for all nodes N in the node set.

+
attval attname
+

Reduces the current node set with the operator hasatt, and +then replaces it with a list containing the values of the attribute +named attname for all nodes N in the node set.

+
+
+

Sub-queries

+

Sub-queries yield node sets which are then used to augment, reduce or +replace the current node set.

+
+
andq query
+

Replaces the node set with the set-intersection of the node set +generated by the sub-query query and itself.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
orq query
+

Replaces the node set with the set-union of the node set generated by +the sub-query query and itself. Duplicate nodes are removed.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
notq query
+

Replaces the node set with the set of nodes generated by the sub-query +query which are also not in the current node set. In other word +the set difference of itself and the node set generated by the +sub-query.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
+
+

Node Set Operators

+

These operators change the node set directly, without referring to the +tree.

+
+
unique
+

Removes duplicate nodes from the node set, preserving order. In other +words, the earliest occurrence of a node handle is preserved, every +other occurrence is removed.

+
select
+

Replaces the current node set with a node set containing only the +first node from the current node set

+
transform query var body
+

First it interprets the sub-query query, using the current node +set as its initial node set. +Then it iterates over the result of that query, binding the handle of +each node to the variable named in var, and executing the script +body. +The collected results of these executions is made the new node set, +replacing the current one.

+

The script body is executed in the context of the caller.

+
map var body
+

Iterates over the current node set, binding the handle of each node to +the variable named in var, and executing the script body. +The collected results of these executions is made the new node set, +replacing the current one.

+

The script body is executed in the context of the caller.

+
quote val
+

Appends the literal value val to the current node set.

+
replace val
+

Replaces the current node set with the literal list value val.

+
+
+

Node Set Iterators

+
+
foreach query var body
+

Interprets the sub-query query, then performs the equivalent of +operator over on the nodes in the node set created by that +query. The current node set is not changed, except through side +effects from the script body.

+

The script body is executed in the context of the caller.

+
with query body
+

Interprets the query, then runs the script body on the +node set generated by the query. At last it restores the current node +set as it was before the execution of the query.

+

The script body is executed in the context of the caller.

+
over var body
+

Executes the script body for each node in the node set, with the +variable named by var bound to the name of the current node. +The script body is executed in the context of the caller.

+

This is like the builtin foreach, with the node set as the +source of the list to iterate over.

+

The results of executing the body are ignored.

+
delete
+

Deletes all the nodes contained in the current node set from the tree.

+
+
+

Typed node support

+

These filters and accessors assume the existence of an attribute +called @type, and are short-hand forms useful for cost-like +tree query, html tree editing, and so on.

+
+
nodetype
+

Returns the node type of nodes. +Attribute string accessor. This is equivalent to

+
get @type
+
+
oftype t
+

Reduces the node set to nodes whose type is equal to t, with +letter case ignored.

+
nottype t
+

Reduces the node set to nodes whose type is not equal to t, with +letter case ignored.

+
oftypes attrs
+

Reduces set to nodes whose @type is an element in the list attrs +of types. The value of @type is used as a glob pattern, and letter +case is relevant.

+
+
+
+

Examples

+

... TODO ...

+
+

References

+
    +

  1. COST on the Tcler's Wiki.

    2. +

  2. TreeQL on the Tcler's Wiki. Discuss +this package there.

    3. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category treeql of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/try/tcllib_try.html Index: embedded/www/tcllib/files/modules/try/tcllib_try.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/try/tcllib_try.html @@ -0,0 +1,237 @@ + + +try - Forward compatibility implementation of [try] + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

try(n) 1 tcllib "Forward compatibility implementation of [try]"

+

Name

+

try - try - Trap and process errors and exceptions

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require try ?1?
    • +
+ +
+
+

Description

+

This package provides a forward-compatibility implementation of Tcl +8.6's try/finally command (TIP 329), for Tcl 8.5. The code was +directly pulled from Tcl 8.6 revision ?, when try/finally was +implemented as Tcl procedure instead of in C.

+
+
::try body ?handler...? ?finally script?
+

This command executes the script body and, depending on what the +outcome of that script is (normal exit, error, or some other +exceptional result), runs a handler script to deal with the case. Once +that has all happened, if the finally clause is present, the +script it includes will be run and the result of the handler (or +the body if no handler matched) is allowed to continue to +propagate. Note that the finally clause is processed even if +an error occurs and irrespective of which, if any, handler is +used.

+

The handler clauses are each expressed as several words, +and must have one of the following forms:

+
+
on code variableList script
+

This clause matches if the evaluation of body completed with the +exception code code. The code may be expressed as an +integer or one of the following literal words: +ok, error, return, break, or +continue. Those literals correspond to the integers 0 through +4 respectively.

+
trap pattern variableList script
+

This clause matches if the evaluation of body resulted in an +error and the prefix of the -errorcode from the interpreter's +status dictionary is equal to the pattern. The number of prefix +words taken from the -errorcode is equal to the list-length +of pattern, and inter-word spaces are normalized in both the +-errorcode and pattern before comparison.

+

The variableList word in each handler is always +interpreted as a list of variable names. If the first word of the list +is present and non-empty, it names a variable into which the result of +the evaluation of body (from the main try) will be placed; +this will contain the human-readable form of any errors. If the second +word of the list is present and non-empty, it names a variable into +which the options dictionary of the interpreter at the moment of +completion of execution of body will be placed.

+

The script word of each handler is also always +interpreted the same: as a Tcl script to evaluate if the clause is +matched. If script is a literal - and the handler +is not the last one, the script of the following handler +is invoked instead (just like with the switch command).

+

Note that handler clauses are matched against in order, +and that the first matching one is always selected. +At most one handler clause will selected. +As a consequence, an on error will mask any subsequent +trap in the try. Also note that on error is +equivalent to trap {}.

+

If an exception (i.e. any non-ok result) occurs during +the evaluation of either the handler or the finally +clause, the original exception's status dictionary will be added to +the new exception's status dictionary under the -during key.

+
+
+
+

EXAMPLES

+

Ensure that a file is closed no matter what:

+
+set f [open /some/file/name a]
+try {
+    puts \$f "some message"
+    # ...
+} finally {
+    close \$f
+}
+
+

Handle different reasons for a file to not be openable for reading:

+
+try {
+    set f [open /some/file/name]
+} trap {POSIX EISDIR} {} {
+    puts "failed to open /some/file/name: it's a directory"
+} trap {POSIX ENOENT} {} {
+    puts "failed to open /some/file/name: it doesn't exist"
+}
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category try of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

catch(n), error(n), return(n), throw(n)

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/uev/uevent.html Index: embedded/www/tcllib/files/modules/uev/uevent.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/uev/uevent.html @@ -0,0 +1,283 @@ + +uevent - User events + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

uevent(n) 0.3.1 tcllib "User events"

+

Name

+

uevent - User events

+
+ + +

Description

+

This package provides a general facility for the handling of user +events. Allows the binding of arbitrary commands to arbitrary events +on arbitrary tags, removal of bindings, and event generation.

+

The main difference to the event system built into the Tcl/Tk core is +that the latter can generate only virtual events, and only for +widgets. It is not possible to use the builtin facilities to bind to +events on arbitrary (pseudo-)objects, nor is it able to generate +events for such.

+

Here we can, by assuming that each object in question is represented +by its own tag. Which is possible as we allow arbitrary tags.

+

More differences:

+
    +

  1. The package uses only a two-level hierarchy, tags and events, to +handle everything, whereas the Tcl/Tk system uses three levels, i.e. +objects, tags, and events, with a n:m relationship between objects and +tags.

    2. +

  2. This package triggers all bound commands for a tag/event combination, +and they are independent of each other. A bound command cannot force +the event processing core to abort the processing of command coming +after it.

    3. +
+
+

API

+

The package exports eight commands, as specified below. Note that when +the package is used from within Tcl 8.5+ all the higher commands are +ensembles, i.e. the :: separators can be replaceed by spaces.

+
+
::uevent::bind tag event command
+

Using this command registers the command prefix to be triggered +when the event occurs for the tag. The result of the +command is an opaque token representing the binding. Note that if the +same combination of <tag,event,command> is used +multiple times the same token is returned by every call.

+

The signature of the command prefix is

+
+
command tag event details
+
+
+

where details contains the argument(s) of the event. Its +contents are event specific and have to be agreed upon between actual +event generator and consumer. This package simply transfers the +information and does not perform any processing beyond that.

+
::uevent::unbind token
+

This command releases the event binding represented by the +token. The token has to be the result of a call to +::uevent::bind. The result of the command is the empty string.

+
::uevent::generate tag event ?details?
+

This command generates an event for the tag, triggering +all commands bound to that combination. The details argument is +simply passed unchanged to all event handlers. It is the +responsibility of the code generating and consuming the event to have +an agreement about the format and contents of the information carried +therein. The result of the command is the empty string.

+

Note that all bound commands are triggered, independently of each +other. The event handlers cannot assume a specific order. They are +also not called synchronously with the invokation of this +command, but simply put into the event queue for processing when the +system returns to the event loop.

+

Generating an event for an unknown tag, or for a +<tag,event> combination which has no commands bound to it +is allowed, such calls will be ignored.

+
::uevent::list
+

In this form the command returns a list containing the names of all +tags which have events with commands bound to them.

+
::uevent::list tag
+

In this format the command returns a list containing the names of all +events for the tag with commands bound to them. Specifying an +unknown tag, i.e. a tag without event and commands, will cause the +command to throw an error.

+
::uevent::list tag event
+

In this format the command returns a list containing all commands +bound to the event for the tag. Specifying an unknown tag +or unknown event, will cause the command to throw an error.

+
::uevent::watch::tag::add pattern command
+

This command sets up a sort of reverse events. Events generated, +i.e. the command prefix invoked, when observers bind to and +unbind from specific tags.

+

Note that the command prefix is only invoked twice per tag, +first when the first command is bound to any event of the tag, and +second when the last command bound to the tag is removed.

+

The signature of the command prefix is

+
+
{*}command bound tag
+
+
{*}command unbound tag
+
+
+

The result of the command is a token representing the watcher.

+
::uevent::watch::tag::remove token
+

This command removes a watcher for (un)bind events on tags.

+

The result of the command is the empty string.

+
::uevent::watch::event::add tag_pattern event_pattern command
+

This command sets up a sort of reverse events. Events generated, +i.e. the command prefix invoked, when observers bind to and +unbind from specific combinations of tags and events.

+

Note that the command prefix is only invoked twice per +tag/event combination, first when the first command is bound to it, +and second when the last command bound to the it is removed.

+

The signature of the command prefix is

+
+
{*}command bound tag event
+
+
{*}command unbound tag event
+
+
+

The result of the command is a token representing the watcher.

+
::uevent::watch::event::remove token
+

This command removes a watcher for (un)bind events on tag/event +combinations.

+

The result of the command is the empty string.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uevent of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/uev/uevent_onidle.html Index: embedded/www/tcllib/files/modules/uev/uevent_onidle.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/uev/uevent_onidle.html @@ -0,0 +1,183 @@ + +uevent::onidle - User events + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

uevent::onidle(n) 0.1 tcllib "User events"

+

Name

+

uevent::onidle - Request merging and deferal to idle time

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require uevent::onidle ?0.1?
    • +
  • package require logger
    • +
+ +
+
+

Description

+

This package provides objects which can merge multiple requestes for +an action and execute the action the moment the system (event loop) +becomes idle. The action to be run is configured during object +construction.

+
+

API

+

The package exports a class, uevent::onidle, as specified +below.

+
+
::uevent::onidle objectName commandprefix
+

The command creates a new onidle object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object.

+

The commandprefix is the action to perform when the event loop +is idle and the user asked for it using the method request +(See below).

+
+

The object commands created by the class commands above have +the form:

+
+
objectName request
+

This method requests the execution of the command prefix specified +during the construction of objectName the next time the event +loop is idle. Multiple requests are merged and cause only one +execution of the command prefix.

+
+
+

Examples

+

Examples of this type of deferal are buried in the (C-level) +implementations all the Tk widgets, defering geometry calculations and +window redraw activity in this manner.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uevent of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/units/units.html Index: embedded/www/tcllib/files/modules/units/units.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/units/units.html @@ -0,0 +1,475 @@ + + +units - Convert and manipulate quantities with units + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

units(n) 1.2 tcllib "Convert and manipulate quantities with units"

+

Name

+

units - unit conversion

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.1
    • +
  • package require units ?2.1?
    • +
+ +
+
+

Description

+

This library provides a conversion facility from a variety of +scientific and engineering shorthand notations into floating point +numbers. This allows application developers to easily convert +values with different units into uniformly scaled numbers.

+

The units conversion facility is also able to convert between +compatible units. If, for example, a application is expecting a value +in ohms (Resistance), and the user specifies units of +milliwebers/femtocoulomb, the conversion routine will +handle it appropriately. An error will be generated if an incorrect +conversion is attempted.

+

Values are scaled from one set of units to another by dimensional +analysis. Both the value units and the target units are reduced into +primitive units and a scale factor. Units are checked for +compatibility, and the scale factors are applied by multiplication and +division. This technique is extremely flexible and quite robust.

+

New units and new unit abbreviations can be defined in terms of +existing units and abbreviations. It is also possible to define a new +primitive unit, although that will probably be unnecessary. New units +will most commonly be defined to accommodate non-SI measurement +systems, such as defining the unit inch as 2.54 cm.

+
+

COMMANDS

+
+
::units::convert value targetUnits
+

Converts the value string into a floating point number, scaled to the +specified targetUnits. The value string may contain a +number and units. If units are specified, then they must be +compatible with the targetUnits. If units are not specified +for the value, then it will be scaled to the target units. For +example,

+
+% ::units::convert "2.3 miles" km
+3.7014912
+% ::units::convert 300m/s miles/hour
+671.080887616
+% ::units::convert "1.0 m kg/s^2" newton
+1.0
+% ::units::convert 1.0 millimeter
+1000.0
+
+
+
::units::reduce unitString
+

Returns a unit string consisting of a scale factor followed by a space +separated list of sorted and reduced primitive units. The reduced +unit string may include a forward-slash (separated from the +surrounding primitive subunits by spaces) indicating that the +remaining subunits are in the denominator. Generates an error if the +unitString is invalid.

+
+% ::units::reduce pascal
+1000.0 gram / meter second second
+
+
+
::units::new name baseUnits
+

Creates a new unit conversion with the specified name. The new unit +name must be only alphabetic (upper or lower case) letters. +The baseUnits string can consist of any valid units conversion +string, including constant factors, numerator and denominator parts, +units with prefixes, and exponents. The baseUnits may contain any +number of subunits, but it must reduce to primitive units. BaseUnits +could also be the string -primitive to represent a new +kind of quantity which cannot be derived from other units. But you +probably would not do that unless you have discovered some kind of new +universal property.

+
+% ::units::new furlong "220 yards"
+% ::units::new fortnight "14 days"
+% ::units::convert 100m/s furlongs/fortnight
+601288.475303
+
+
+
+
+

UNIT STRING FORMAT

+

Value and unit string format is quite flexible. It is possible to +define virtually any combination of units, prefixes, and powers. +Valid unit strings must conform to these rules.

+
    +

  • A unit string consists of an optional scale factor followed by zero or +more subunits. The scale factor must be a valid floating point +number, and may or may not be separated from the subunits. The scale +factor could be negative.

    • +

  • Subunits are separated form each other by one or more separator +characters, which are space (" "), hyphen ("-"), asterisk ("*"), and +forward-slash ("/"). Sure, go ahead and complain about using a minus +sign ("-") to represent multiplication. It just isn't sound +mathematics, and, by rights, we should require everyone to use the +asterisk ("*") to separate all units. But the bottom line is that +complex unit strings like m-kg/s^2 are pleasantly +readable.

    • +

  • The forward-slash seperator ("/") indicates that following subunits are +in the denominator. There can be at most one forward-slash separator.

    • +

  • Subunits can be floating point scale factors, but with the exception +of the leading scale factor, they must be surrounded by valid +separators. Subunit scale factors cannot be negative. (Remember that +the hyphen is a unit separator.)

    • +

  • Subunits can be valid units or abbreviations. They may include a +prefix. They may include a plural suffix "s" or "es". They may also +include a power string denoted by a circumflex ("^"), followed by a +integer, after the unit name (or plural suffix, if there is one). +Negative exponents are not allowed. (Remember that the hyphen is a +unit separator.)

    • +
+

Example Valid Unit Strings

+
+Unit String              Reduced Unit String
+------------------------------------------------------------
+meter                    1.0 meter
+kilometer                1000.0 meter
+km                       1000.0 meter
+km/s                     1000.0 meter / second
+/microsecond             1000000.0 / second
+/us                      1000000.0 / second
+kg-m/s^2                 1000.0 gram meter / second second
+30second                 30.0 second
+30 second                30.0 second
+30 seconds               30.0 second
+200*meter/20.5*second    9.75609756098 meter / second
+
+
+
+

SI UNITS

+

The standard SI units are predefined according to NIST Special +Publication 330. Standard units for both SI Base Units (Table +1) and SI Derived Units with Special Names (Tables 3a and 3b) are +included here for reference. Each standard unit name and abbreviation +are included in this package.

+

SI Base Units

+
+Quantity                Unit Name    Abbr.
+---------------------------------------------
+Length                  meter        m
+Mass                    kilogram     kg
+Time                    second       s
+Current                 ampere       A
+Temperature             kelvin       K
+Amount                  mole         mol
+Luminous Intensity      candela      cd
+
+
+

SI Derived Units with Special Names

+
+Quantity                Unit Name    Abbr.   Units     Base Units
+--------------------------------------------------------------------
+plane angle             radian      rad     m/m       m/m
+solid angle             steradian   sr      m^2/m^2   m^2/m^2
+frequency               hertz       Hz                /s
+force                   newton      N                 m-kg/s^2
+pressure                pascal      Pa      N/m^2     kg/m-s^2
+energy, work            joule       J       N-m       m^2-kg/s^2
+power, radiant flux     watt        W       J/s       m^2-kg/s^3
+electric charge         coulomb     C                 s-A
+electric potential      volt        V       W/A       m^2-kg/s^3-A
+capacitance             farad       F       C/V       s^4-A^2/m^2-kg
+electric resistance     ohm                 V/A       m^2-kg/s^3-A^2
+electric conductance    siemens     S       A/V       s^3-A^2/m^2-kg
+magnetic flux           weber       Wb      V-s       m^2-kg/s^2-A
+magnetic flux density   tesla       T       Wb/m^2    kg/s^2-A
+inductance              henry       H       Wb/A      m^2-kg/s^2-A^2
+luminous flux           lumen       lm                cd-sr
+illuminance             lux         lx      lm/m^2    cd-sr/m^2
+activity (of a
+radionuclide)           becquerel   Bq                /s
+absorbed dose           gray        Gy      J/kg      m^2/s^2
+dose equivalent         sievert     Sv      J/kg      m^2/s^2
+
+

Note that the SI unit kilograms is actually implemented as grams +because 1e-6 kilogram = 1 milligram, not 1 microkilogram. The +abbreviation for Electric Resistance (ohms), which is the omega +character, is not supported.

+

Also note that there is no support for Celsius or Farenheit +temperature. The units conversion routines can only scale values +with multiplication and division, so it is not possible to convert +from thermodynamic temperature (kelvins) to absolute degrees Celsius +or Farenheit. Conversion of thermodynamic quantities, such as +thermal expansion (per unit temperature), however, are easy to add +to the units library.

+

SI Units can have a multiple or sub-multiple prefix. The prefix or its +abbreviation should appear before the unit, without spaces. Compound +prefixes are not allowed, and a prefix should never be used alone. +These prefixes are defined in Table 5 of Special Publication +330.

+
+

SI Prefixes

+
+Prefix Name     Abbr.   Factor
+---------------------------------------
+yotta           Y       1e24
+zetta           Z       1e21
+exa             E       1e18
+peta            P       1e15
+tera            T       1e12
+giga            G       1e9
+mega            M       1e6
+kilo            k       1e3
+hecto           h       1e2
+deka            da      1e1
+deca                    1e1
+deci            d       1e-1
+centi           c       1e-2
+milli           m       1e-3
+micro           u       1e-6
+nano            n       1e-9
+pico            p       1e-12
+femto           f       1e-15
+atto            a       1e-18
+zepto           z       1e-21
+yocto           y       1e-24
+
+

Note that we define the same prefix with both the USA ("deka") and +non-USA ("deca") spellings. Also note that we take the liberty of +allowing "micro" to be typed as a "u" instead of the Greek character +mu.

+

Many non-SI units are commonly used in applications. Appendix B.8 of +NIST Special Publication 811 lists many non-SI conversion +factors. It is not possible to include all possible unit definitions +in this package. In some cases, many different conversion factors +exist for a given unit, depending on the context. (The appendix lists +over 40 conversions for British thermal units!) Application specific +conversions can always be added using the new +command, but some well known and often used conversions are included +in this package.

+
+

Non-SI Units

+
+Unit Name            Abbr.    Base Units
+--------------------------------------------------
+angstrom                      1.0E-10 m
+astronomicalUnit     AU       1.495979E11 m
+atmosphere                    1.01325E5 Pa
+bar                           1.0E5 Pa
+calorie                       4.1868 J
+curie                         3.7E10 Bq
+day                           8.64E4 s
+degree                        1.745329E-2 rad
+erg                           1.0E-7 J
+faraday                       9.648531 C
+fermi                         1.0E-15 m
+foot                 ft       3.048E-1 m
+gauss                         1.0E-4 T
+gilbert                       7.957747E-1 A
+grain                gr       6.479891E-5 kg
+hectare              ha       1.0E4 m^2
+hour                 h        3.6E3 s
+inch                 in       2.54E-2 m
+lightYear                     9.46073E15 m
+liter                L        1.0E-3 m^3
+maxwell              Mx       1.0E-8 Wb
+mho                           1.0 S
+micron                        1.0E-6 m
+mil                           2.54E-5 m
+mile                 mi       1.609344E3 m
+minute               min      6.0E1 s
+parsec               pc       3.085E16 m
+pica                          4.233333E-3 m
+pound                lb       4.535924E-1 kg
+revolution                    6.283185 rad
+revolutionPerMinute  rpm      1.047198E-1 rad/s
+yard                 yd       9.144E-1 m
+year                          3.1536E7 s
+
+
+

Quantities and Derived Units with Special Names

+

This units conversion package is limited specifically to unit +reduction, comparison, and scaling. This package does not consider +any of the quantity names for either base or derived units. A similar +implementation or an extension in a typed or object-oriented language +might introduce user defined types for the quantities. Quantity type +checking could be used, for example, to ensure that all +length values properly reduced to meters, or +that all velocity values properly reduced to +meters/second.

+

A C implementation of this package has been created to work in +conjunction with the Simplified Wrapper Interface Generator +(http://www.swig.org/). That package (units.i) exploits SWIG's typemap +system to automatically convert script quantity strings into floating +point quantities. Function arguments are specified as quantity types +(e.g., typedef float Length), and target units (expected +by the C application code) are specified in an associative array. +Default units are also defined for each quantity type, and are applied +to any unit-less quantity strings.

+

A units system enhanced with quantity type checking might benefit from +inclusion of other derived types which are expressed in terms of +special units, as illustrated in Table 2 of NIST Publication +330. The quantity area, for example, could be +defined as units properly reducing to meter^2, although +the utility of defining a unit named square meter is +arguable.

+
+
+

REFERENCES

+

The unit names, abbreviations, and conversion values are derived from +those published by the United States Department of Commerce Technology +Administration, National Institute of Standards and Technology (NIST) +in NIST Special Publication 330: The International System of +Units (SI) and NIST Special Publication 811: Guide for +the Use of the International System of Units (SI). Both of +these publications are available (as of December 2000) from +http://physics.nist.gov/cuu/Reference/contents.html

+

The ideas behind implementation of this package is based in part on +code written in 1993 by Adrian Mariano which performed dimensional +analysis of unit strings using fixed size tables of C structs. After +going missing in the late 1990's, Adrian's code has reappeared in the +GNU Units program at http://www.gnu.org/software/units/

+
+

AUTHORS

+

Robert W. Techentin

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category units of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/uri/uri.html Index: embedded/www/tcllib/files/modules/uri/uri.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/uri/uri.html @@ -0,0 +1,269 @@ + +uri - Tcl Uniform Resource Identifier Management + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

uri(n) 1.2.2 tcllib "Tcl Uniform Resource Identifier Management"

+

Name

+

uri - URI utilities

+
+ + +

Description

+

This package contains two parts. First it provides regular expressions +for a number of url/uri schemes. Second it provides a number of +commands for manipulating urls/uris and fetching data specified by +them. For the latter this package analyses the requested url/uri and +then dispatches it to the appropriate package (http, ftp, ...) for +actual fetching.

+

The package currently does not conform to +RFC 2396 (http://www.rfc-editor.org/rfc/rfc2396.txt), +but quite likely should be. Patches and other help are welcome.

+
+

COMMANDS

+
+
uri::split url ?defaultscheme?
+

uri::split takes an url, decodes it and then returns a +list of key/value pairs suitable for array set containing the +constituents of the url. If the scheme is missing from the url +it defaults to the value of defaultscheme if it was specified, +or http else. Currently only the schemes http, +ftp, mailto, urn, news, ldap and +file are supported by the package itself. +See section EXTENDING on how to expand that range.

+

The set of constituents of an url (= the set of keys in the returned +dictionary) is dependent on the scheme of the url. The only key which +is therefore always present is scheme. For the following +schemes the constituents and their keys are known:

+
+
ftp
+

user, pwd, host, port, +path, type

+
http(s)
+

user, pwd, host, port, +path, query, fragment. The fragment +is optional.

+
file
+

path, host. The host is optional.

+
mailto
+

user, host. The host is optional.

+
news
+

Either message-id or newsgroup-name.

+
+
uri::join ?key value?...
+

uri::join takes a list of key/value pairs (generated by +uri::split, for example) and returns the canonical url they +represent. Currently only the schemes http, ftp, +mailto, urn, news, ldap and file +are supported. See section EXTENDING on how to expand that +range.

+
uri::resolve base url
+

uri::resolve resolves the specified url relative to +base. In other words: A non-relative url is returned +unchanged, whereas for a relative url the missing parts are +taken from base and prepended to it. The result of this +operation is returned. For an empty url the result is +base.

+
uri::isrelative url
+

uri::isrelative determines whether the specified url is +absolute or relative.

+
uri::geturl url ?options...?
+

uri::geturl decodes the specified url and then dispatches +the request to the package appropriate for the scheme found in the +url. The command assumes that the package to handle the given scheme +either has the same name as the scheme itself (including possible +capitalization) followed by ::geturl, or, in case of this +failing, has the same name as the scheme itself (including possible +capitalization). It further assumes that whatever package was loaded +provides a geturl-command in the namespace of the same name as +the package itself. This command is called with the given url +and all given options. Currently geturl does not handle +any options itself.

+

Note: file-urls are an exception to the rule +described above. They are handled internally.

+

It is not possible to specify results of the command. They depend on +the geturl-command for the scheme the request was dispatched to.

+
uri::canonicalize uri
+

uri::canonicalize returns the canonical form of a URI. The +canonical form of a URI is one where relative path specifications, +ie. . and .., have been resolved.

+
uri::register schemeList script
+

uri::register registers the first element of schemeList as +a new scheme and the remaining elements as aliases for this scheme. It +creates the namespace for the scheme and executes the script in +the new namespace. The script has to declare variables containing the +regular expressions relevant to the scheme. At least the variable +schemepart has to be declared as that one is used to extend +the variables keeping track of the registered schemes.

+
+
+

SCHEMES

+

In addition to the commands mentioned above this package provides +regular expression to recognize urls for a number of url schemes.

+

For each supported scheme a namespace of the same name as the scheme +itself is provided inside of the namespace uri containing the +variable url whose contents are a regular expression to +recognize urls of that scheme. Additional variables may contain +regular expressions for parts of urls for that scheme.

+

The variable uri::schemes contains a list of all supported +schemes. Currently these are ftp, ldap, file, +http, gopher, mailto, news, +wais and prospero.

+
+

EXTENDING

+

Extending the range of schemes supported by uri::split and +uri::join is easy because both commands do not handle the +request by themselves but dispatch it to another command in the +uri namespace using the scheme of the url as criterion.

+

uri::split and uri::join +call Split[string totitle <scheme>] +and Join[string totitle <scheme>] respectively.

+
+

CREDITS

+

Original code (regular expressions) by Andreas Kupries. +Modularisation by Steve Ball, also the split/join/resolve +functionality.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uri of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/uri/urn-scheme.html Index: embedded/www/tcllib/files/modules/uri/urn-scheme.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/uri/urn-scheme.html @@ -0,0 +1,166 @@ + +uri_urn - Tcl Uniform Resource Identifier Management + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

uri_urn(n) 1.1.2 tcllib "Tcl Uniform Resource Identifier Management"

+

Name

+

uri_urn - URI utilities, URN scheme

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require uri::urn ?1.1.2?
    • +
+ +
+
+

Description

+

This package provides two commands to quote and unquote the disallowed +characters for url using the urn scheme, registers the scheme +with the package uri, and provides internal helpers which +will be automatically used by the commands uri::split and +uri::join of package uri to handle urls using the +urn scheme.

+
+

COMMANDS

+
+
uri::urn::quote url
+

This command quotes the characters disallowed by the urn scheme +(per RFC 2141 sec2.2) in the url and returns the modified url as +its result.

+
uri::urn::unquote url
+

This commands performs the reverse of ::uri::urn::quote. It +takes an urn url, removes the quoting from all disallowed +characters, and returns the modified urls as its result.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uri of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/uuid/uuid.html Index: embedded/www/tcllib/files/modules/uuid/uuid.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/uuid/uuid.html @@ -0,0 +1,182 @@ + +uuid - uuid + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

uuid(n) 1.0.2 tcllib "uuid"

+

Name

+

uuid - UUID generation and comparison

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require uuid ?1.0.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)

    2. +
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uuid of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/cat.html Index: embedded/www/tcllib/files/modules/virtchannel_base/cat.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/cat.html @@ -0,0 +1,175 @@ + + +tcl::chan::cat - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::cat - Concatenation channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::cat ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::cat package provides a command creating +concatenation channels. These are non-seekable channels owning a list +of subordinate channels whose contents they return in order, until all +are exhausted. In this manner the cahnnel is the concatentation of the +contents of all the sub-ordinate channels.

+

Note that the created channels take ownership of the channels +they were constructed with. Whenever they have exhausted one of their +channel it will be closed. Similarly, closing the cat channel will +close all the sub-ordinates it still has.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::core framework.

+

Event handling is delegated to the currently active sub-channel.

+
+

API

+
+
::tcl::chan::cat chan...
+

This command creates the concatenation channel using all the provided +channels, and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/facade.html Index: embedded/www/tcllib/files/modules/virtchannel_base/facade.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/facade.html @@ -0,0 +1,193 @@ + + +tcl::chan::facade - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::facade(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::facade - Facade channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require logger
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::facade ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::facade package provides a command creating +facades to other channels. These are channels which own a single +subordinate channel and delegate all operations to.

+

The main use for facades is the debugging of actions on a +channel. While most of the information could be tracked by a virtual +channel transformation it does not have access to the event-related +operation, and furthermore they are only available in Tcl 8.6.

+

Therefore this channel, usable with Tcl 8.5, and having access +to everything going on for a channel.

+

The intercepted actions on channel are logged through package +logger.

+

Beyond that facades provide the following additional channel +configuration options:

+
+
-self
+

The TclOO object handling the facade.

+
-fd
+

The handle of the subordinate, i.e. wrapped channel.

+
-used
+

The last time the wrapped channel was read from or written to by +the facade, as per clock milliseconds. A value of 0 +indicates that the subordinate channel was not accessed at all, yet.

+
-created
+

The time the facade was created, as per clock milliseconds.

+
-user
+

A free-form value identifying the user of the facade and its +wrapped channel.

+
+

Of these only option -user is writable.

+
+

API

+
+
::tcl::chan::facade chan
+

This command creates the facade channel around the provided +channel chan, and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/fifo.html Index: embedded/www/tcllib/files/modules/virtchannel_base/fifo.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/fifo.html @@ -0,0 +1,171 @@ + + +tcl::chan::fifo - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::fifo(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::fifo - In-memory fifo channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::fifo ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::fifo package provides a command creating +channels which live purely in memory. Access is fifo-like, i.e. things +are read out of the channel in the order they were written to it. +This is equivalent to the fifo channels provided by the package +Mmechan, except that this is written in pure Tcl, not C. On +the other hand, Memchan is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::fifo
+

This command creates a new fifo channel and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/fifo2.html Index: embedded/www/tcllib/files/modules/virtchannel_base/fifo2.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/fifo2.html @@ -0,0 +1,176 @@ + + +tcl::chan::fifo2 - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::fifo2(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::fifo2 - In-memory interconnected fifo channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
  • package require tcl::chan::fifo2 ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::fifo2 package provides a command creating +pairs of channels which live purely in memory and are connected to +each other in a fifo manner. What is written to one half of the pair +can be read from the other half, in the same order. One particular +application for this is communication between threads, with one half +of the pair moved to the thread to talk to. +This is equivalent to the fifo2 channels provided by the package +Mmechan, except that this is written in pure Tcl, not C. On +the other hand, Memchan is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::fifo2
+

This command creates a new connected pair of fifo channels and returns +their handles, as a list containing two elements.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html Index: embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html @@ -0,0 +1,199 @@ + + +tcl::chan::halfpipe - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::halfpipe(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::halfpipe - In-memory channel, half of a fifo2

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::halfpipe package provides a command creating +one half of a tcl::chan::fifo2 pair. Writing into such a +channel invokes a set of callbacks which then handle the data. This is +similar to a channel handler, except having a much simpler API.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::halfpipe ?-option value...?
+

This command creates a halfpipe channel and configures it with the +callbacks to run when the channel is closed, data was written to it, +or ran empty. See the section Options for the list of +options and associated semantics. +The result of the command is a list containing two elements, the +handle of the new channel, and the object command of the channel +handler, in this order. +The latter is supplied to the caller to provide her with access to the +put method for adding data to the channel.

+

Two halfpipes with a bit of glue logic in the callbacks make +for one tcl::chan::fifo2.

+
objectCmd put bytes
+

This method of the channel handler object puts the data bytes +into the channel so that it can be read from it.

+
+
+

Options

+
+
-close-command cmdprefix
+

This callback is invoked when the channel is closed. +A single argument is supplied, the handle of the channel being closed. +The result of the callback is ignored.

+
-write-command cmdprefix
+

This callback is invoked when data is written to the channel. +Two arguments are supplied, the handle of the channel written to, and the data written. +The result of the callback is ignored.

+
-empty-command cmdprefix
+

This callback is invoked when the channel has run out of data to read. +A single argument is supplied, the handle of the channel.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/memchan.html Index: embedded/www/tcllib/files/modules/virtchannel_base/memchan.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/memchan.html @@ -0,0 +1,173 @@ + + +tcl::chan::memchan - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::memchan(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::memchan - In-memory channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::memchan ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::memchan package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. This is equivalent to the memchan channels provided by +the package Memchan, except that this is written in pure Tcl, +not C. On the other hand, Memchan is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +TclOO.

+

Packages related to this are tcl::chan::string and +tcl::chan::variable.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::memchan
+

This command creates a new memchan channel and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/null.html Index: embedded/www/tcllib/files/modules/virtchannel_base/null.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/null.html @@ -0,0 +1,173 @@ + + +tcl::chan::null - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::null(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::null - Null channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::null ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::null package provides a command creating null +channels, i.e. write-only channels which immediately forget whatever +is written to them. This is equivalent to the null channels provided by +the package Memchan, except that this is written in pure Tcl, +not C. On the other hand, Memchan is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +TclOO.

+

Packages related to this are tcl::chan::zero and +tcl::chan::nullzero.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::null
+

This command creates a new null channel and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html Index: embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html @@ -0,0 +1,170 @@ + + +tcl::chan::nullzero - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::nullzero(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::nullzero - Null/Zero channel combination

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::nullzero ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::nullzero package provides a command creating channels, +which are a combination of null and zero devices. They immediately forget +whatever is written to them, and on reading return an infinite stream of null +characters.

+

Packages related to this are tcl::chan::null and +tcl::chan::zero.

+

The internal TclOO class implementing the channel handler +is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::nullzero
+

This command creates a new nullzero channel and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/random.html Index: embedded/www/tcllib/files/modules/virtchannel_base/random.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/random.html @@ -0,0 +1,174 @@ + + +tcl::chan::random - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::random(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::random - Random channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::random ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::random package provides a command creating +random channels, i.e. read-only channels which return an infinite +stream of pseudo-random characters upon reading. This is similar to +the random channels provided by the package Memchan, except +that this is written in pure Tcl, not C, and uses a much simpler +generator as well. On the other hand, Memchan is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::random seed
+

This command creates a new random channel and returns its handle. +The seed is a list of integer numbers used to initialize the +internal feedback shift register of the generator.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/randseed.html Index: embedded/www/tcllib/files/modules/virtchannel_base/randseed.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/randseed.html @@ -0,0 +1,169 @@ + + +tcl::chan::randseed - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::randseed(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::randseed - Utilities for random channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::randseed ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::randseed package provides a a few utility commands to help with the seeding of tcl::chan::random channels.

+
+

API

+
+
::tcl::randomseed
+

This command creates returns a list of seed integers suitable as seed +argument for random channels. The numbers are derived from the process +id, current time, and Tcl random number generator.

+
::tcl::combine seed1 seed2
+

This command takes to seed lists and combines them into a single list +by XORing them elementwise, modulo 256. If the lists are not of equial +length the shorter of the two is padded with 0s before merging.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/std.html Index: embedded/www/tcllib/files/modules/virtchannel_base/std.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/std.html @@ -0,0 +1,170 @@ + + +tcl::chan::std - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::std(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::std - Standard I/O, unification of stdin and stdout

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::std ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::std package provides a command creating +a standard channel which unifies stdin and stdout into a single +read- and writable channel. The result is not seek-able, like +the original standard channels.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::core framework.

+
+

API

+
+
::tcl::chan::std
+

This command creates the std channel and returns its handle.

+

The channel is created only once, on the first call, and all +future calls simply return this handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/string.html Index: embedded/www/tcllib/files/modules/virtchannel_base/string.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/string.html @@ -0,0 +1,173 @@ + + +tcl::chan::string - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::string(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::string - Read-only in-memory channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::string ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::string package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. +In contrast to the channels created by tcl::chan::memchan +they are read-only however, their content is provided at the time of +construction and immutable afterward.

+

Packages related to this are tcl::chan::memchan and +tcl::chan::variable.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::string content
+

This command creates a new string channel and returns its handle. The +channel provides random read-only access to the content string.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html Index: embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html @@ -0,0 +1,168 @@ + + +tcl::chan::textwindow - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::textwindow(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::textwindow - Textwindow channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::textwindow ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::textwindow package provides a command creating +write-only channels connected to text widgets. Anything written to the +channel is printed into the associated widget.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::textwindow widget
+

This command creates a new textwindow channel and returns its handle. +Data written to this channel will appear in the associated widget.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/variable.html Index: embedded/www/tcllib/files/modules/virtchannel_base/variable.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/variable.html @@ -0,0 +1,174 @@ + + +tcl::chan::variable - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::variable(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::variable - In-memory channel using variable for storage

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::variable ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::variable package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. +In contrast to the channels created by tcl::chan::memchan +the data is not hidden in the channel however, but stored in an +associated variable, specified at the time of construction.

+

Packages related to this are tcl::chan::memchan and +tcl::chan::string.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::variable varname
+

This command creates a new variable channel and returns its handle. +The content of the channel is stored in the associated namespace +variable varname.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/zero.html Index: embedded/www/tcllib/files/modules/virtchannel_base/zero.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_base/zero.html @@ -0,0 +1,173 @@ + + +tcl::chan::zero - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::zero(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::zero - Zero channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::zero ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::zero package provides a command creating zero +channels, i.e. read-only channels which return an infinite stream of null +characters upon reading. This is equivalent to the zero channels +provided by the package Memchan, except that this is written +in pure Tcl, not C. On the other hand, Memchan is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO.

+

Packages related to this are tcl::chan::null and +tcl::chan::nullzero.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::zero
+

This command creates a new zero channel and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/core.html Index: embedded/www/tcllib/files/modules/virtchannel_core/core.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_core/core.html @@ -0,0 +1,197 @@ + + +tcl::chan::core - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::core(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::core - Basic reflected/virtual channel support

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::core package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel (initialization, finalization).

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::chan::core objectName
+

This command creates a new channel core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of channel core instances provides only two methods, both +corresponding to channel handler commands (For reference see +TIP 219). They expect to be called +from whichever object instance the channel core was made a part of.

+
+
objectName initialize thechannel mode
+

This method implements standard behaviour for the initialize +method of channel handlers. Using introspection it finds the handler +methods supported by the instance and returns a list containing their +names, as expected by the support for reflected channels in the Tcl +core.

+

It further remembers the channel handle in an instance variable +for access by sub-classes.

+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It simply destroys itself.

+
objectName destroy
+

Destroying the channel core instance closes the channel it was +initialized for, see the method initialize. When destroyed +from within a call of finalize this does not happen, under +the assumption that the channel is being destroyed by Tcl.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/events.html Index: embedded/www/tcllib/files/modules/virtchannel_core/events.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_core/events.html @@ -0,0 +1,205 @@ + + +tcl::chan::events - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::chan::events(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::events - Event support for reflected/virtual channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::events ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::events package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel supporting event driven IO. It is a +sub-class of tcl::chan::core, inheriting all of its behaviour.

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::chan::events objectName
+

This command creates a new channel event core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of channel event core instances provides only four methods, two +corresponding to channel handler commands (For reference see +TIP 219), and the other two for use by +sub-classes to control event generation. They former expect to be called +from whichever object instance the channel event core was made a part of.

+
+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It overrides the behaviour inherited from +tcl::chan::core and additionally disables any and all event +generation before destroying itself.

+
objectName watch thechannel eventmask
+

This method implements standard behaviour for the watch +method of channel handlers. Called by the IO system whenever the +interest in event changes it updates the instance state to activate +and/or suppress the generation of the events of (non-)interest.

+
objectName allow eventname...
+
+
objectName disallow eventname...
+

These two methods are exported to sub-classes, so that their instances +can notify their event core of the events the channel they implement +can (allow) or cannot (disallow) generate. +Together with the information about the events requested by Tcl's IO +system coming in through the watch method the event core is +able to determine which events it should (not) generate and act +accordingly.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html Index: embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html @@ -0,0 +1,197 @@ + + +tcl::transform::core - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::core(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::core - Basic reflected/virtual channel transform support

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::transform::core ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::core package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel transformation (initialization, finalization).

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::transform::core objectName
+

This command creates a new transform core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of transform core instances provides only two methods, both +corresponding to transform handler commands (For reference see +TIP 230). They expect to be called +from whichever object instance the transform core was made a part of.

+
+
objectName initialize thechannel mode
+

This method implements standard behaviour for the initialize +method of transform handlers. Using introspection it finds the handler +methods supported by the instance and returns a list containing their +names, as expected by the support for reflected transformation in the +Tcl core.

+

It further remembers the channel handle in an instance variable +for access by sub-classes.

+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It simply destroys itself.

+
objectName destroy
+

Destroying the transform core instance closes the channel and transform +it was initialized for, see the method initialize. When destroyed +from within a call of finalize this does not happen, under +the assumption that the channel and transform are being destroyed by Tcl.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html @@ -0,0 +1,190 @@ + + +tcl::transform::adler32 - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::adler32(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::adler32 - Adler32 transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::adler32 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::adler32 package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally continuously computes the adler32 checksums of the data +it has seen for each direction and stores them in Tcl variables +specified at construction time.

+

Related transformations in this module are +tcl::transform::counter, +tcl::transform::crc32, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::adler32 chan -option value...
+

This command creates an adler32 checksumming transformation on top of +the channel chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +adler32 checksum of the data read from the channel.

+

If not specified, or the empty string, the checksum of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +adler32 checksum of the data written to the channel.

+

If not specified, or the empty string, the checksum of the +write direction is not saved.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/base64.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/base64.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/base64.html @@ -0,0 +1,170 @@ + + +tcl::transform::base64 - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::base64(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::base64 - Base64 encoding transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::base64 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::base64 package provides a command +creating a channel transformation which base64 encodes data written to +it, and decodes the data read from it.

+

A related transformations in this module is +tcl::transform::hex.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::base64 chan
+

This command creates a base64 transformation on top of the channel +chan and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/counter.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/counter.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/counter.html @@ -0,0 +1,189 @@ + + +tcl::transform::counter - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::counter(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::counter - Counter transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::counter ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::counterr package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally counts the bytes it has seen for each direction and +stores these counts in Tcl variables specified at construction time.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::crc32, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::counter chan -option value...
+

This command creates a counter transformation on top of the channel +chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +byte count of the data read from the channel.

+

If not specified, or the empty string, the counter of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +byte count of the data written to the channel.

+

If not specified, or the empty string, the counter of the +write direction is not saved.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/crc32.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/crc32.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/crc32.html @@ -0,0 +1,190 @@ + + +tcl::transform::crc32 - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::crc32(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::crc32 - Crc32 transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::crc32 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::crc32 package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally continuously computes the crc32 checksums of the data it +has seen for each direction and stores them in Tcl variables specified +at construction time. The checksum in question is zlib's crc32.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::crc32 chan -option value...
+

This command creates a crc32 checksumming transformation on top of +the channel chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +crc32 checksum of the data read from the channel.

+

If not specified, or the empty string, the checksum of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +crc32 checksum of the data written to the channel.

+

If not specified, or the empty string, the checksum of the +write direction is not saved.

+
+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/hex.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/hex.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/hex.html @@ -0,0 +1,170 @@ + + +tcl::transform::hex - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::hex(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::hex - Hexadecimal encoding transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::hex ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::hex package provides a command creating +a channel transformation which hex encodes data written to it, and +decodes the data read from it.

+

A related transformations in this module is +tcl::transform::base64.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::hex chan
+

This command creates a hex transformation on top of the channel +chan and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/identity.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/identity.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/identity.html @@ -0,0 +1,177 @@ + + +tcl::transform::identity - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::identity(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::identity - Identity transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::identity ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::identity package provides a command +creating an identity channel transformation, which does nothing but +pass the read and written bytes through it unchanged. Not really +useful in an application, however as the prototypical observer +transformation its code is a useful starting point for any other +observers people may wish to write.

+

The transformations in this module which derived from +identity's code are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::crc32, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::identity chan
+

This command creates an identity transformation on top of the channel +chan and returns its handle.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html @@ -0,0 +1,172 @@ + + +tcl::transform::limitsize - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::limitsize(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::limitsize - limiting input

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::limitsize ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::limitsize package provides a command +creating a channel transformation which limits the number of +characters which can be read from the channel. A generator for an +artificial EOF.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::limitsize chan max
+

This command creates a size limiting transformation on top of the +channel chan and returns its handle.

+

max is the number of bytes which can be read from the +channel before EOF is signaled by the transformation. Note that +popping the transformation clears the EOF it generated as well.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/observe.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/observe.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/observe.html @@ -0,0 +1,176 @@ + + +tcl::transform::observe - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::observe(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::observe - Observer transformation, stream copy

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::observe ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::observer package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally copies the data it has seen for each direction into +channels specified at construction time.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::crc32, and +tcl::transform::identity.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::observe chan logw logr
+

This command creates an observer transformation on top of the channel +chan and returns its handle. The channel handles logr and +logw are there the data is copied to.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/otp.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/otp.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/otp.html @@ -0,0 +1,174 @@ + + +tcl::transform::otp - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::otp(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::otp - Encryption via one-time pad

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::otp ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::otp package provides a command creating +a channel transformation which uses externally provided one-time pads +to perform encryption (on writing) and decryption (on reading).

+

A related transformations in this module is +tcl::transform::rot.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::otp chan keychanw keychanr
+

This command creates a one-time pad based encryption transformation on +top of the channel chan and returns its handle.

+

The two channels keychanw and keychanr contain the +one-time pads for the write and read directions, respectively. Their +contents are reads and xored with the bytes written to and read from +the channel.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/rot.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/rot.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/rot.html @@ -0,0 +1,177 @@ + + +tcl::transform::rot - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::rot(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::rot - rot-encryption

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::rot ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::rot package provides a command creating +a channel transformation which performs primitive encryption (on +writing) and decryption (on reading) on the alphabetic characters. The +algorithm is the Caesar-cipher, a specific variant of which is rot13.

+

A related transformations in this module is +tcl::transform::otp.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::rot chan key
+

This command creates a rot encryption transformation on top of the +channel chan and returns its handle.

+

The "key" specifies how far characters are rotated in the +alphabet, and is wrapped to the range "0...25".

+

Note that this transformation affects only bytes in the ranges +ASCII 65...90, and 97...122, i.e. the upper- and lower-case alphabetic +characters, i.e. "A...Z" and "a...z". All other bytes are passed +through unchanged.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html @@ -0,0 +1,172 @@ + + +tcl::transform::spacer - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::spacer(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::spacer - Space insertation and removal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::spacer ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::spacer package provides a command +creating a channel transformation which adds spacing to the data +written to it, and removes such spacing from the data read from it.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::spacer chan n ?space?
+

This command creates a spacer transformation on top of the channel +chan and returns its handle.

+

The space character sequence will be added every n +bytes of data written, and on the read side the same is done in +reverse, removing the spacing. If space is not specified it +defaults to a single space character (ASCII 32).

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/zlib.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/zlib.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/virtchannel_transform/zlib.html @@ -0,0 +1,170 @@ + + +tcl::transform::zlib - Reflected/virtual channel support + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

tcl::transform::zlib(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::zlib - zlib (de)compression

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::zlib ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::zlib package provides a command creating +a channel transformation which zlib compresses the written data, and +decompresses on reading.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::zlib chan ?level?
+

This command creates a zlib compressor transformation on top of the +channel chan and returns its handle.

+

The level specifies how much effort is put into the +compression, from 0 to 9, and defaults to 4.

+
+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/wip/wip.html Index: embedded/www/tcllib/files/modules/wip/wip.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/wip/wip.html @@ -0,0 +1,413 @@ + + +wip - Word Interpreter + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

wip(n) 2.2 tcllib "Word Interpreter"

+

Name

+

wip - Word Interpreter

+
+ + +

Description

+

This package provides a micro interpreter for lists of words. Domain +specific languages based on this will have a bit of a Forth feel, with +the input stream segmented into words and any other structuring left +to whatever the language desired. Note that we have here in essence +only the core dispatch loop, and no actual commands whatsoever, making +this definitely only a Forth feel and not an actual Forth.

+

The idea is derived from Colin McCormack's treeql processor, +modified to require less boiler plate within the command +implementations, at the expense of, likely, execution speed. In +addition the interface between processor core and commands is more +complex too.

+
+

GENERAL BEHAVIOUR

+

Word interpreters have a mappping from the names of the language +commands they shall recognize to the methods in the engine to invoke +for them, and possibly fixed arguments for these methods. This mapping +is largely static, however it is possible to change it during the +execution of a word list (= program).

+

At the time a language command is defined the word interpreter will +use snit's introspection capabilities to determine the +number of arguments expected by the method of the egnine, and together +with the number of fixed arguments supplied in the method prefix of +the mapping it then knows how many arguments the language command is +expecting. This is the command's arity. Variable-argument +methods (i.e. with the last argument named args) are not +allowed and will cause the word interpreter to throw an error at +definition time.

+

Note that while I said snit's abilities the engine object +can be written in any way, as long as it understands the method +info args, which takes a method name and returns the list +of arguments for that method.

+

When executing a list of words (aka program) the first word is always +taken as the name of a language command, and the next words as its +arguments, per the arity of the command. Command and argument +words are removed from the list and then associated method of the +engine is executed with the argument words. The process then repeats +using the then-first word of the list.

+

Note that the methods implementing the language commands may have full +access to the list of words and are allowed to manipulate as they see +fit.

+
    +

  1. This means, for example, that while we cannot specify +variable-argument methods directly they can consume words after their +fixed arguments before returning to the execution loop. This may be +under the control of their fixed arguments.

    2. +

  2. Another possibility is the use of method run_next and its +variants to execute commands coming after the current command, +changing the order of execution.

    3. +

  3. Execution can be further changed by use of the program accessor +methods which allow a command implementation to modify the remaining +list of words (insert, replace, prepend, append words) without +executing them immediately.

    4. +

  4. At last the basic run methods save and restore an existing +list of words when used, enabling recursive use from within command +implementations.

    5. +
+
+

CLASS API

+

The main command of the package is:

+
+
::wip wipName engine arg...
+

The command creates a new word interpreter object with an associated +global Tcl command whose name is wipName. If however the string +%AUTO% was used as object name the package will generate its +own unique name for the object.

+

The engine is the object the word interpreter will dispatch all +recognized commands to, and the arguments are a word list which +defines an initial mapping from language words to engine methods.

+

The recognized language of this word list is

+
+
def name
+

Defines name as command of the language, to be mapped to a +method of the engine having the same name.

+
def name method_prefix
+

Defines name as command of the language, to be mapped to the +method of the engine named in the method_prefix.

+
+

The returned command may be used to invoke various operations on the +object. It has the following general form:

+
+
wipName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+
+

The package additionally exports the command:

+
+
wip::dsl ?suffix?
+

This command is for use within snit types which wish to use one or +more wip interpreters as a component. Use within the type definition +installs most of the boilerplate needed to setup and use a word +interpreter.

+

It installs a component named wip, and a method +wip_setup for initializing it. This method has to be called +from within the constructor of the type using the word interpreter. +If further installs a series of procedures which make the object API +of the word interpreter directly available to the type's methods, +without having to specify the component.

+

Note that this does and cannot install the language to +interpret, i.e. the mapping from words to engine methods.

+

It is possible to instantiate multiple word interpreter components +within a type by using different suffices as arguments to the command. +In that case the name of the component changes to +'wip_$suffix', the setup command becomes +'wip_$suffix_setup' and all the procedures also get the suffix +'_$suffix'.

+
+
+

OBJECT API

+

The following commands are possible for word interpreter objects:

+
+
wipName def name ?method_prefix?
+

Defines a language command name and maps it to the method named +in the engine's method_prefix. If the method_prefix name +is not specified it is simply the name of the language command.

+
wipName defl names
+

Defines a series of language commands, specified through the list of +names, all of which are mapped to engine methods of the same +name.

+
wipName defd dict
+

Defines a series of language commands, specified through the +dictionary dict of names and method prefixes.

+
wipName deflva name...
+

As method defl, however the list of names is specified +through multiple arguments.

+
wipName defdva (name method_prefix)...
+

As method defd, however the dictionary of names and method +prefixes is specified through multiple arguments.

+
wipName undefl names
+

Removes the named series of language commands from the mapping.

+
wipName undefva name...
+

As method undefl, however the list of names is specified +through multiple arguments.

+
wipName unknown cmdprefix
+

Sets the handler for unknown words to cmdprefix. This command +prefix takes one argument, the current word, and either throws some +error, or returns the result of executing the word, as defined by the +handler. The default handler simply throws an error.

+
wipName runl wordlist
+

Treats the list of words in wordlist as a program and executes +the contained command one by one. The result of the command executed +last is returned as the result of this command.

+

The wordlist is stored in the object for access by the other +run-methods, and the general program accessor methods (see +below). A previously stored wordlist is saved during the execution of +this method and restored before it returns. This enables the recursive +execution of word lists within word lists.

+
wipName run word...
+

As method runl, however the list of words to execute is +specified through multiple arguments.

+
wipName run_next
+

Low-level method. Determines the next word in the list of words, and +its arguments, and then executes it. The result of the executed word +is the result of this method.

+

Exposed for use within command implementations. +The methods run and runl use it to execute words +until their word list is exhausted.

+
wipName run_next_while acceptable
+

Low-level method. Invokes the method run_next as long as the +next word is in the set of acceptable words, and the program is +not empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_until rejected
+

Low-level method. Invokes the method run_next until the next +word is in the set of rejected words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_if acceptable
+

Low-level method. Invokes the method run_next if the next +word is in the set of acceptable words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_ifnot rejected
+

Low-level method. Invokes the method run_next if the next +word is not in the set of rejected words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName next
+

Returns the next word in the programm. The word is also removed.

+
wipName peek
+

Returns the next word in the programm without removing it

+
wipName peekall
+

Returns the remaining programm in toto.

+
wipName insertl at wordlist
+

Basic programm accessor method. Inserts the specified wordlist +into the program, just before the word at position at. Positions +are counted from zero.

+
wipName replacel wordlist
+

Basic programm accessor method. Replaces the whole stored program with +the specified wordlist.

+
wipName pushl wordlist
+

Program accessor method. The specified wordlist is added to the +front of the remaining program. Equivalent to

+
$wip insertl 0 $wordlist
+
+
wipName addl wordlist
+

Program accessor method. The specified wordlist is appended at +the end of the remaining program. Equivalent to

+
$wip insertl end $wordlist
+
+
wipName insert at word...
+

Like method insertl, except the words are specified through +multiple arguments.

+
wipName replace word...
+

Like method setl, except the words are specified through +multiple arguments.

+
wipName push word...
+

Like method pushl, except the words are specified through +multiple arguments.

+
wipName add word...
+

Like method addl, except the words are specified through +multiple arguments.

+
+
+

EXAMPLES

+

No examples yet.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category wip of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/yaml/huddle.html Index: embedded/www/tcllib/files/modules/yaml/huddle.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/yaml/huddle.html @@ -0,0 +1,600 @@ + + +huddle - HUDDLE + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

huddle(n) 0.1.5 tcllib "HUDDLE"

+

Name

+

huddle - Create and manipulate huddle object

+
+ + +

Description

+

Huddle provides a generic Tcl-based serialization/intermediary format. +Currently, each node is wrapped in a tag with simple type information.

+

When converting huddle-notation to other serialization formats like +JSON or YAML this type information is used to select the proper notation. +And when going from JSON/YAML/... to huddle their notation can be used +to select the proper huddle type.

+

In that manner huddle can serve as a common intermediary format.

+
+huddle-format: >
+  {HUDDLE {huddle-node}}
+huddle-node: >
+  {tag content}
+each content of tag means:
+  s: (content is a) string
+  L: list, each sub node is a huddle-node
+  D: dict, each sub node is a huddle-node
+confirmed:
+  - JSON
+  - YAML(generally, but cannot discribe YAML-tags)
+limitation:
+  - cannot discribe aliases from a node to other node.
+
+

The huddle package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
huddle create key value ?key value ...?
+

Create a huddle object as a dict. It can contain other huddle objects.

+
huddle list ?value value ...?
+

Create a huddle object as a list. It can contain other huddle objects.

+
huddle 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.

+
+
+% huddle type {HUDDLE {s str}}
+string
+% huddle type {HUDDLE {L {{s a} {s b} {s c}}}}
+list
+% huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc
+string
+
+
+
huddle strip object
+

Stripped all tags. Converted to normal Tcl's list/dict.

+
huddle jsondump object ?offset? ?newline? ?begin_offset?
+

dump a json-stream from the huddle-object.

+
+
offset ""
+

begin offset as spaces " ".

+
+
# normal output has some indents. some strings are escaped.
+% huddle jsondump {HUDDLE {L {{L {{s i} {s baa} {s \\k} {L {{s 1.0} {s true} {s /g} {s h}}} {L {{s g}}}}} {s t}}}}
+[
+  [
+    "i",
+    "baa",
+    "\\k",
+    [
+      1.0,
+      true,
+      "\/g",
+      "h"
+    ],
+    ["g"]
+  ],
+  "t"
+]
+# stripped output
+% huddle jsondump {HUDDLE {D {dd {D {bb {D {a {s baa} c {s {d
+a}}}} cc {D {g {s h}}}}} ee {D {i {s j} k {s 1} j {s { m\a}}}}}}} "" ""
+{"dd": {"bb": {"a": "baa","c": "d\na"},"cc": {"g": "h"}},"ee": {"i": "j","k": 1,"j": " m\\a"}}
+
+
+
huddle compile spec data
+

construct a huddle object from plain old tcl values. +spec is defined as follows:

+
+
string
+

data is simply a string

+
list
+

data is a tcl list of strings

+
dict
+

data is a tcl dict of strings

+
list list
+

data is a tcl list of lists

+
list dict
+

data is a tcl list of dicts

+
dict xx list
+

data is a tcl dict where the value of key xx is a tcl list

+
dict * list
+

data is a tcl dict of lists +data is plain old tcl values

+
+
% huddle compile {dict * list} {a {1 2 3} b {4 5}}
+HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}}
+% huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}}
+HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}}
+
+
+
huddle isHuddle object
+

if object is a huddle, returns 1. the other, returns 0.

+
huddle checkHuddle object
+

if object is not a huddle, rises an error.

+
huddle to_node object ?tag?
+

for type-callbacks.

+

if object is a huddle, returns root-node. the other, returns [list s $object].

+
+% huddle to_node str
+s str
+% huddle to_node str !!str
+!!str str
+% huddle to_node {HUDDLE {s str}}
+s str
+% huddle to_node {HUDDLE {l {a b c}}}
+l {a b c}
+
+
+
huddle wrap tag src
+

for type-callbacks.

+

Create a huddle object from src with specified tag.

+
+% huddle wrap "" str
+HUDDLE str
+% huddle wrap s str
+HUDDLE {s str}
+
+
+
huddle call tag command args
+

for type-callbacks.

+

devolving command to default tag-callback

+
huddle addType callback
+

add a user-specified-type/tag to the huddle library. +To see "Additional Type".

+
+
callback
+

callback function name for additional type.

+
+
+
+

TYPE CALLBACK

+

The definition of callback for user-type.

+
+
callback command ?args?
+
+
command
+

huddle subcomand which is needed to reply by the callback.

+
args
+

arguments of subcommand. The number of list of arguments is different for each subcommand.

+
+
+

The callback procedure shuould reply the following subcommands.

+
+
setting
+

only returns a fixed dict of the type infomation for setting the user-tag.

+
+
type typename
+

typename of the type

+
method {method1 method2 method3 ...}
+

method list as huddle subcommand. Then, you can call [huddle method1 ...]

+
tag {tag1 child/parent tag2 child/parent ...}
+

tag list for huddle-node as a dict. if the type has child-nodes, use "parent", otherwise use "child".

+
+
get_sub src key
+

returns a sub node specified by key.

+
+
src
+

a node content in huddle object.

+
+
strip src
+

returns stripped node contents. if the type has child nodes, every node must be stripped.

+
set src key value
+

sets a sub-node from the tagged-content, and returns self.

+
remove src key value
+

removes a sub-node from the tagged-content, and returns self.

+
+

strip must be defined at all types. +get_sub must be defined at container types. +set/remove shuould be defined, if you call them.

+
+# callback sample for my-dict
+proc my_dict_setting {command args} {
+    switch -- $command {
+        setting { ; # type definition
+            return {
+                type dict
+                method {create keys}
+                tag {d child D parent}
+                constructor create
+                str s
+            }
+            # type:   the type-name
+            # method: add methods to huddle's subcommand.
+            #          "get_sub/strip/set/remove/equal/append" called by huddle module.
+            #          "strip" must be defined at all types.
+            #          "get_sub" must be defined at container types.
+            #          "set/remove/equal/append" shuould be defined, if you call them.
+            # tag:    tag definition("child/parent" word is maybe obsoleted)
+        }
+        get_sub { ; # get a sub-node specified by "key" from the tagged-content
+            foreach {src key} $args break
+            return [dict get $src $key]
+        }
+        strip { ; # strip from the tagged-content
+            foreach {src nop} $args break
+            foreach {key val} $src {
+                lappend result $key [huddle strip $val]
+            }
+            return $result
+        }
+        set { ; # set a sub-node from the tagged-content
+            foreach {src key value} $args break
+            dict set src $key $value
+            return $src
+        }
+        remove { ; # remove a sub-node from the tagged-content
+            foreach {src key value} $args break
+            return [dict remove $src $key]
+        }
+        equal { ; # check equal for each node
+            foreach {src1 src2} $args break
+            if {[llength $src1] != [llength $src2]} {return 0}
+            foreach {key1 val1} $src1 {
+                if {![dict exists $src2 $key1]} {return 0}
+                if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0}
+            }
+            return 1
+        }
+        append { ; # append nodes
+            foreach {str src list} $args break
+            if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}}
+            set resultL $src
+            foreach {key value} $list {
+                if {$str ne ""} {
+                    lappend resultL $key [huddle to_node $value $str]
+                } else {
+                    lappend resultL $key $value
+                }
+            }
+            return [eval dict create $resultL]
+        }
+        create { ; # $args: all arguments after "huddle create"
+            if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}}
+            set resultL {}
+            foreach {key value} $args {
+                lappend resultL $key [huddle to_node $value]
+            }
+            return [huddle wrap D $resultL]
+        }
+        keys {
+            foreach {src nop} $args break
+            return [dict keys [lindex [lindex $src 1] 1]]
+        }
+        default {
+            error "$command is not callback for dict"
+        }
+    }
+}
+
+
+# inheritance sample from default dict-callback
+proc ::yaml::_huddle_mapping {command args} {
+    switch -- $command {
+        setting { ; # type definition
+            return {
+                type dict
+                method {mapping}
+                tag {!!map parent}
+                constructor mapping
+                str !!str
+            }
+        }
+        mapping { ; # $args: all arguments after "huddle mapping"
+            if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}}
+            set resultL {}
+            foreach {key value} $args {
+                lappend resultL $key [huddle to_node $value !!str]
+            }
+            return [huddle wrap !!map $resultL]
+        }
+        default { ; # devolving to default dict-callback
+            return [huddle call D $command $args]
+        }
+    }
+}
+
+
+

How to add type

+

You can add huddle-node types e.g. ::struct::tree. +To do so, first, define a callback-procedure for additional tagged-type. +The proc get argments as command and ?args?. It has some switch-sections.

+

And, addType subcommand will called.

+
+huddle addType my_dict_setting
+
+
+

WORKING SAMPLE

+
+# create as a dict
+% set bb [huddle create a b c d]
+HUDDLE {D {a {s b} c {s d}}}
+# create as a list
+% set cc [huddle list e f g h]
+HUDDLE {L {{s e} {s f} {s g} {s h}}}
+% set bbcc [huddle create bb $bb cc $cc]
+HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}}
+% set folding [huddle list $bbcc p [huddle list q r] s]
+HUDDLE {L {{D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}
+# normal Tcl's notation
+% huddle strip $folding
+{bb {a b c d} cc {e f g h}} p {q r} s
+# get a sub node
+% huddle get $folding 0 bb
+HUDDLE {D {a {s b} c {s d}}}
+% huddle gets $folding 0 bb
+a b c d
+# overwrite a node
+% huddle set folding 0 bb c kkk
+HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}
+# remove a node
+% huddle remove $folding 2 1
+HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q}}} {s s}}}
+% huddle strip $folding
+{bb {a b c kkk} cc {e f g h}} p {q r} s
+# dump as a JSON stream
+% huddle jsondump $folding
+[
+  {
+    "bb": {
+      "a": "b",
+      "c": "kkk"
+    },
+    "cc": [
+      "e",
+      "f",
+      "g",
+      "h"
+    ]
+  },
+  "p",
+  [
+    "q",
+    "r"
+  ],
+  "s"
+]
+
+
+

LIMITATIONS

+

now printing.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category huddle of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/yaml/yaml.html Index: embedded/www/tcllib/files/modules/yaml/yaml.html ================================================================== --- /dev/null +++ embedded/www/tcllib/files/modules/yaml/yaml.html @@ -0,0 +1,283 @@ + + +yaml - YAML processing + + + + + +
+
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Home +]
+

yaml(n) 0.3.6 tcllib "YAML processing"

+

Name

+

yaml - YAML Format Encoder/Decoder

+
+ + +

Description

+

The yaml package provides a simple Tcl-only library for parsing the +YAML http://www.yaml.org/ data exchange format as specified in +http://www.yaml.org/spec/1.1/.

+

The yaml package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
::yaml::yaml2dict ?options? txt
+
+
::yaml::yaml2huddle ?options? txt
+

Parse yaml formatted text txt into a Tcl dict/huddle and return the value.

+
+
-file
+

txt is a filename of YAML-stream.

+
-stream
+

txt is just a YAML-stream.

+
-types list
+

The list is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...)

+
 -types {timestamp integer null true false}
+

In this case, if a string matched "timestamp", converted to the TCL internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183)

+
-m:true param
+

The param is two elements of list for the value of true, and considered strings.

+
 -m:true {1 {true on + yes y}}
+

In this case, the string "yes" found in YAML Stream, automatically converted 1.

+
-m:false param
+

The param is two elements of list for the value of false, and considered strings.

+
 -m:false {0 {false off - no n}}
+
+
-m:null param
+

The param is two elements of list for the value of null, and considered strings.

+
 -m:null {"" {null nil "" ~}}
+
+
-validate
+

Experiment,old: Output stream contains YAML's-tag, each node.

+
% puts [::yaml::load -validate {[aaa, bbb]}]
+=>
+!!seq {{!!str aaa} {!!str bbb}}
+
+
+
+
::yaml::setOption ?options?
+

Change implicit options for the library. +Now, the params are the same as ::yaml::yaml2dict. +Arguments of::yaml::yaml2dict is more priority than this setting.

+
::yaml::dict2yaml dict ?indent? ?wordwrap?
+
+
::yaml::list2yaml list ?indent? ?wordwrap?
+
+
::yaml::huddle2yaml huddle ?indent? ?wordwrap?
+

Convert a dict/list/huddle object into YAML stream.

+
+
indent
+

spaces indent of each block node. +currently default is 2.

+
wordwrap
+

word wrap for YAML stream. +currently default is 40.

+
+
+
+

EXAMPLES

+

An example of a yaml stream converted to Tcl. A yaml stream is returned as a +single item with multiple elements.

+
{
+--- !<tag:clarkevans.com,2002:invoice>
+invoice: 34843
+date   : 2001-01-23
+bill-to: &id001
+    given  : Chris
+    family : Dumars
+    address:
+        lines: |
+            458 Walkman Dr.
+            Suite #292
+        city    : Royal Oak
+        state   : MI
+        postal  : 48046
+ship-to: *id001
+product:
+    - sku         : BL394D
+      quantity    : 4
+      description : Basketball
+      price       : 450.00
+    - sku         : BL4438H
+      quantity    : 1
+      description : Super Hoop
+      price       : 2392.00
+tax  : 251.42
+total: 4443.52
+comments:
+    Late afternoon is best.
+    Backup contact is Nancy
+    Billsmer @ 338-4338.
+}
+=>
+invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr.
+Suite #292
+} city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr.
+Suite #292
+} city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.}
+

An example of a yaml object converted to Tcl. A yaml object is returned as a +multi-element list (a dict).

+
{
+---
+- [name        , hr, avg  ]
+- [Mark McGwire, 65, 0.278]
+- [Sammy Sosa  , 63, 0.288]
+- 
+  Mark McGwire: {hr: 65, avg: 0.278}
+  Sammy Sosa: { hr: 63, avg: 0.288}
+}
+=>
+{name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}}
+
+
+

LIMITATIONS

+

tag parser not implemented. currentry, tags are merely ignored.

+

Only Anchor => Aliases ordering. back alias-referring is not supported.

+

Too many braces, or too few braces.

+

Not enough character set of line feeds. Please use only "\n" as line breaks.

+
+

BUGS, IDEAS, FEEDBACK

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category yaml of the +Tcllib SF Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/toc.html Index: embedded/www/tcllib/toc.html ================================================================== --- /dev/null +++ embedded/www/tcllib/toc.html @@ -0,0 +1,1521 @@ + + Table Of Contents + + + + +
[ + Keyword Index +| Home +]
+

Table Of Contents

+

tcllib

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aesImplementation of the AES block cipher
ascii85ascii85-encode/decode binary data
asnASN.1 BER encoder/decoder
autoproxyAutomatic HTTP proxy usage and authentication
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
base64base64-encode/decode binary data
beeBitTorrent Serialization Format Encoder/Decoder
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
bibtexParse bibtex files
blowfishImplementation of the Blowfish block cipher
cache::asyncAsynchronous in-memory cache
cksumCalculate a cksum(1) compatible checksum
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
cmdlineProcedures to process command lines and options.
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
controlProcedures for control flow structures.
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
counterProcedures for counters and histograms
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
csvProcedures to handle CSV data.
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
desImplementation of the DES and triple-DES ciphers
dnsTcl Domain Name Service Client
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools2idx_introductionDocTools - Keyword indices
doctools2toc_introductionDocTools - Tables of Contents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::idxdocidx - Processing indices
doctools::idxHolding keyword indices
doctools::idx::exportExporting keyword indices
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::importImporting keyword indices
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcatMessage catalog management for the various document parsers
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
doctools::tocdoctoc - Processing tables of contents
doctools::tocHolding tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::importImporting keyword indices
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
dtpliteLightweight DocTools Markup Processor
exifTcl EXIF extracts and parses EXIF fields from digital images
fileutilProcedures implementing some file utilities
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::mimetypeProcedures implementing mime-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
ftpdTcl FTP server implementation
generatorProcedures for creating and using generators.
gpxExtracts waypoints, tracks and routes from GPX files
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
hookHooks
htmlProcedures to generate HTML structures
htmlparseProcedures to parse HTML strings
huddleCreate and manipulate huddle object
identIdent protocol client
imap4imap client-side tcl implementation of imap protocol
inifileParsing of Windows INI files
interpInterp creation and aliasing
ircCreate IRC connection and interface.
javascriptProcedures to generate HTML and Java Script structures.
jpegJPEG querying and manipulation of meta data
jsonJSON parser
json::writeJSON generation
lambdaUtility commands for anonymous procedures
ldapLDAP client
ldapxLDAP extended object interface
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
mapprojMap projection routines
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::calculus::symdiffSymbolic differentiation for Tcl
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
md4MD4 Message-Digest Algorithm
md5MD5 Message-Digest Algorithm
md5cryptMD5-based password encryption
mimeManipulation of MIME body parts
mpexpandMarkup processor
multiplexerOne-to-many communication with sockets.
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
namespacexNamespace utility commands
ncgiProcedures to manipulate CGI values.
nmeaProcess NMEA data
nnsName service facility, Commandline Client Application
nns_introName service facility, introduction
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
nntpTcl client for the NNTP protocol
ntp_timeTcl Time Service Client
oo::utilUtility commands for TclOO
otpOne-Time Passwords
pageParser Generator
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
picoircSmall and simple embeddable IRC client.
pkiImplementation of the public key cipher
pluginmgrManage a plugin
pngPNG querying and manipulation of meta data
pop3Tcl client for POP3 email protocol
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
profilerTcl source code profiler
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parser_apiParser API
rc4Implementation of the RC4 stream cipher
rcsRCS low level utilities
reportCreate and manipulate report objects
restdefine REST web APIs and call them inline or asychronously
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
S3Amazon S3 Web Service Interface
SASLImplementation of SASL mechanisms for Tcl
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
smtpClient-side tcl implementation of the smtp protocol
smtpdTcl SMTP server implementation
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
soundexSoundex
stooopObject oriented extension.
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
sumCalculate a sum(1) compatible checksum
tarTar file creation, extraction & manipulation
tcl::chan::catConcatenation channel
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::randseedUtilities for random channels
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::coreBasic reflected/virtual channel transform support
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
tcldocstripTcl-based Docstrip Processor
tcllib_ipIPv4 and IPv6 address manipulation
tclrep/machineparametersCompute double precision machine parameters.
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
tepam::procedureTEPAM procedure, reference manual
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::expanderProcedures to process templates and expand text.
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
tieArray persistence, standard data sources
tieArray persistence
tiffTIFF reading, writing, and querying and manipulation of meta data
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
treeqlQuery tree objects
trytry - Trap and process errors and exceptions
ueventUser events
uevent::onidleRequest merging and deferal to idle time
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
unitsunit conversion
uriURI utilities
uri_urnURI utilities, URN scheme
uuencodeUU-encode/decode binary data
uuidUUID generation and comparison
wipWord Interpreter
xsxpeXtremely Simple Xml Parser
yamlYAML Format Encoder/Decoder
yencodeY-encode/decode binary data
+
ADDED embedded/www/toc.html Index: embedded/www/toc.html ================================================================== --- /dev/null +++ embedded/www/toc.html @@ -0,0 +1,3526 @@ + + Table Of Contents + + + + +
[ + Keyword Index +| Home +]
+

Table Of Contents

+

+
By Categories
+
Argument entry form, mega widget
+ + + + + +
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
+
Benchmark tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
CGI programming
+ + + + + + + + + + + + + + + + + + + + + +
htmlProcedures to generate HTML structures
javascriptProcedures to generate HTML and Java Script structures.
jsonJSON parser
json::writeJSON generation
ncgiProcedures to manipulate CGI values.
+
Channels
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::randseedUtilities for random channels
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::coreBasic reflected/virtual channel transform support
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
Coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
Data structures
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
counterProcedures for counters and histograms
reportCreate and manipulate report objects
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
treeqlQuery tree objects
+
Documentation tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools2idx_introductionDocTools - Keyword indices
doctools2toc_introductionDocTools - Tables of Contents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::idxHolding keyword indices
doctools::idxdocidx - Processing indices
doctools::idx::exportExporting keyword indices
doctools::idx::importImporting keyword indices
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcatMessage catalog management for the various document parsers
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
doctools::tocHolding tables of contents
doctools::tocdoctoc - Processing tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::importImporting keyword indices
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
dtpliteLightweight DocTools Markup Processor
mpexpandMarkup processor
tcldocstripTcl-based Docstrip Processor
textutil::expanderProcedures to process templates and expand text.
+
File formats
+ + + + + + + + + + + + + + + + + + + + + + + + + +
exifTcl EXIF extracts and parses EXIF fields from digital images
gpxExtracts waypoints, tracks and routes from GPX files
jpegJPEG querying and manipulation of meta data
pngPNG querying and manipulation of meta data
tarTar file creation, extraction & manipulation
tiffTIFF reading, writing, and querying and manipulation of meta data
+
Grammars and finite automata
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
Hashes, checksums, and encryption
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aesImplementation of the AES block cipher
blowfishImplementation of the Blowfish block cipher
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
desImplementation of the DES and triple-DES ciphers
md4MD4 Message-Digest Algorithm
md5MD5 Message-Digest Algorithm
md5cryptMD5-based password encryption
otpOne-Time Passwords
pkiImplementation of the public key cipher
rc4Implementation of the RC4 stream cipher
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
soundexSoundex
sumCalculate a sum(1) compatible checksum
uuidUUID generation and comparison
+
Mathematics
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
Networking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
asnASN.1 BER encoder/decoder
autoproxyAutomatic HTTP proxy usage and authentication
beeBitTorrent Serialization Format Encoder/Decoder
dnsTcl Domain Name Service Client
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
ftpdTcl FTP server implementation
identIdent protocol client
ircCreate IRC connection and interface.
ldapLDAP client
ldapxLDAP extended object interface
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nmeaProcess NMEA data
nnsName service facility, Commandline Client Application
nns_introName service facility, introduction
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
nntpTcl client for the NNTP protocol
ntp_timeTcl Time Service Client
picoircSmall and simple embeddable IRC client.
pop3Tcl client for POP3 email protocol
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
S3Amazon S3 Web Service Interface
SASLImplementation of SASL mechanisms for Tcl
smtpClient-side tcl implementation of the smtp protocol
smtpdTcl SMTP server implementation
tcllib_ipIPv4 and IPv6 address manipulation
uriURI utilities
uri_urnURI utilities, URN scheme
+
Page Parser Generator
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pageParser Generator
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
Parsing and Grammars
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parser_apiParser API
+
Procedures, arguments, parameters, options
+ + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::procedureTEPAM procedure, reference manual
+
Programming tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cmdlineProcedures to process command lines and options.
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
controlProcedures for control flow structures.
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
fileutilProcedures implementing some file utilities
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::mimetypeProcedures implementing mime-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
hookHooks
interpInterp creation and aliasing
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
multiplexerOne-to-many communication with sockets.
pluginmgrManage a plugin
profilerTcl source code profiler
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
stooopObject oriented extension.
tieArray persistence
tieArray persistence, standard data sources
ueventUser events
wipWord Interpreter
+
Terminal control
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
Text formatter plugin
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
+
Text processing
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
base64base64-encode/decode binary data
bibtexParse bibtex files
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
csvProcedures to handle CSV data.
htmlparseProcedures to parse HTML strings
inifileParsing of Windows INI files
mimeManipulation of MIME body parts
rcsRCS low level utilities
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
uuencodeUU-encode/decode binary data
xsxpeXtremely Simple Xml Parser
yencodeY-encode/decode binary data
+
Transfer module
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
Unfiled
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cache::asyncAsynchronous in-memory cache
generatorProcedures for creating and using generators.
huddleCreate and manipulate huddle object
imap4imap client-side tcl implementation of imap protocol
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
mapprojMap projection routines
math::calculus::symdiffSymbolic differentiation for Tcl
namespacexNamespace utility commands
restdefine REST web APIs and call them inline or asychronously
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
tclrep/machineparametersCompute double precision machine parameters.
uevent::onidleRequest merging and deferal to idle time
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
unitsunit conversion
yamlYAML Format Encoder/Decoder
+
Utility
+ + + + + + + + + + + + + +
lambdaUtility commands for anonymous procedures
oo::utilUtility commands for TclOO
trytry - Trap and process errors and exceptions
+
Validation, Type checking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
By Type
+
Applications
+ + + + + + + + + + + + + + + + + + + + + + + + + +
dtpliteLightweight DocTools Markup Processor
nnsName service facility, Commandline Client Application
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
pageParser Generator
tcldocstripTcl-based Docstrip Processor
+
Modules
+
aes
+ + + + + +
aesImplementation of the AES block cipher
+
amazon-s3
+ + + + + + + + + +
S3Amazon S3 Web Service Interface
xsxpeXtremely Simple Xml Parser
+
asn
+ + + + + +
asnASN.1 BER encoder/decoder
+
base32
+ + + + + + + + + + + + + +
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
+
base64
+ + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base64base64-encode/decode binary data
uuencodeUU-encode/decode binary data
yencodeY-encode/decode binary data
+
bee
+ + + + + +
beeBitTorrent Serialization Format Encoder/Decoder
+
bench
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
bibtex
+ + + + + +
bibtexParse bibtex files
+
blowfish
+ + + + + +
blowfishImplementation of the Blowfish block cipher
+
cache
+ + + + + +
cache::asyncAsynchronous in-memory cache
+
clock
+ + + + + + + + + +
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
+
cmdline
+ + + + + +
cmdlineProcedures to process command lines and options.
+
comm
+ + + + + + + + + +
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
+
control
+ + + + + +
controlProcedures for control flow structures.
+
coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
counter
+ + + + + +
counterProcedures for counters and histograms
+
crc
+ + + + + + + + + + + + + + + + + +
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
sumCalculate a sum(1) compatible checksum
+
csv
+ + + + + +
csvProcedures to handle CSV data.
+
des
+ + + + + +
desImplementation of the DES and triple-DES ciphers
+
dns
+ + + + + + + + + +
dnsTcl Domain Name Service Client
tcllib_ipIPv4 and IPv6 address manipulation
+
docstrip
+ + + + + + + + + +
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
+
doctools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::idxdocidx - Processing indices
doctools::tocdoctoc - Processing tables of contents
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
mpexpandMarkup processor
+
doctools2base
+ + + + + + + + + + + + + + + + + +
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::msgcatMessage catalog management for the various document parsers
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
+
doctools2idx
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2idx_introductionDocTools - Keyword indices
doctools::idxHolding keyword indices
doctools::idx::exportExporting keyword indices
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::importImporting keyword indices
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
+
doctools2toc
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2toc_introductionDocTools - Tables of Contents
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::tocHolding tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::importImporting keyword indices
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
+
exif
+ + + + + +
exifTcl EXIF extracts and parses EXIF fields from digital images
+
fileutil
+ + + + + + + + + + + + + + + + + +
fileutilProcedures implementing some file utilities
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
+
ftp
+ + + + + + + + + +
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
+
ftpd
+ + + + + +
ftpdTcl FTP server implementation
+
fumagic
+ + + + + + + + + + + + + + + + + + + + + +
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::mimetypeProcedures implementing mime-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
+
generator
+ + + + + +
generatorProcedures for creating and using generators.
+
gpx
+ + + + + +
gpxExtracts waypoints, tracks and routes from GPX files
+
grammar_aycock
+ + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
+
grammar_fa
+ + + + + + + + + + + + + + + + + +
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
+
grammar_me
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
+
grammar_peg
+ + + + + + + + + +
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
hook
+ + + + + +
hookHooks
+
html
+ + + + + +
htmlProcedures to generate HTML structures
+
htmlparse
+ + + + + +
htmlparseProcedures to parse HTML strings
+
http
+ + + + + +
autoproxyAutomatic HTTP proxy usage and authentication
+
ident
+ + + + + +
identIdent protocol client
+
imap4
+ + + + + +
imap4imap client-side tcl implementation of imap protocol
+
inifile
+ + + + + +
inifileParsing of Windows INI files
+
interp
+ + + + + + + + + + + + + +
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
interpInterp creation and aliasing
+
irc
+ + + + + + + + + +
ircCreate IRC connection and interface.
picoircSmall and simple embeddable IRC client.
+
javascript
+ + + + + +
javascriptProcedures to generate HTML and Java Script structures.
+
jpeg
+ + + + + +
jpegJPEG querying and manipulation of meta data
+
json
+ + + + + + + + + +
jsonJSON parser
json::writeJSON generation
+
lambda
+ + + + + +
lambdaUtility commands for anonymous procedures
+
ldap
+ + + + + + + + + +
ldapLDAP client
ldapxLDAP extended object interface
+
log
+ + + + + + + + + + + + + + + + + +
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
+
map
+ + + + + + + + + + + + + + + + + +
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
+
mapproj
+ + + + + +
mapprojMap projection routines
+
math
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::calculus::symdiffSymbolic differentiation for Tcl
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
tclrep/machineparametersCompute double precision machine parameters.
+
md4
+ + + + + +
md4MD4 Message-Digest Algorithm
+
md5
+ + + + + +
md5MD5 Message-Digest Algorithm
+
md5crypt
+ + + + + +
md5cryptMD5-based password encryption
+
mime
+ + + + + + + + + +
mimeManipulation of MIME body parts
smtpClient-side tcl implementation of the smtp protocol
+
multiplexer
+ + + + + +
multiplexerOne-to-many communication with sockets.
+
namespacex
+ + + + + +
namespacexNamespace utility commands
+
ncgi
+ + + + + +
ncgiProcedures to manipulate CGI values.
+
nmea
+ + + + + +
nmeaProcess NMEA data
+
nns
+ + + + + + + + + + + + + + + + + + + + + + + + + +
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nns_introName service facility, introduction
+
nntp
+ + + + + +
nntpTcl client for the NNTP protocol
+
ntp
+ + + + + +
ntp_timeTcl Time Service Client
+
ooutil
+ + + + + +
oo::utilUtility commands for TclOO
+
otp
+ + + + + +
otpOne-Time Passwords
+
page
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
pki
+ + + + + +
pkiImplementation of the public key cipher
+
pluginmgr
+ + + + + +
pluginmgrManage a plugin
+
png
+ + + + + +
pngPNG querying and manipulation of meta data
+
pop3
+ + + + + +
pop3Tcl client for POP3 email protocol
+
pop3d
+ + + + + + + + + + + + + +
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
+
profiler
+ + + + + +
profilerTcl source code profiler
+
pt
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parser_apiParser API
+
rc4
+ + + + + +
rc4Implementation of the RC4 stream cipher
+
rcs
+ + + + + +
rcsRCS low level utilities
+
report
+ + + + + +
reportCreate and manipulate report objects
+
rest
+ + + + + +
restdefine REST web APIs and call them inline or asychronously
+
ripemd
+ + + + + + + + + +
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
+
sasl
+ + + + + +
SASLImplementation of SASL mechanisms for Tcl
+
sha1
+ + + + + + + + + +
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
+
simulation
+ + + + + + + + + + + + + +
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
smtpd
+ + + + + +
smtpdTcl SMTP server implementation
+
snit
+ + + + + + + + + +
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
+
soundex
+ + + + + +
soundexSoundex
+
stooop
+ + + + + +
stooopObject oriented extension.
+
stringprep
+ + + + + + + + + + + + + + + + + +
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
+
struct
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
+
tar
+ + + + + +
tarTar file creation, extraction & manipulation
+
tepam
+ + + + + + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
tepam::procedureTEPAM procedure, reference manual
+
term
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
textutil
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::expanderProcedures to process templates and expand text.
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
+
tie
+ + + + + + + + + +
tieArray persistence
tieArray persistence, standard data sources
+
tiff
+ + + + + +
tiffTIFF reading, writing, and querying and manipulation of meta data
+
transfer
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
treeql
+ + + + + +
treeqlQuery tree objects
+
try
+ + + + + +
trytry - Trap and process errors and exceptions
+
uev
+ + + + + + + + + +
ueventUser events
uevent::onidleRequest merging and deferal to idle time
+
units
+ + + + + +
unitsunit conversion
+
uri
+ + + + + + + + + +
uriURI utilities
uri_urnURI utilities, URN scheme
+
uuid
+ + + + + +
uuidUUID generation and comparison
+
valtype
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
virtchannel_base
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::randseedUtilities for random channels
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
+
virtchannel_core
+ + + + + + + + + + + + + +
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::transform::coreBasic reflected/virtual channel transform support
+
virtchannel_transform
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
wip
+ + + + + +
wipWord Interpreter
+
yaml
+ + + + + + + + + +
huddleCreate and manipulate huddle object
yamlYAML Format Encoder/Decoder
+
Index: modules/amazon-s3/ChangeLog ================================================================== --- modules/amazon-s3/ChangeLog +++ modules/amazon-s3/ChangeLog @@ -1,5 +1,10 @@ +2013-02-08 Andreas Kupries + + * xsxp.man: Fixed moddesc/titledesc confusion. + * S3.man: Ditto. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/amazon-s3/S3.man ================================================================== --- modules/amazon-s3/S3.man +++ modules/amazon-s3/S3.man @@ -1,7 +1,8 @@ [manpage_begin S3 n 1.0.0] -[moddesc {Amazon S3 Web Service Interface}] +[moddesc {Amazon S3 Web Service Utilities}] +[titledesc {Amazon S3 Web Service Interface}] [category Networking] [copyright {Copyright 2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms.}] [require Tcl 8.5] [require sha1 1.0] [require md5 2.0] Index: modules/amazon-s3/xsxp.man ================================================================== --- modules/amazon-s3/xsxp.man +++ modules/amazon-s3/xsxp.man @@ -1,7 +1,8 @@ [manpage_begin xsxp n 1.0] -[moddesc {eXtremely Simple Xml Parser}] +[moddesc {Amazon S3 Web Service Utilities}] +[titledesc {eXtremely Simple Xml Parser}] [copyright {Copyright 2006 Darren New. All Rights Reserved.}] [category {Text processing}] [require Tcl 8.4] [require xml] [keywords xml dom parser] Index: modules/coroutine/ChangeLog ================================================================== --- modules/coroutine/ChangeLog +++ modules/coroutine/ChangeLog @@ -1,5 +1,10 @@ +2013-02-08 Andreas Kupries + + * coroutine.man: Fixed missing short package title. + * coro_auto.man: Ditto. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/coroutine/coro_auto.man ================================================================== --- modules/coroutine/coro_auto.man +++ modules/coroutine/coro_auto.man @@ -1,11 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin coroutine::auto n 1] [copyright {2010-2011 Andreas Kupries }] [moddesc {Coroutine utilities}] [category Coroutine] -[titledesc {}] +[titledesc {Automatic event and IO coroutine awareness}] [require Tcl 8.6] [require coroutine::auto 1.1] [require coroutine 1.1] [description] [keywords coroutine global exit after vwait update gets read] Index: modules/coroutine/coroutine.man ================================================================== --- modules/coroutine/coroutine.man +++ modules/coroutine/coroutine.man @@ -1,11 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin coroutine n 1] [copyright {2010-2011 Andreas Kupries }] [moddesc {Coroutine utilities}] [category Coroutine] -[titledesc {}] +[titledesc {Coroutine based event and IO handling}] [require Tcl 8.6] [require coroutine 1.1] [description] [keywords coroutine channel events threads {green threads}] [keywords global exit after vwait update gets read] Index: modules/gpx/ChangeLog ================================================================== --- modules/gpx/ChangeLog +++ modules/gpx/ChangeLog @@ -1,5 +1,9 @@ +2013-02-08 Andreas Kupries + + * gpx.man: Fixed categorization. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/gpx/gpx.man ================================================================== --- modules/gpx/gpx.man +++ modules/gpx/gpx.man @@ -1,11 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin gpx n 0.9] [copyright {2010, Keith Vetter }] [moddesc {GPS eXchange Format (GPX)}] [titledesc {Extracts waypoints, tracks and routes from GPX files}] -[category {gpx, gpx}] +[category {File formats}] [require Tcl 8.5] [require gpx [opt 0.9]] [description] [para] Index: modules/grammar_aycock/ChangeLog ================================================================== --- modules/grammar_aycock/ChangeLog +++ modules/grammar_aycock/ChangeLog @@ -1,5 +1,9 @@ +2013-02-08 Andreas Kupries + + * aycock.man: Fixed missing short package title. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/grammar_aycock/aycock.man ================================================================== --- modules/grammar_aycock/aycock.man +++ modules/grammar_aycock/aycock.man @@ -1,11 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] -[manpage_begin aycock n 1.0] +[manpage_begin grammar::aycock n 1.0] [copyright "2006 by Kevin B. Kenny Redistribution permitted under the terms of the Open\ Publication License "] [moddesc "Aycock-Horspool-Earley parser generator for Tcl"] +[titledesc "Aycock-Horspool-Earley parser generator for Tcl"] [category "Grammars and finite automata"] [require Tcl 8.5] [require grammar::aycock [opt 1.0]] [description] [keywords grammar parser aycock earley horspool] Index: modules/math/ChangeLog ================================================================== --- modules/math/ChangeLog +++ modules/math/ChangeLog @@ -1,5 +1,10 @@ +2013-02-08 Andreas Kupries + + * decimal.man: Fixed leading namespace qualifier in label. + * symdiff.man: Fixed missing short package title. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/math/decimal.man ================================================================== --- modules/math/decimal.man +++ modules/math/decimal.man @@ -1,7 +1,7 @@ [comment {-*- tcl -*- doctools manpage}] -[manpage_begin ::math::decimal n 1.0.2] +[manpage_begin math::decimal n 1.0.2] [copyright {2011 Mark Alston }] [moddesc {Tcl Decimal Arithmetic Library}] [titledesc {General decimal arithmetic}] [category Mathematics] [require Tcl [opt 8.5]] Index: modules/math/symdiff.man ================================================================== --- modules/math/symdiff.man +++ modules/math/symdiff.man @@ -1,10 +1,11 @@ -[manpage_begin symdiff n 1.0] +[manpage_begin math::calculus::symdiff n 1.0] [copyright "2010 by Kevin B. Kenny Redistribution permitted under the terms of the Open\ Publication License "] [moddesc "Symbolic differentiation for Tcl"] +[titledesc "Symbolic differentiation for Tcl"] [require Tcl 8.5] [require grammar::aycock 1.0] [require math::calculus::symdiff 1.0] [description] [para] Index: modules/rc4/ChangeLog ================================================================== --- modules/rc4/ChangeLog +++ modules/rc4/ChangeLog @@ -1,5 +1,9 @@ +2013-02-08 Andreas Kupries + + * rc4.man: fixed bogus trailing comma in list of keywords. + 2013-02-01 Andreas Kupries * * Released and tagged Tcllib 1.15 ======================== * Index: modules/rc4/rc4.man ================================================================== --- modules/rc4/rc4.man +++ modules/rc4/rc4.man @@ -118,7 +118,7 @@ Please also report any ideas for enhancements you may have for either package and/or documentation. -[keywords rc4 arcfour, {stream cipher} security encryption {data integrity}] +[keywords rc4 arcfour {stream cipher} security encryption {data integrity}] [manpage_end] Index: support/devel/sak/doc/doc.tcl ================================================================== --- support/devel/sak/doc/doc.tcl +++ support/devel/sak/doc/doc.tcl @@ -76,12 +76,13 @@ auto::saveTableOfContents title name cat apps mods return } proc ::sak::doc::imake {modules} { + global base # The argument (= set of modules) is irrelevant to this command. - auto::saveManpages [auto::findManpages] + auto::saveManpages [auto::findManpages $base] return } proc ::sak::doc::ishow {modules} { if {[catch { Index: support/devel/sak/doc/doc_auto.tcl ================================================================== --- support/devel/sak/doc/doc_auto.tcl +++ support/devel/sak/doc/doc_auto.tcl @@ -58,10 +58,11 @@ ::doctools::new dt -format list set data {} puts Scanning... foreach page $manpages { puts ...$page + dt configure -ibase $page lappend data $page [lindex [dt format [fileutil::cat $page]] 1] } dt destroy return $data Index: support/devel/sak/doc/kwic.txt ================================================================== --- support/devel/sak/doc/kwic.txt +++ support/devel/sak/doc/kwic.txt @@ -2,10 +2,19 @@ [key .ddt] [manpage modules/docstrip/docstrip_util.man docstrip_util] [key .dtx] [manpage modules/docstrip/docstrip.man docstrip] [manpage apps/tcldocstrip.man tcldocstrip] +[key /dev/null] +[manpage modules/virtchannel_base/null.man tcl::chan::null] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[key /dev/random] +[manpage modules/virtchannel_base/random.man tcl::chan::random] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] +[key /dev/zero] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[manpage modules/virtchannel_base/zero.man tcl::chan::zero] [key 3DES] [manpage modules/des/des.man des] [key {abstract syntax tree}] [manpage modules/grammar_me/me_util.man grammar::me::util] [manpage modules/grammar_me/me_ast.man grammar::me_ast] @@ -16,26 +25,41 @@ [key active] [manpage modules/transfer/connect.man transfer::connect] [key adaptors] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] +[key {adjacency list}] +[manpage modules/struct/graphops.man struct::graph::op] [key {adjacency matrix}] [manpage modules/struct/graphops.man struct::graph::op] [key adjacent] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] [key adjusting] [manpage modules/textutil/adjust.man textutil::adjust] +[key adler32] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] [key aes] [manpage modules/aes/aes.man aes] +[key after] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key alias] [manpage modules/interp/tcllib_interp.man interp] [key amazon] [manpage modules/amazon-s3/S3.man S3] +[key ambiguous] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[key {American Express}] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[key AMEX] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] [key angle] -[manpage modules/math/geometry.man math::geometry] -[manpage modules/units/units.man units] +[manpage modules/math/math_geometry.man math::geometry] +[manpage modules/units/units.man units] +[key {anonymous procedure}] +[manpage modules/lambda/lambda.man lambda] [key ansi] [manpage modules/term/ansi_cattr.man term::ansi::code::attr] [manpage modules/term/ansi_cctrl.man term::ansi::code::ctrl] [manpage modules/term/ansi_cmacros.man term::ansi::code::macros] [manpage modules/term/ansi_ctrlu.man term::ansi::ctrl::unix] @@ -44,28 +68,41 @@ [manpage modules/log/loggerUtils.man logger::utils] [key application] [manpage apps/nns.man nns] [manpage apps/nnsd.man nnsd] [manpage apps/nnslog.man nnslog] +[key {approximation algorithm}] +[manpage modules/struct/graphops.man struct::graph::op] [key arc] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] -[key arcfour,] +[key arcfour] [manpage modules/rc4/rc4.man rc4] [key archive] [manpage modules/tar/tar.man tar] +[key {argument integrity}] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_procedure.man tepam::procedure] [key {argument processing}] [manpage modules/cmdline/cmdline.man cmdline] +[key {argument validation}] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_procedure.man tepam::procedure] +[key arguments] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_procedure.man tepam::procedure] [key argv] [manpage modules/cmdline/cmdline.man cmdline] [key argv0] [manpage modules/cmdline/cmdline.man cmdline] [key array] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] [key {articulation point}] [manpage modules/struct/graphops.man struct::graph::op] +[key ascii85] +[manpage modules/base64/ascii85.man ascii85] [key asn] [manpage modules/asn/asn.man asn] [key assembler] [manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] [key assert] @@ -77,10 +114,14 @@ [key asynchronous] [manpage modules/cache/async.man cache::async] [key {attribute control}] [manpage modules/term/ansi_cattr.man term::ansi::code::attr] [manpage modules/term/ansi_cctrl.man term::ansi::code::ctrl] +[key {augmenting network}] +[manpage modules/struct/graphops.man struct::graph::op] +[key {augmenting path}] +[manpage modules/struct/graphops.man struct::graph::op] [key authentication] [manpage modules/http/autoproxy.man autoproxy] [manpage modules/sasl/sasl.man SASL] [key automatic] [manpage modules/nns/nns_auto.man nameserv::auto] @@ -87,16 +128,25 @@ [key automaton] [manpage modules/grammar_fa/fa.man grammar::fa] [manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] [manpage modules/grammar_fa/dexec.man grammar::fa::dexec] [manpage modules/grammar_fa/faop.man grammar::fa::op] +[key aycock] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[key bank] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/iban.man valtype::iban] [key base32] [manpage modules/base32/base32.man base32] [manpage modules/base32/base32core.man base32::core] [manpage modules/base32/base32hex.man base32::hex] [key base64] -[manpage modules/base64/base64.man base64] +[manpage modules/base64/base64.man base64] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] [key bee] [manpage modules/bee/bee.man bee] [key {bench language}] [manpage modules/bench/bench_intro.man bench_intro] [manpage modules/bench/bench_lang_intro.man bench_lang_intro] @@ -111,10 +161,12 @@ [manpage modules/bench/bench_lang_spec.man bench_lang_spec] [key ber] [manpage modules/asn/asn.man asn] [key {Bessel functions}] [manpage modules/math/special.man math::special] +[key bfs] +[manpage modules/struct/graphops.man struct::graph::op] [key bibliography] [manpage modules/bibtex/bibtex.man bibtex] [key bibtex] [manpage modules/bibtex/bibtex.man bibtex] [key bignums] @@ -131,37 +183,70 @@ [manpage modules/textutil/repeat.man textutil::repeat] [key {block cipher}] [manpage modules/aes/aes.man aes] [manpage modules/blowfish/blowfish.man blowfish] [manpage modules/des/des.man des] +[key {blocking flow}] +[manpage modules/struct/graphops.man struct::graph::op] [key blowfish] [manpage modules/blowfish/blowfish.man blowfish] +[key {Book Number}] +[manpage modules/valtype/isbn.man valtype::isbn] [key breadth-first] [manpage modules/struct/struct_tree.man struct::tree] [key bridge] [manpage modules/struct/graphops.man struct::graph::op] [key BWidget] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] +[key C] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] [key C++] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [manpage modules/stooop/stooop.man stooop] [key cache] [manpage modules/cache/async.man cache::async] [manpage modules/map/map_slippy_cache.man map::slippy::cache] +[key {caesar cipher}] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] [key calculus] [manpage modules/math/calculus.man math::calculus] [key callback] [manpage modules/cache/async.man cache::async] +[manpage modules/hook/hook.man hook] +[manpage modules/lambda/lambda.man lambda] +[manpage modules/ooutil/ooutil.man oo::util] [manpage modules/uev/uevent_onidle.man uevent::onidle] +[key callbacks] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] [key capitalize] [manpage modules/textutil/textutil_string.man textutil::string] +[key {card for credit}] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] [key cardinality] [manpage modules/struct/struct_set.man struct::set] [key cat] [manpage modules/fileutil/fileutil.man fileutil] +[key {catalog package}] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] +[key catalogue] +[manpage modules/docstrip/docstrip_util.man docstrip_util] +[key cell-phone] +[manpage modules/valtype/imei.man valtype::imei] [key cer] [manpage modules/asn/asn.man asn] [key CFG] [manpage modules/grammar_me/me_intro.man grammar::me_intro] [key CFL] @@ -168,22 +253,37 @@ [manpage modules/grammar_me/me_intro.man grammar::me_intro] [key CGI] [manpage modules/ncgi/ncgi.man ncgi] [key cgraph] [manpage modules/struct/graph.man struct::graph] -[manpage modules/struct/graph1.man {struct::graph v1}] +[manpage modules/struct/graph1.man struct::graph_v1] [key changelog] [manpage modules/doctools/changelog.man doctools::changelog] [manpage modules/doctools/cvs.man doctools::cvs] [key channel] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [manpage modules/transfer/connect.man transfer::connect] [manpage modules/transfer/copyops.man transfer::copy] [manpage modules/transfer/tqueue.man transfer::copy::queue] [manpage modules/transfer/ddest.man transfer::data::destination] [manpage modules/transfer/dsource.man transfer::data::source] [manpage modules/transfer/receiver.man transfer::receiver] [manpage modules/transfer/transmitter.man transfer::transmitter] +[key {channel transformation}] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key {character input}] [manpage modules/term/receive.man term::receive] [manpage modules/term/term_bind.man term::receive::bind] [key {character output}] [manpage modules/term/ansi_send.man term::ansi::send] @@ -195,26 +295,52 @@ [key checkbox] [manpage modules/html/html.man html] [manpage modules/javascript/javascript.man javascript] [key checkbutton] [manpage modules/html/html.man html] +[key Checking] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] [key checksum] -[manpage modules/crc/cksum.man cksum] -[manpage modules/crc/crc16.man crc16] -[manpage modules/crc/crc32.man crc32] -[manpage modules/crc/sum.man sum] +[manpage modules/crc/cksum.man cksum] +[manpage modules/crc/crc16.man crc16] +[manpage modules/crc/crc32.man crc32] +[manpage modules/crc/sum.man sum] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] [key chop] [manpage modules/textutil/textutil_string.man textutil::string] +[key cipher] +[manpage modules/pki/pki.man pki] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] [key cksum] [manpage modules/crc/cksum.man cksum] [manpage modules/crc/crc16.man crc16] [manpage modules/crc/crc32.man crc32] [manpage modules/crc/sum.man sum] [key class] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [manpage modules/stooop/stooop.man stooop] +[key {class methods}] +[manpage modules/ooutil/ooutil.man oo::util] +[key {class variables}] +[manpage modules/ooutil/ooutil.man oo::util] +[key cleanup] +[manpage modules/try/tcllib_try.man try] [key client] [manpage modules/nns/nns_client.man nameserv] [manpage modules/nns/nns_auto.man nameserv::auto] [manpage modules/nns/nns_common.man nameserv::common] [manpage apps/nns.man nns] @@ -233,12 +359,17 @@ [manpage modules/comm/comm.man comm] [manpage modules/comm/comm_wire.man comm_wire] [manpage modules/interp/deleg_method.man deleg_method] [manpage modules/interp/deleg_proc.man deleg_proc] [manpage modules/nns/nns_protocol.man nameserv::protocol] +[key command] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] [key {command line processing}] [manpage modules/cmdline/cmdline.man cmdline] +[key {command prefix}] +[manpage modules/lambda/lambda.man lambda] +[manpage modules/ooutil/ooutil.man oo::util] [key comment] [manpage modules/jpeg/jpeg.man jpeg] [manpage modules/png/png.man png] [key common] [manpage modules/struct/struct_list.man struct::list] @@ -247,28 +378,80 @@ [key communication] [manpage modules/comm/comm.man comm] [manpage modules/comm/comm_wire.man comm_wire] [key comparison] [manpage modules/struct/struct_list.man struct::list] +[key {complete graph}] +[manpage modules/struct/graphops.man struct::graph::op] [key {complex numbers}] [manpage modules/math/qcomplex.man math::complexnumbers] [manpage modules/math/fourier.man math::fourier] +[key compression] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key computations] [manpage modules/math/bigfloat.man math::bigfloat] +[key {concatenation channel}] +[manpage modules/virtchannel_base/cat.man tcl::chan::cat] +[manpage modules/virtchannel_base/facade.man tcl::chan::facade] [key {connected component}] [manpage modules/struct/graphops.man struct::graph::op] +[key {connected fifos}] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] [key connection] [manpage modules/transfer/connect.man transfer::connect] [key constants] [manpage modules/math/constants.man math::constants] [manpage modules/units/units.man units] +[key CONTAINER] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[key contents] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] [key {context-free grammar}] [manpage modules/grammar_me/me_intro.man grammar::me_intro] [key {context-free languages}] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key control] [manpage modules/control/control.man control] [manpage modules/term/term.man term] [manpage modules/term/ansi_code.man term::ansi::code] [manpage modules/term/ansi_cattr.man term::ansi::code::attr] @@ -279,19 +462,37 @@ [manpage modules/term/imenu.man term::interact::menu] [manpage modules/term/ipager.man term::interact::pager] [manpage modules/term/receive.man term::receive] [manpage modules/term/term_bind.man term::receive::bind] [manpage modules/term/term_send.man term::send] +[key {control structure}] +[manpage modules/generator/generator.man generator] [key conversion] -[manpage modules/doctools/doctools.man doctools] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] -[manpage apps/dtplite.man dtplite] -[manpage modules/math/roman.man math::roman] -[manpage modules/doctools/mpexpand.man mpexpand] -[manpage apps/tcldocstrip.man tcldocstrip] -[manpage modules/units/units.man units] +[manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage apps/dtplite.man dtplite] +[manpage modules/math/roman.man math::roman] +[manpage modules/doctools/mpexpand.man mpexpand] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage apps/tcldocstrip.man tcldocstrip] +[manpage modules/units/units.man units] [key cooked] [manpage modules/term/ansi_ctrlu.man term::ansi::ctrl::unix] [key cookie] [manpage modules/ncgi/ncgi.man ncgi] [key copy] @@ -301,32 +502,51 @@ [manpage modules/transfer/tqueue.man transfer::copy::queue] [manpage modules/transfer/ddest.man transfer::data::destination] [manpage modules/transfer/dsource.man transfer::data::source] [manpage modules/transfer/receiver.man transfer::receiver] [manpage modules/transfer/transmitter.man transfer::transmitter] +[key coroutine] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] +[manpage modules/generator/generator.man generator] [key Cost] [manpage modules/treeql/treeql.man treeql] +[key counter] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] [key counting] [manpage modules/counter/counter.man counter] +[key CPARAM] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] [key crc] [manpage modules/crc/cksum.man cksum] [manpage modules/crc/crc16.man crc16] [manpage modules/crc/crc32.man crc32] [manpage modules/crc/sum.man sum] [key crc16] [manpage modules/crc/crc16.man crc16] [key crc32] -[manpage modules/crc/cksum.man cksum] -[manpage modules/crc/crc16.man crc16] -[manpage modules/crc/crc32.man crc32] -[manpage modules/crc/sum.man sum] +[manpage modules/crc/cksum.man cksum] +[manpage modules/crc/crc16.man crc16] +[manpage modules/crc/crc32.man crc32] +[manpage modules/crc/sum.man sum] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[key {credit card}] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] [key cryptography] [manpage modules/blowfish/blowfish.man blowfish] +[key CSS] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] [key csv] [manpage modules/bench/bench_read.man bench::in] [manpage modules/bench/bench_wcsv.man bench::out::csv] [manpage modules/csv/csv.man csv] +[key currying] +[manpage modules/lambda/lambda.man lambda] +[manpage modules/ooutil/ooutil.man oo::util] [key {cut edge}] [manpage modules/struct/graphops.man struct::graph::op] [key {cut vertex}] [manpage modules/struct/graphops.man struct::graph::op] [key CVS] @@ -343,20 +563,24 @@ [key {data analysis}] [manpage modules/math/statistics.man math::statistics] [key {data destination}] [manpage modules/transfer/ddest.man transfer::data::destination] [manpage modules/transfer/receiver.man transfer::receiver] +[key {data entry form}] +[manpage modules/tepam/tepam_argument_dialogbox.man tepam::argument_dialogbox] [key {data exchange}] -[manpage modules/yaml/huddle.man huddle] -[manpage modules/json/json.man json] -[manpage modules/yaml/yaml.man yaml] +[manpage modules/yaml/huddle.man huddle] +[manpage modules/json/json.man json] +[manpage modules/json/json_write.man json::write] +[manpage modules/yaml/yaml.man yaml] [key {data integrity}] [manpage modules/aes/aes.man aes] [manpage modules/crc/cksum.man cksum] [manpage modules/crc/crc16.man crc16] [manpage modules/crc/crc32.man crc32] [manpage modules/des/des.man des] +[manpage modules/pki/pki.man pki] [manpage modules/rc4/rc4.man rc4] [manpage modules/crc/sum.man sum] [key {data source}] [manpage modules/transfer/dsource.man transfer::data::source] [manpage modules/transfer/transmitter.man transfer::transmitter] @@ -365,18 +589,30 @@ [key database] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] [key dataflow] [manpage modules/page/page_util_flow.man page_util_flow] +[key DE] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[key decimal] +[manpage modules/math/decimal.man math::decimal] [key declare] [manpage modules/term/ansi_code.man term::ansi::code] +[key decompression] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] +[key decryption] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] [key deferal] [manpage modules/uev/uevent_onidle.man uevent::onidle] [key define] [manpage modules/term/ansi_code.man term::ansi::code] [key degree] [manpage modules/struct/graph.man struct::graph] +[manpage modules/struct/graphops.man struct::graph::op] +[key {degree constrained spanning tree}] [manpage modules/struct/graphops.man struct::graph::op] [key degrees] [manpage modules/math/constants.man math::constants] [key delegation] [manpage modules/interp/deleg_method.man deleg_method] @@ -385,14 +621,22 @@ [manpage modules/struct/struct_tree.man struct::tree] [key der] [manpage modules/asn/asn.man asn] [key DES] [manpage modules/des/des.man des] +[key deserialization] +[manpage modules/doctools2idx/import_docidx.man doctools::idx::import::docidx] +[manpage modules/doctools2idx/import_json.man doctools::idx::import::json] +[manpage modules/doctools2idx/structure.man doctools::idx::structure] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] +[manpage modules/doctools2toc/structure.man doctools::toc::structure] [key diameter] [manpage modules/struct/graphops.man struct::graph::op] [key diff] -[manpage modules/struct/struct_list.man struct::list] +[manpage modules/docstrip/docstrip_util.man docstrip_util] +[manpage modules/struct/struct_list.man struct::list] [key {diff -n format}] [manpage modules/rcs/rcs.man rcs] [key difference] [manpage modules/struct/struct_set.man struct::set] [key differential] @@ -404,27 +648,40 @@ [key {directory access}] [manpage modules/ldap/ldap.man ldap] [manpage modules/ldap/ldapx.man ldapx] [key {directory traversal}] [manpage modules/fileutil/traverse.man fileutil_traverse] +[key Discover] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] [key {discrete items}] [manpage modules/struct/pool.man struct::pool] [key {disjoint set}] [manpage modules/struct/disjointset.man struct::disjointset] [key dispatcher] [manpage modules/term/term_bind.man term::receive::bind] [key distance] -[manpage modules/math/geometry.man math::geometry] -[manpage modules/struct/graphops.man struct::graph::op] -[manpage modules/units/units.man units] +[manpage modules/math/math_geometry.man math::geometry] +[manpage modules/struct/graphops.man struct::graph::op] +[manpage modules/units/units.man units] [key DNS] [manpage modules/dns/tcllib_dns.man dns] [key do] [manpage modules/control/control.man control] [key docidx] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage apps/dtplite.man dtplite] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_docidx.man doctools::idx::export::docidx] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2idx/import_docidx.man doctools::idx::import::docidx] +[manpage modules/doctools2idx/parse.man doctools::idx::parse] +[manpage modules/doctools2idx/structure.man doctools::idx::structure] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage apps/dtplite.man dtplite] [key {docidx commands}] [manpage modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/docidx_lang_intro.man docidx_lang_intro] [manpage modules/doctools/docidx_lang_syntax.man docidx_lang_syntax] @@ -436,21 +693,33 @@ [key {docidx markup}] [manpage modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/docidx_lang_intro.man docidx_lang_intro] [manpage modules/doctools/docidx_lang_syntax.man docidx_lang_syntax] +[manpage modules/doctools2idx/container.man doctools::idx] [key {docidx syntax}] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/docidx_lang_intro.man docidx_lang_intro] [manpage modules/doctools/docidx_lang_syntax.man docidx_lang_syntax] [key docstrip] [manpage modules/docstrip/docstrip.man docstrip] [manpage modules/docstrip/docstrip_util.man docstrip_util] [manpage apps/tcldocstrip.man tcldocstrip] [key doctoc] -[manpage modules/doctools/doctoc.man doctools::toc] -[manpage apps/dtplite.man dtplite] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/parse.man doctools::toc::parse] +[manpage modules/doctools2toc/structure.man doctools::toc::structure] +[manpage apps/dtplite.man dtplite] [key {doctoc commands}] [manpage modules/doctools/doctoc_lang_cmdref.man doctoc_lang_cmdref] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctoc_lang_intro.man doctoc_lang_intro] [manpage modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax] @@ -462,18 +731,51 @@ [key {doctoc markup}] [manpage modules/doctools/doctoc_lang_cmdref.man doctoc_lang_cmdref] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctoc_lang_intro.man doctoc_lang_intro] [manpage modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax] +[manpage modules/doctools2toc/container.man doctools::toc] [key {doctoc syntax}] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctoc_lang_intro.man doctoc_lang_intro] [manpage modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax] [key doctools] -[manpage modules/docstrip/docstrip_util.man docstrip_util] -[manpage modules/doctools/changelog.man doctools::changelog] -[manpage apps/dtplite.man dtplite] +[manpage modules/docstrip/docstrip_util.man docstrip_util] +[manpage modules/doctools/changelog.man doctools::changelog] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] +[manpage modules/doctools2idx/export_docidx.man doctools::idx::export::docidx] +[manpage modules/doctools2idx/export_html.man doctools::idx::export::html] +[manpage modules/doctools2idx/export_json.man doctools::idx::export::json] +[manpage modules/doctools2idx/export_nroff.man doctools::idx::export::nroff] +[manpage modules/doctools2idx/export_text.man doctools::idx::export::text] +[manpage modules/doctools2idx/export_wiki.man doctools::idx::export::wiki] +[manpage modules/doctools2idx/import_docidx.man doctools::idx::import::docidx] +[manpage modules/doctools2idx/import_json.man doctools::idx::import::json] +[manpage modules/doctools2idx/parse.man doctools::idx::parse] +[manpage modules/doctools2idx/structure.man doctools::idx::structure] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] +[manpage modules/doctools2toc/parse.man doctools::toc::parse] +[manpage modules/doctools2toc/structure.man doctools::toc::structure] +[manpage apps/dtplite.man dtplite] [key {doctools commands}] [manpage modules/doctools/doctools_lang_cmdref.man doctools_lang_cmdref] [manpage modules/doctools/doctools_lang_faq.man doctools_lang_faq] [manpage modules/doctools/doctools_lang_intro.man doctools_lang_intro] [manpage modules/doctools/doctools_lang_syntax.man doctools_lang_syntax] @@ -495,84 +797,228 @@ [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [key documentation] [manpage modules/docstrip/docstrip.man docstrip] [manpage modules/docstrip/docstrip_util.man docstrip_util] [manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/container.man doctools::idx] [manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] [manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] [manpage apps/tcldocstrip.man tcldocstrip] [key DOM] [manpage modules/treeql/treeql.man treeql] [key dom] [manpage modules/amazon-s3/xsxp.man xsxp] [key {domain name service}] [manpage modules/dns/tcllib_dns.man dns] [key e] [manpage modules/math/constants.man math::constants] +[key EAN] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/isbn.man valtype::isbn] +[key EAN13] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/isbn.man valtype::isbn] +[key earley] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[key EBNF] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key eccentricity] [manpage modules/struct/graphops.man struct::graph::op] [key edge] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] [key emacs] [manpage modules/doctools/changelog.man doctools::changelog] [manpage modules/doctools/cvs.man doctools::cvs] [key email] -[manpage modules/mime/mime.man mime] -[manpage modules/pop3/pop3.man pop3] -[manpage modules/mime/smtp.man smtp] +[manpage modules/imap4/imap4.man imap4] +[manpage modules/mime/mime.man mime] +[manpage modules/pop3/pop3.man pop3] +[manpage modules/mime/smtp.man smtp] [key emptiness] [manpage modules/struct/struct_set.man struct::set] [key {empty interpreter}] [manpage modules/interp/tcllib_interp.man interp] +[key EN] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] [key encoding] +[manpage modules/base64/ascii85.man ascii85] [manpage modules/base64/base64.man base64] [manpage modules/base64/uuencode.man uuencode] [manpage modules/base64/yencode.man yencode] [key encryption] -[manpage modules/aes/aes.man aes] -[manpage modules/blowfish/blowfish.man blowfish] -[manpage modules/des/des.man des] -[manpage modules/rc4/rc4.man rc4] +[manpage modules/aes/aes.man aes] +[manpage modules/blowfish/blowfish.man blowfish] +[manpage modules/des/des.man des] +[manpage modules/pki/pki.man pki] +[manpage modules/rc4/rc4.man rc4] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[key {entry mask}] +[manpage modules/tepam/tepam_introduction.man tepam] [key equal] [manpage modules/struct/struct_list.man struct::list] [key equality] [manpage modules/struct/struct_list.man struct::list] [key {equivalence class}] [manpage modules/struct/disjointset.man struct::disjointset] +[key error] +[manpage modules/try/tcllib_try.man try] [key {error function}] [manpage modules/math/special.man math::special] +[key {European Article Number}] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/isbn.man valtype::isbn] [key event] +[manpage modules/hook/hook.man hook] [manpage modules/uev/uevent.man uevent] [manpage modules/uev/uevent_onidle.man uevent::onidle] +[key {event management}] +[manpage modules/virtchannel_core/events.man tcl::chan::events] +[key events] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key examples] [manpage modules/bench/bench_lang_intro.man bench_lang_intro] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctools_lang_faq.man doctools_lang_faq] +[key exception] +[manpage modules/try/tcllib_try.man try] [key {exchange format}] -[manpage modules/yaml/huddle.man huddle] -[manpage modules/json/json.man json] +[manpage modules/yaml/huddle.man huddle] +[manpage modules/json/json.man json] +[manpage modules/json/json_write.man json::write] [key exclusion] [manpage modules/struct/struct_set.man struct::set] [key execution] [manpage modules/grammar_fa/dexec.man grammar::fa::dexec] [key exif] [manpage modules/exif/exif.man exif] [manpage modules/jpeg/jpeg.man jpeg] +[key exit] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] +[key export] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_docidx.man doctools::idx::export::docidx] +[manpage modules/doctools2idx/export_html.man doctools::idx::export::html] +[manpage modules/doctools2idx/export_json.man doctools::idx::export::json] +[manpage modules/doctools2idx/export_nroff.man doctools::idx::export::nroff] +[manpage modules/doctools2idx/export_text.man doctools::idx::export::text] +[manpage modules/doctools2idx/export_wiki.man doctools::idx::export::wiki] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] [key expression] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[key {extended namespace}] +[manpage modules/namespacex/namespacex.man namespacex] [key faq] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctools_lang_faq.man doctools_lang_faq] [key {fetching information}] [manpage modules/uri/uri.man uri] [key FFT] [manpage modules/math/fourier.man math::fourier] +[key fifo] +[manpage modules/virtchannel_base/fifo.man tcl::chan::fifo] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] [key file] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] [manpage modules/uri/uri.man uri] [key {file recognition}] @@ -597,11 +1043,20 @@ [manpage modules/fileutil/multi.man fileutil::multi] [manpage modules/fileutil/multiop.man fileutil::multi::op] [key filesystem] [manpage modules/map/map_slippy_cache.man map::slippy::cache] [key filter] -[manpage modules/struct/struct_list.man struct::list] +[manpage modules/generator/generator.man generator] +[manpage modules/struct/struct_list.man struct::list] +[key final] +[manpage modules/try/tcllib_try.man try] +[key finance] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/iban.man valtype::iban] [key find] [manpage modules/struct/disjointset.man struct::disjointset] [key finite] [manpage modules/struct/pool.man struct::pool] [key {finite automaton}] @@ -612,38 +1067,66 @@ [key {FIPS 180-1}] [manpage modules/sha1/sha1.man sha1] [manpage modules/sha1/sha256.man sha256] [key {first permutation}] [manpage modules/struct/struct_list.man struct::list] +[key Fisher-Yates] +[manpage modules/struct/struct_list.man struct::list] [key flatten] [manpage modules/struct/struct_list.man struct::list] [key floating-point] [manpage modules/math/bigfloat.man math::bigfloat] [manpage modules/math/fuzzy.man math::fuzzy] [key flow] [manpage modules/control/control.man control] +[key {flow network}] +[manpage modules/struct/graphops.man struct::graph::op] [key folding] [manpage modules/struct/struct_list.man struct::list] +[key foldl] +[manpage modules/generator/generator.man generator] +[key foldr] +[manpage modules/generator/generator.man generator] +[key foreach] +[manpage modules/generator/generator.man generator] [key form] [manpage modules/html/html.man html] [manpage modules/ncgi/ncgi.man ncgi] +[key {format conversion}] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] [key formatter] [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [key formatting] -[manpage modules/bench/bench_read.man bench::in] -[manpage modules/bench/bench_wcsv.man bench::out::csv] -[manpage modules/bench/bench_wtext.man bench::out::text] -[manpage modules/textutil/textutil.man textutil] -[manpage modules/textutil/adjust.man textutil::adjust] -[manpage modules/textutil/textutil_string.man textutil::string] -[manpage modules/textutil/tabify.man textutil::tabify] +[manpage modules/bench/bench_read.man bench::in] +[manpage modules/bench/bench_wcsv.man bench::out::csv] +[manpage modules/bench/bench_wtext.man bench::out::text] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/textutil/textutil.man textutil] +[manpage modules/textutil/adjust.man textutil::adjust] +[manpage modules/textutil/textutil_string.man textutil::string] +[manpage modules/textutil/tabify.man textutil::tabify] [key {formatting engine}] [manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [key {Fourier transform}] [manpage modules/math/fourier.man math::fourier] +[key FR] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] [key frame] [manpage modules/term/ansi_cmacros.man term::ansi::code::macros] [key ftp] [manpage modules/ftp/ftp.man ftp] [manpage modules/ftp/ftp_geturl.man ftp::geturl] @@ -657,45 +1140,105 @@ [manpage modules/struct/struct_list.man struct::list] [key {generate event}] [manpage modules/uev/uevent.man uevent] [key {generate permutations}] [manpage modules/struct/struct_list.man struct::list] +[key generation] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[key generator] +[manpage modules/generator/generator.man generator] +[key geocoding] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] [key geodesy] [manpage modules/map/map_slippy.man map::slippy] [manpage modules/mapproj/mapproj.man mapproj] [key geography] [manpage modules/map/map_slippy.man map::slippy] [key {get character}] [manpage modules/term/receive.man term::receive] +[key gets] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] +[key global] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key gopher] [manpage modules/uri/uri.man uri] [key gps] +[manpage modules/gpx/gpx.man gpx] [manpage modules/nmea/nmea.man nmea] +[key gpx] +[manpage modules/gpx/gpx.man gpx] [key grammar] -[manpage modules/grammar_fa/fa.man grammar::fa] -[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] -[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] -[manpage modules/grammar_fa/faop.man grammar::fa::op] -[manpage modules/grammar_me/me_cpu.man grammar::me::cpu] -[manpage modules/grammar_me/me_cpucore.man grammar::me::cpu::core] -[manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] -[manpage modules/grammar_me/me_tcl.man grammar::me::tcl] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_me/me_vm.man grammar::me_vm] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[manpage modules/grammar_fa/fa.man grammar::fa] +[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] +[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] +[manpage modules/grammar_fa/faop.man grammar::fa::op] +[manpage modules/grammar_me/me_cpu.man grammar::me::cpu] +[manpage modules/grammar_me/me_cpucore.man grammar::me::cpu::core] +[manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] +[manpage modules/grammar_me/me_tcl.man grammar::me::tcl] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_me/me_vm.man grammar::me_vm] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key graph] [manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] [manpage modules/struct/graph.man struct::graph] -[manpage modules/struct/graph1.man {struct::graph v1}] [manpage modules/struct/graphops.man struct::graph::op] +[manpage modules/struct/graph1.man struct::graph_v1] [manpage modules/struct/queue.man struct::queue] [manpage modules/struct/stack.man struct::stack] [key {graph walking}] [manpage modules/page/page_util_flow.man page_util_flow] [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] [manpage modules/page/page_util_norm_peg.man page_util_norm_peg] +[key {green threads}] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key grep] [manpage modules/fileutil/fileutil.man fileutil] [key GUID] [manpage modules/uuid/uuid.man uuid] [key hashing] @@ -705,48 +1248,99 @@ [manpage modules/otp/otp.man otp] [manpage modules/ripemd/ripemd128.man ripemd128] [manpage modules/ripemd/ripemd160.man ripemd160] [manpage modules/sha1/sha1.man sha1] [manpage modules/sha1/sha256.man sha256] +[key heuristic] +[manpage modules/struct/graphops.man struct::graph::op] [key hex] [manpage modules/base32/base32hex.man base32::hex] +[key hexadecimal] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] [key histogram] [manpage modules/counter/counter.man counter] +[key hook] +[manpage modules/hook/hook.man hook] +[manpage modules/uev/uevent.man uevent] +[key horspool] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] [key HTML] -[manpage modules/doctools/doctools.man doctools] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] -[manpage apps/dtplite.man dtplite] -[manpage modules/doctools/mpexpand.man mpexpand] +[manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_html.man doctools::idx::export::html] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage apps/dtplite.man dtplite] +[manpage modules/doctools/mpexpand.man mpexpand] [key html] [manpage modules/html/html.man html] [manpage modules/htmlparse/htmlparse.man htmlparse] [manpage modules/javascript/javascript.man javascript] [manpage modules/ncgi/ncgi.man ncgi] [key http] -[manpage modules/http/autoproxy.man autoproxy] -[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] -[manpage modules/uri/uri.man uri] +[manpage modules/http/autoproxy.man autoproxy] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] +[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] +[manpage modules/uri/uri.man uri] [key huddle] [manpage modules/yaml/huddle.man huddle] [manpage modules/yaml/yaml.man yaml] [key {human readable}] [manpage modules/bench/bench_read.man bench::in] [manpage modules/bench/bench_wtext.man bench::out::text] [key hyphenation] [manpage modules/textutil/textutil.man textutil] [manpage modules/textutil/adjust.man textutil::adjust] +[key i18n] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] +[key IBAN] +[manpage modules/valtype/iban.man valtype::iban] [key ident] [manpage modules/ident/ident.man ident] [key identification] [manpage modules/ident/ident.man ident] +[key identity] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] [key idle] [manpage modules/uev/uevent_onidle.man uevent::onidle] [key image] [manpage modules/jpeg/jpeg.man jpeg] [manpage modules/png/png.man png] [manpage modules/tiff/tiff.man tiff] +[key imap] +[manpage modules/imap4/imap4.man imap4] +[key IMEI] +[manpage modules/valtype/imei.man valtype::imei] +[key import] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2idx/import_docidx.man doctools::idx::import::docidx] +[manpage modules/doctools2idx/import_json.man doctools::idx::import::json] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[key {in-memory channel}] +[manpage modules/virtchannel_base/fifo.man tcl::chan::fifo] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] +[manpage modules/virtchannel_base/memchan.man tcl::chan::memchan] +[manpage modules/virtchannel_base/string.man tcl::chan::string] +[manpage modules/virtchannel_base/variable.man tcl::chan::variable] [key in-order] [manpage modules/struct/struct_tree.man struct::tree] [key inclusion] [manpage modules/struct/struct_set.man struct::set] [key {Incr Tcl}] @@ -753,28 +1347,66 @@ [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [key indenting] [manpage modules/textutil/textutil.man textutil] [manpage modules/textutil/adjust.man textutil::adjust] +[key {independent set}] +[manpage modules/struct/graphops.man struct::graph::op] [key index] [manpage modules/doctools/docidx_intro.man docidx_intro] [manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] [manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_docidx.man doctools::idx::export::docidx] +[manpage modules/doctools2idx/export_html.man doctools::idx::export::html] +[manpage modules/doctools2idx/export_json.man doctools::idx::export::json] +[manpage modules/doctools2idx/export_nroff.man doctools::idx::export::nroff] +[manpage modules/doctools2idx/export_text.man doctools::idx::export::text] +[manpage modules/doctools2idx/export_wiki.man doctools::idx::export::wiki] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2idx/import_docidx.man doctools::idx::import::docidx] +[manpage modules/doctools2idx/import_json.man doctools::idx::import::json] [key {index formatter}] [manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] +[key info] +[manpage modules/namespacex/namespacex.man namespacex] [key {inner join}] [manpage modules/struct/struct_list.man struct::list] [key {input mode}] [manpage modules/term/ansi_ctrlu.man term::ansi::ctrl::unix] [key integer] [manpage modules/math/roman.man math::roman] [key integration] [manpage modules/math/calculus.man math::calculus] +[key {inter-thread communication}] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[key {International Article Number}] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/isbn.man valtype::isbn] +[key {International Bank Account Number}] +[manpage modules/valtype/iban.man valtype::iban] +[key {International Mobile Equipment Identity}] +[manpage modules/valtype/imei.man valtype::imei] +[key {International Standard Book Number}] +[manpage modules/valtype/isbn.man valtype::isbn] +[key internationalization] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] [key internet] [manpage modules/asn/asn.man asn] [manpage modules/ftp/ftp.man ftp] [manpage modules/ftp/ftp_geturl.man ftp::geturl] +[manpage modules/imap4/imap4.man imap4] [manpage modules/ldap/ldap.man ldap] [manpage modules/ldap/ldapx.man ldapx] [manpage modules/mime/mime.man mime] [manpage modules/pop3d/pop3d.man pop3d] [manpage modules/pop3d/pop3d_dbox.man pop3d::dbox] @@ -803,40 +1435,93 @@ [key ipv6] [manpage modules/dns/tcllib_ip.man tcllib_ip] [key irc] [manpage modules/irc/irc.man irc] [manpage modules/irc/picoirc.man picoirc] +[key isA] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] +[key ISBN] +[manpage modules/valtype/isbn.man valtype::isbn] [key isthmus] [manpage modules/struct/graphops.man struct::graph::op] +[key iterator] +[manpage modules/generator/generator.man generator] [key javascript] [manpage modules/javascript/javascript.man javascript] [manpage modules/json/json.man json] +[manpage modules/json/json_write.man json::write] [key jfif] [manpage modules/jpeg/jpeg.man jpeg] [key join] [manpage modules/struct/struct_list.man struct::list] [key jpeg] [manpage modules/exif/exif.man exif] [manpage modules/jpeg/jpeg.man jpeg] +[key JSON] +[manpage modules/doctools2idx/export_json.man doctools::idx::export::json] +[manpage modules/doctools2idx/import_json.man doctools::idx::import::json] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] [key json] -[manpage modules/yaml/huddle.man huddle] -[manpage modules/json/json.man json] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/yaml/huddle.man huddle] +[manpage modules/json/json.man json] +[manpage modules/json/json_write.man json::write] [key justification] [manpage modules/textutil/adjust.man textutil::adjust] [key {keyword index}] -[manpage modules/doctools/docidx_intro.man docidx_intro] -[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools/docidx_intro.man docidx_intro] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] [key keywords] [manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] [key knuth] [manpage modules/soundex/soundex.man soundex] +[key l10n] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] +[key lambda] +[manpage modules/lambda/lambda.man lambda] [key LaTeX] [manpage modules/docstrip/docstrip.man docstrip] [manpage apps/tcldocstrip.man tcldocstrip] [key latex] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] [key latitute] [manpage modules/map/map_slippy.man map::slippy] [key ldap] [manpage modules/ldap/ldap.man ldap] [manpage modules/ldap/ldapx.man ldapx] @@ -850,12 +1535,19 @@ [manpage modules/math/linalg.man math::linearalgebra] [key {left outer join}] [manpage modules/struct/struct_list.man struct::list] [key lemon] [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] +[key {level graph}] +[manpage modules/struct/graphops.man struct::graph::op] +[key lexer] +[manpage modules/doctools2idx/parse.man doctools::idx::parse] +[manpage modules/doctools2toc/parse.man doctools::toc::parse] +[key limitsize] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] [key line] -[manpage modules/math/geometry.man math::geometry] +[manpage modules/math/math_geometry.man math::geometry] [key {linear algebra}] [manpage modules/math/linalg.man math::linearalgebra] [key {linear equations}] [manpage modules/math/linalg.man math::linearalgebra] [key {linear program}] @@ -872,17 +1564,68 @@ [key {literate programming}] [manpage modules/docstrip/docstrip.man docstrip] [manpage modules/docstrip/docstrip_util.man docstrip_util] [manpage apps/tcldocstrip.man tcldocstrip] [key LL(k)] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[key {local searching}] +[manpage modules/struct/graphops.man struct::graph::op] +[key localization] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] [key location] -[manpage modules/map/map_slippy.man map::slippy] -[manpage modules/map/map_slippy_cache.man map::slippy::cache] -[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] +[manpage modules/map/map_slippy.man map::slippy] +[manpage modules/map/map_slippy_cache.man map::slippy::cache] +[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] [key log] [manpage modules/doctools/cvs.man doctools::cvs] [manpage modules/log/log.man log] [manpage modules/log/logger.man logger] [key {log level}] @@ -897,31 +1640,48 @@ [key longitude] [manpage modules/map/map_slippy.man map::slippy] [key loop] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] +[key luhn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[key luhn-5] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[key macros] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] [key mail] -[manpage modules/mime/mime.man mime] -[manpage modules/pop3/pop3.man pop3] -[manpage modules/mime/smtp.man smtp] +[manpage modules/imap4/imap4.man imap4] +[manpage modules/mime/mime.man mime] +[manpage modules/pop3/pop3.man pop3] +[manpage modules/mime/smtp.man smtp] [key mailto] [manpage modules/uri/uri.man uri] [key {maker note}] [manpage modules/exif/exif.man exif] +[key man_macros] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] [key manpage] [manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/container.man doctools::idx] [manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] [manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [manpage apps/dtplite.man dtplite] [manpage modules/doctools/mpexpand.man mpexpand] [key map] -[manpage modules/map/map_slippy.man map::slippy] -[manpage modules/map/map_slippy_cache.man map::slippy::cache] -[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] -[manpage modules/mapproj/mapproj.man mapproj] -[manpage modules/struct/struct_list.man struct::list] +[manpage modules/generator/generator.man generator] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] +[manpage modules/map/map_slippy.man map::slippy] +[manpage modules/map/map_slippy_cache.man map::slippy::cache] +[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] +[manpage modules/mapproj/mapproj.man mapproj] +[manpage modules/struct/struct_list.man struct::list] [key markup] [manpage modules/doctools/docidx_intro.man docidx_intro] [manpage modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref] [manpage modules/doctools/docidx_lang_faq.man docidx_lang_faq] [manpage modules/doctools/docidx_lang_intro.man docidx_lang_intro] @@ -932,85 +1692,163 @@ [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctoc_lang_intro.man doctoc_lang_intro] [manpage modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] [manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] [manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] [manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] [manpage modules/doctools/doctools_intro.man doctools_intro] [manpage modules/doctools/doctools_lang_cmdref.man doctools_lang_cmdref] [manpage modules/doctools/doctools_lang_faq.man doctools_lang_faq] [manpage modules/doctools/doctools_lang_intro.man doctools_lang_intro] [manpage modules/doctools/doctools_lang_syntax.man doctools_lang_syntax] [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [manpage apps/dtplite.man dtplite] [manpage modules/doctools/mpexpand.man mpexpand] [manpage apps/tcldocstrip.man tcldocstrip] +[key MasterCard] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] [key matching] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[manpage modules/struct/graphops.man struct::graph::op] [key math] -[manpage modules/math/math.man math] -[manpage modules/math/bigfloat.man math::bigfloat] -[manpage modules/math/bignum.man math::bignum] -[manpage modules/math/calculus.man math::calculus] -[manpage modules/math/qcomplex.man math::complexnumbers] -[manpage modules/math/constants.man math::constants] -[manpage modules/math/fuzzy.man math::fuzzy] -[manpage modules/math/geometry.man math::geometry] -[manpage modules/math/interpolate.man math::interpolate] -[manpage modules/math/linalg.man math::linearalgebra] -[manpage modules/math/optimize.man math::optimize] -[manpage modules/math/polynomials.man math::polynomials] -[manpage modules/math/rational_funcs.man math::rationalfunctions] -[manpage modules/math/special.man math::special] -[manpage modules/simulation/annealing.man simulation::annealing] -[manpage modules/simulation/montecarlo.man simulation::montecarlo] -[manpage modules/simulation/random.man simulation::random] +[manpage modules/math/math.man math] +[manpage modules/math/bigfloat.man math::bigfloat] +[manpage modules/math/bignum.man math::bignum] +[manpage modules/math/calculus.man math::calculus] +[manpage modules/math/qcomplex.man math::complexnumbers] +[manpage modules/math/constants.man math::constants] +[manpage modules/math/decimal.man math::decimal] +[manpage modules/math/fuzzy.man math::fuzzy] +[manpage modules/math/math_geometry.man math::geometry] +[manpage modules/math/interpolate.man math::interpolate] +[manpage modules/math/linalg.man math::linearalgebra] +[manpage modules/math/optimize.man math::optimize] +[manpage modules/math/polynomials.man math::polynomials] +[manpage modules/math/rational_funcs.man math::rationalfunctions] +[manpage modules/math/special.man math::special] +[manpage modules/simulation/annealing.man simulation::annealing] +[manpage modules/simulation/montecarlo.man simulation::montecarlo] +[manpage modules/simulation/simulation_random.man simulation::random] [key mathematics] [manpage modules/math/fourier.man math::fourier] [manpage modules/math/statistics.man math::statistics] [key matrices] [manpage modules/math/linalg.man math::linearalgebra] [key matrix] [manpage modules/csv/csv.man csv] +[manpage modules/math/linalg.man math::linearalgebra] [manpage modules/report/report.man report] [manpage modules/struct/matrix.man struct::matrix] -[manpage modules/struct/matrix1.man {struct::matrix v1}] +[manpage modules/struct/matrix1.man struct::matrix_v1] [manpage modules/struct/queue.man struct::queue] [manpage modules/struct/stack.man struct::stack] +[key {max cut}] +[manpage modules/struct/graphops.man struct::graph::op] [key maximum] [manpage modules/math/optimize.man math::optimize] +[key {maximum flow}] +[manpage modules/struct/graphops.man struct::graph::op] [key md4] [manpage modules/md4/md4.man md4] [manpage modules/ripemd/ripemd128.man ripemd128] [manpage modules/ripemd/ripemd160.man ripemd160] [key md5] [manpage modules/md5/md5.man md5] [manpage modules/md5crypt/md5crypt.man md5crypt] [key md5crypt] [manpage modules/md5crypt/md5crypt.man md5crypt] +[key medicare] +[manpage modules/valtype/usnpi.man valtype::usnpi] [key {mega widget}] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [key membership] [manpage modules/struct/struct_set.man struct::set] [key menu] [manpage modules/term/ansi_cmacros.man term::ansi::code::macros] [manpage modules/term/imenu.man term::interact::menu] [key merge] -[manpage modules/uev/uevent_onidle.man uevent::onidle] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] +[manpage modules/uev/uevent_onidle.man uevent::onidle] [key {merge find}] [manpage modules/struct/disjointset.man struct::disjointset] [key merging] [manpage modules/bench/bench.man bench] [key message] [manpage modules/comm/comm.man comm] [manpage modules/comm/comm_wire.man comm_wire] [manpage modules/log/log.man log] +[key {message catalog}] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] [key {message level}] [manpage modules/log/log.man log] +[key {message package}] +[manpage modules/doctools2base/tcllib_msgcat.man doctools::msgcat] +[manpage modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c] +[manpage modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de] +[manpage modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en] +[manpage modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr] +[manpage modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c] +[manpage modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de] +[manpage modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en] +[manpage modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr] [key message-digest] [manpage modules/md4/md4.man md4] [manpage modules/md5/md5.man md5] [manpage modules/md5crypt/md5crypt.man md5crypt] [manpage modules/otp/otp.man otp] @@ -1022,10 +1860,12 @@ [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] [key method] [manpage modules/interp/deleg_method.man deleg_method] [manpage modules/interp/tcllib_interp.man interp] +[key {method reference}] +[manpage modules/ooutil/ooutil.man oo::util] [key mime] [manpage modules/fumagic/cfront.man fileutil::magic::cfront] [manpage modules/fumagic/cgen.man fileutil::magic::cgen] [manpage modules/fumagic/mimetypes.man fileutil::magic::mimetype] [manpage modules/fumagic/rtcore.man fileutil::magic::rt] @@ -1033,10 +1873,20 @@ [manpage modules/mime/smtp.man smtp] [key {minimal spanning tree}] [manpage modules/struct/graphops.man struct::graph::op] [key minimum] [manpage modules/math/optimize.man math::optimize] +[key {minimum cost flow}] +[manpage modules/struct/graphops.man struct::graph::op] +[key {minimum degree spanning tree}] +[manpage modules/struct/graphops.man struct::graph::op] +[key {minimum diameter spanning tree}] +[manpage modules/struct/graphops.man struct::graph::op] +[key {mobile phone}] +[manpage modules/valtype/imei.man valtype::imei] +[key module] +[manpage modules/docstrip/docstrip_util.man docstrip_util] [key {montecarlo simulation}] [manpage modules/simulation/montecarlo.man simulation::montecarlo] [key move] [manpage modules/fileutil/multi.man fileutil::multi] [manpage modules/fileutil/multiop.man fileutil::multi::op] @@ -1046,10 +1896,12 @@ [key multiplexer] [manpage modules/multiplexer/multiplexer.man multiplexer] [key multiprecision] [manpage modules/math/bigfloat.man math::bigfloat] [manpage modules/math/bignum.man math::bignum] +[key {my method}] +[manpage modules/ooutil/ooutil.man oo::util] [key {name service}] [manpage modules/nns/nns_client.man nameserv] [manpage modules/nns/nns_auto.man nameserv::auto] [manpage modules/nns/nns_common.man nameserv::common] [manpage modules/nns/nns_protocol.man nameserv::protocol] @@ -1056,16 +1908,23 @@ [manpage modules/nns/nns_server.man nameserv::server] [manpage apps/nns.man nns] [manpage modules/nns/nns_intro.man nns_intro] [manpage apps/nnsd.man nnsd] [manpage apps/nnslog.man nnslog] +[key {namespace unknown}] +[manpage modules/namespacex/namespacex.man namespacex] +[key {namespace utilities}] +[manpage modules/namespacex/namespacex.man namespacex] +[key {National Provider Identifier}] +[manpage modules/valtype/usnpi.man valtype::usnpi] [key neighbour] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] [key net] [manpage modules/ftp/ftp.man ftp] [manpage modules/ftp/ftp_geturl.man ftp::geturl] +[manpage modules/imap4/imap4.man imap4] [manpage modules/mime/mime.man mime] [manpage modules/mime/smtp.man smtp] [key network] [manpage modules/pop3d/pop3d.man pop3d] [manpage modules/pop3d/pop3d_dbox.man pop3d::dbox] @@ -1085,42 +1944,67 @@ [manpage modules/control/control.man control] [key node] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] [manpage modules/struct/struct_tree.man struct::tree] +[key nominatim] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] [key normalization] [manpage modules/bench/bench.man bench] [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] [manpage modules/page/page_util_norm_peg.man page_util_norm_peg] [manpage modules/stringprep/unicode.man unicode] +[key NPI] +[manpage modules/valtype/usnpi.man valtype::usnpi] [key nroff] -[manpage modules/doctools/doctools.man doctools] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] -[manpage apps/dtplite.man dtplite] -[manpage modules/doctools/mpexpand.man mpexpand] +[manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_nroff.man doctools::idx::export::nroff] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage apps/dtplite.man dtplite] +[manpage modules/doctools/mpexpand.man mpexpand] [key NTP] [manpage modules/ntp/ntp_time.man ntp_time] +[key null] +[manpage modules/virtchannel_base/null.man tcl::chan::null] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[key {number theory}] +[manpage modules/math/numtheory.man math::numtheory] [key object] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [manpage modules/stooop/stooop.man stooop] [key {object oriented}] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [manpage modules/stooop/stooop.man stooop] +[key observer] +[manpage modules/hook/hook.man hook] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] [key on-idle] [manpage modules/uev/uevent_onidle.man uevent::onidle] +[key {one time pad}] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] [key optimization] [manpage modules/math/optimize.man math::optimize] [manpage modules/simulation/annealing.man simulation::annealing] [key {ordered list}] [manpage modules/struct/prioqueue.man struct::prioqueue] +[key otp] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] [key {outer join}] [manpage modules/struct/struct_list.man struct::list] [key package] [manpage modules/csv/csv.man csv] +[key {package indexing}] +[manpage modules/docstrip/docstrip_util.man docstrip_util] [key page] [manpage modules/page/page_intro.man page_intro] [manpage modules/page/page_pluginmgr.man page_pluginmgr] [manpage modules/page/page_util_flow.man page_util_flow] [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] @@ -1130,12 +2014,59 @@ [key pager] [manpage modules/term/ipager.man term::interact::pager] [key paragraph] [manpage modules/textutil/textutil.man textutil] [manpage modules/textutil/adjust.man textutil::adjust] +[key PARAM] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[key {parameter entry form}] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_argument_dialogbox.man tepam::argument_dialogbox] [key parser] -[manpage modules/amazon-s3/xsxp.man xsxp] +[manpage modules/doctools2idx/parse.man doctools::idx::parse] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] +[manpage modules/doctools2toc/parse.man doctools::toc::parse] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[manpage modules/amazon-s3/xsxp.man xsxp] [key {parser generator}] [manpage apps/page.man page] [manpage modules/page/page_intro.man page_intro] [manpage modules/page/page_pluginmgr.man page_pluginmgr] [manpage modules/page/page_util_flow.man page_util_flow] @@ -1142,49 +2073,174 @@ [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] [manpage modules/page/page_util_norm_peg.man page_util_norm_peg] [manpage modules/page/page_util_peg.man page_util_peg] [manpage modules/page/page_util_quote.man page_util_quote] [key parsing] -[manpage modules/bench/bench_read.man bench::in] -[manpage modules/bibtex/bibtex.man bibtex] -[manpage modules/grammar_fa/fa.man grammar::fa] -[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] -[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] -[manpage modules/grammar_fa/faop.man grammar::fa::op] -[manpage modules/grammar_me/me_cpu.man grammar::me::cpu] -[manpage modules/grammar_me/me_cpucore.man grammar::me::cpu::core] -[manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] -[manpage modules/grammar_me/me_tcl.man grammar::me::tcl] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_me/me_vm.man grammar::me_vm] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] -[manpage modules/htmlparse/htmlparse.man htmlparse] -[manpage modules/yaml/huddle.man huddle] -[manpage modules/yaml/yaml.man yaml] +[manpage modules/bench/bench_read.man bench::in] +[manpage modules/bibtex/bibtex.man bibtex] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[manpage modules/grammar_fa/fa.man grammar::fa] +[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] +[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] +[manpage modules/grammar_fa/faop.man grammar::fa::op] +[manpage modules/grammar_me/me_cpu.man grammar::me::cpu] +[manpage modules/grammar_me/me_cpucore.man grammar::me::cpu::core] +[manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] +[manpage modules/grammar_me/me_tcl.man grammar::me::tcl] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_me/me_vm.man grammar::me_vm] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/htmlparse/htmlparse.man htmlparse] +[manpage modules/yaml/huddle.man huddle] +[manpage modules/yaml/yaml.man yaml] [key {parsing expression}] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key {parsing expression grammar}] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] -[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[key {partial application}] +[manpage modules/lambda/lambda.man lambda] [key partition] [manpage modules/struct/disjointset.man struct::disjointset] [key {partitioned set}] [manpage modules/struct/disjointset.man struct::disjointset] [key passive] [manpage modules/transfer/connect.man transfer::connect] [key password] [manpage modules/otp/otp.man otp] +[key patch] +[manpage modules/docstrip/docstrip_util.man docstrip_util] [key patching] [manpage modules/rcs/rcs.man rcs] [key PEG] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/page/page_util_norm_peg.man page_util_norm_peg] -[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/page/page_util_norm_peg.man page_util_norm_peg] +[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key performance] [manpage modules/bench/bench.man bench] [manpage modules/bench/bench_read.man bench::in] [manpage modules/bench/bench_wcsv.man bench::out::csv] [manpage modules/bench/bench_wtext.man bench::out::text] @@ -1195,25 +2251,45 @@ [key permutation] [manpage modules/struct/struct_list.man struct::list] [key persistence] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] +[key phone] +[manpage modules/valtype/imei.man valtype::imei] [key pi] [manpage modules/math/constants.man math::constants] +[key {plain text}] +[manpage modules/doctools2idx/export_text.man doctools::idx::export::text] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] [key {plane geometry}] -[manpage modules/math/geometry.man math::geometry] +[manpage modules/math/math_geometry.man math::geometry] [key plugin] -[manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] -[manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] +[manpage modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref] +[manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] [key {plugin management}] [manpage modules/pluginmgr/pluginmgr.man pluginmgr] [key {plugin search}] [manpage modules/pluginmgr/pluginmgr.man pluginmgr] [key png] [manpage modules/png/png.man png] [key point] -[manpage modules/math/geometry.man math::geometry] +[manpage modules/math/math_geometry.man math::geometry] [key {polynomial functions}] [manpage modules/math/polynomials.man math::polynomials] [key pool] [manpage modules/struct/pool.man struct::pool] [manpage modules/struct/queue.man struct::queue] @@ -1229,17 +2305,25 @@ [key pre-order] [manpage modules/struct/struct_tree.man struct::tree] [key prefix] [manpage modules/textutil/textutil_string.man textutil::string] [manpage modules/textutil/trim.man textutil::trim] +[key prime] +[manpage modules/math/numtheory.man math::numtheory] [key prioqueue] [manpage modules/struct/prioqueue.man struct::prioqueue] [manpage modules/struct/queue.man struct::queue] [key {priority queue}] [manpage modules/struct/prioqueue.man struct::prioqueue] +[key proc] +[manpage modules/lambda/lambda.man lambda] [key procedure] -[manpage modules/interp/deleg_proc.man deleg_proc] +[manpage modules/interp/deleg_proc.man deleg_proc] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_procedure.man tepam::procedure] +[key producer] +[manpage modules/hook/hook.man hook] [key profile] [manpage modules/profiler/profiler.man profiler] [key projection] [manpage modules/mapproj/mapproj.man mapproj] [key prospero] @@ -1252,14 +2336,56 @@ [manpage modules/pop3d/pop3d.man pop3d] [manpage modules/pop3d/pop3d_dbox.man pop3d::dbox] [manpage modules/pop3d/pop3d_udb.man pop3d::udb] [key proxy] [manpage modules/http/autoproxy.man autoproxy] +[key {public key cipher}] +[manpage modules/pki/pki.man pki] +[key publisher] +[manpage modules/hook/hook.man hook] [key {push down automaton}] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key queue] [manpage modules/csv/csv.man csv] [manpage modules/htmlparse/htmlparse.man htmlparse] [manpage modules/struct/stack.man struct::stack] [manpage modules/transfer/tqueue.man transfer::copy::queue] @@ -1270,12 +2396,15 @@ [manpage modules/units/units.man units] [key radiobutton] [manpage modules/html/html.man html] [key radius] [manpage modules/struct/graphops.man struct::graph::op] +[key random] +[manpage modules/virtchannel_base/random.man tcl::chan::random] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] [key {random numbers}] -[manpage modules/simulation/random.man simulation::random] +[manpage modules/simulation/simulation_random.man simulation::random] [key {rational functions}] [manpage modules/math/rational_funcs.man math::rationalfunctions] [key raw] [manpage modules/term/ansi_ctrlu.man term::ansi::ctrl::unix] [key rc4] @@ -1282,10 +2411,13 @@ [manpage modules/rc4/rc4.man rc4] [key RCS] [manpage modules/rcs/rcs.man rcs] [key {RCS patch}] [manpage modules/rcs/rcs.man rcs] +[key read] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key reading] [manpage modules/bench/bench_read.man bench::in] [key receiver] [manpage modules/term/receive.man term::receive] [manpage modules/term/term_bind.man term::receive::bind] @@ -1294,15 +2426,92 @@ [manpage modules/nns/nns_auto.man nameserv::auto] [key record] [manpage modules/struct/queue.man struct::queue] [manpage modules/struct/record.man struct::record] [key {recursive descent}] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key reduce] -[manpage modules/struct/struct_list.man struct::list] +[manpage modules/generator/generator.man generator] +[manpage modules/struct/struct_list.man struct::list] +[key reference] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[key {reflected channel}] +[manpage modules/virtchannel_base/cat.man tcl::chan::cat] +[manpage modules/virtchannel_core/core.man tcl::chan::core] +[manpage modules/virtchannel_core/events.man tcl::chan::events] +[manpage modules/virtchannel_base/facade.man tcl::chan::facade] +[manpage modules/virtchannel_base/fifo.man tcl::chan::fifo] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] +[manpage modules/virtchannel_base/memchan.man tcl::chan::memchan] +[manpage modules/virtchannel_base/null.man tcl::chan::null] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[manpage modules/virtchannel_base/random.man tcl::chan::random] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] +[manpage modules/virtchannel_base/std.man tcl::chan::std] +[manpage modules/virtchannel_base/string.man tcl::chan::string] +[manpage modules/virtchannel_base/textwindow.man tcl::chan::textwindow] +[manpage modules/virtchannel_base/variable.man tcl::chan::variable] +[manpage modules/virtchannel_base/zero.man tcl::chan::zero] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[manpage modules/virtchannel_core/transformcore.man tcl::transform::core] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key {regular expression}] [manpage modules/grammar_fa/fa.man grammar::fa] [manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] [manpage modules/grammar_fa/dexec.man grammar::fa::dexec] [manpage modules/grammar_fa/faop.man grammar::fa::op] @@ -1333,12 +2542,18 @@ [key repetition] [manpage modules/struct/struct_list.man struct::list] [manpage modules/textutil/repeat.man textutil::repeat] [key report] [manpage modules/report/report.man report] +[key reshuffle] +[manpage modules/struct/struct_list.man struct::list] +[key {residual graph}] +[manpage modules/struct/graphops.man struct::graph::op] [key resolver] [manpage modules/dns/tcllib_dns.man dns] +[key {resource management}] +[manpage modules/try/tcllib_try.man try] [key restore] [manpage modules/nns/nns_auto.man nameserv::auto] [key reverse] [manpage modules/struct/struct_list.man struct::list] [key {rfc 821}] @@ -1417,10 +2632,12 @@ [manpage modules/mime/smtp.man smtp] [key {rfc 3513}] [manpage modules/dns/tcllib_ip.man tcllib_ip] [key {rfc 4511}] [manpage modules/ldap/ldap.man ldap] +[key rfc3501] +[manpage modules/imap4/imap4.man imap4] [key rfc3548] [manpage modules/base32/base32.man base32] [manpage modules/base32/base32hex.man base32::hex] [key {right outer join}] [manpage modules/struct/struct_list.man struct::list] @@ -1429,25 +2646,40 @@ [manpage modules/ripemd/ripemd160.man ripemd160] [key {roman numeral}] [manpage modules/math/roman.man math::roman] [key roots] [manpage modules/math/calculus.man math::calculus] +[key rot] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[key rot13] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] [key rounding] [manpage modules/math/fuzzy.man math::fuzzy] [key rows] [manpage modules/term/ansi_ctrlu.man term::ansi::ctrl::unix] [key rpc] [manpage modules/comm/comm.man comm] [manpage modules/comm/comm_wire.man comm_wire] +[key rsa] +[manpage modules/pki/pki.man pki] [key running] [manpage modules/grammar_fa/dexec.man grammar::fa::dexec] [key s3] [manpage modules/amazon-s3/S3.man S3] [key SASL] [manpage modules/sasl/sasl.man SASL] +[key scanl] +[manpage modules/generator/generator.man generator] [key SCCS] [manpage modules/rcs/rcs.man rcs] +[key secure] +[manpage modules/comm/comm.man comm] +[manpage modules/pop3/pop3.man pop3] +[manpage modules/pop3d/pop3d.man pop3d] +[manpage modules/transfer/connect.man transfer::connect] +[manpage modules/transfer/receiver.man transfer::receiver] +[manpage modules/transfer/transmitter.man transfer::transmitter] [key security] [manpage modules/aes/aes.man aes] [manpage modules/blowfish/blowfish.man blowfish] [manpage modules/crc/cksum.man cksum] [manpage modules/crc/crc16.man crc16] @@ -1455,16 +2687,19 @@ [manpage modules/des/des.man des] [manpage modules/md4/md4.man md4] [manpage modules/md5/md5.man md5] [manpage modules/md5crypt/md5crypt.man md5crypt] [manpage modules/otp/otp.man otp] +[manpage modules/pki/pki.man pki] [manpage modules/rc4/rc4.man rc4] [manpage modules/ripemd/ripemd128.man ripemd128] [manpage modules/ripemd/ripemd160.man ripemd160] [manpage modules/sha1/sha1.man sha1] [manpage modules/sha1/sha256.man sha256] [manpage modules/crc/sum.man sum] +[key seed] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] [key selectionbox] [manpage modules/javascript/javascript.man javascript] [key {semantic markup}] [manpage modules/doctools/docidx_intro.man docidx_intro] [manpage modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref] @@ -1476,28 +2711,58 @@ [manpage modules/doctools/doctoc_lang_cmdref.man doctoc_lang_cmdref] [manpage modules/doctools/doctoc_lang_faq.man doctoc_lang_faq] [manpage modules/doctools/doctoc_lang_intro.man doctoc_lang_intro] [manpage modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] +[manpage modules/doctools2idx/introduction.man doctools2idx_introduction] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] [manpage modules/doctools/doctools_intro.man doctools_intro] [manpage modules/doctools/doctools_lang_cmdref.man doctools_lang_cmdref] [manpage modules/doctools/doctools_lang_faq.man doctools_lang_faq] [manpage modules/doctools/doctools_lang_intro.man doctools_lang_intro] [manpage modules/doctools/doctools_lang_syntax.man doctools_lang_syntax] [manpage modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref] [key send] [manpage modules/comm/comm.man comm] [key serialization] -[manpage modules/bee/bee.man bee] -[manpage modules/struct/graph.man struct::graph] -[manpage modules/struct/struct_tree.man struct::tree] +[manpage modules/bee/bee.man bee] +[manpage modules/doctools2idx/export_docidx.man doctools::idx::export::docidx] +[manpage modules/doctools2idx/export_html.man doctools::idx::export::html] +[manpage modules/doctools2idx/export_json.man doctools::idx::export::json] +[manpage modules/doctools2idx/export_nroff.man doctools::idx::export::nroff] +[manpage modules/doctools2idx/export_text.man doctools::idx::export::text] +[manpage modules/doctools2idx/export_wiki.man doctools::idx::export::wiki] +[manpage modules/doctools2idx/structure.man doctools::idx::structure] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] +[manpage modules/doctools2toc/structure.man doctools::toc::structure] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/struct/graph.man struct::graph] +[manpage modules/struct/struct_tree.man struct::tree] [key server] -[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] -[manpage modules/nns/nns_common.man nameserv::common] -[manpage modules/nns/nns_server.man nameserv::server] -[manpage modules/nns/nns_intro.man nns_intro] -[manpage apps/nnsd.man nnsd] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] +[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] +[manpage modules/nns/nns_common.man nameserv::common] +[manpage modules/nns/nns_server.man nameserv::server] +[manpage modules/nns/nns_intro.man nns_intro] +[manpage apps/nnsd.man nnsd] [key service] [manpage modules/log/logger.man logger] [key services] [manpage modules/ftpd/ftpd.man ftpd] [manpage modules/smtpd/smtpd.man smtpd] @@ -1506,14 +2771,22 @@ [manpage modules/struct/struct_set.man struct::set] [key sha1] [manpage modules/sha1/sha1.man sha1] [key sha256] [manpage modules/sha1/sha256.man sha256] +[key {shortest path}] +[manpage modules/struct/graphops.man struct::graph::op] +[key shuffle] +[manpage modules/struct/struct_list.man struct::list] [key {simulated annealing}] [manpage modules/simulation/annealing.man simulation::annealing] [key simulation] -[manpage modules/simulation/random.man simulation::random] +[manpage modules/simulation/simulation_random.man simulation::random] +[key singleton] +[manpage modules/ooutil/ooutil.man oo::util] +[key {size limit}] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] [key skiplist] [manpage modules/struct/queue.man struct::queue] [manpage modules/struct/skiplist.man struct::skiplist] [key slippy] [manpage modules/map/map_slippy.man map::slippy] @@ -1540,10 +2813,12 @@ [manpage modules/soundex/soundex.man soundex] [key source] [manpage modules/docstrip/docstrip.man docstrip] [manpage modules/docstrip/docstrip_util.man docstrip_util] [manpage apps/tcldocstrip.man tcldocstrip] +[key spacing] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] [key {spatial interpolation}] [manpage modules/math/interpolate.man math::interpolate] [key {special functions}] [manpage modules/math/special.man math::special] [key specification] @@ -1550,29 +2825,87 @@ [manpage modules/bench/bench_lang_spec.man bench_lang_spec] [key speed] [manpage modules/profiler/profiler.man profiler] [key split] [manpage modules/textutil/textutil_split.man textutil::split] +[key {squared graph}] +[manpage modules/struct/graphops.man struct::graph::op] +[key ssl] +[manpage modules/comm/comm.man comm] +[manpage modules/imap4/imap4.man imap4] +[manpage modules/pop3/pop3.man pop3] +[manpage modules/pop3d/pop3d.man pop3d] +[manpage modules/transfer/connect.man transfer::connect] +[manpage modules/transfer/receiver.man transfer::receiver] +[manpage modules/transfer/transmitter.man transfer::transmitter] [key stack] [manpage modules/struct/queue.man struct::queue] +[key {standard io}] +[manpage modules/virtchannel_base/std.man tcl::chan::std] [key state] -[manpage modules/grammar_fa/fa.man grammar::fa] -[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] -[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] -[manpage modules/grammar_fa/faop.man grammar::fa::op] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_fa/fa.man grammar::fa] +[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] +[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] +[manpage modules/grammar_fa/faop.man grammar::fa::op] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] +[key {state (de)serialization}] +[manpage modules/namespacex/namespacex.man namespacex] [key {statistical distribution}] -[manpage modules/simulation/random.man simulation::random] +[manpage modules/simulation/simulation_random.man simulation::random] [key statistics] [manpage modules/counter/counter.man counter] [manpage modules/math/math.man math] [manpage modules/math/statistics.man math::statistics] +[key stdin] +[manpage modules/virtchannel_base/std.man tcl::chan::std] +[key stdout] +[manpage modules/virtchannel_base/std.man tcl::chan::std] [key {stochastic modelling}] [manpage modules/simulation/montecarlo.man simulation::montecarlo] [key {stream cipher}] [manpage modules/rc4/rc4.man rc4] +[key {stream copy}] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] [key string] [manpage modules/textutil/textutil.man textutil] [manpage modules/textutil/adjust.man textutil::adjust] [manpage modules/textutil/expander.man textutil::expander] [manpage modules/textutil/repeat.man textutil::repeat] @@ -1591,17 +2924,28 @@ [manpage modules/struct/record.man struct::record] [key structure] [manpage modules/control/control.man control] [key {structured queries}] [manpage modules/treeql/treeql.man treeql] +[key style] +[manpage modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults] +[key subcommand] +[manpage modules/tepam/tepam_introduction.man tepam] +[manpage modules/tepam/tepam_procedure.man tepam::procedure] [key subgraph] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] +[key subject] +[manpage modules/hook/hook.man hook] [key submitbutton] [manpage modules/javascript/javascript.man javascript] +[key subscriber] +[manpage modules/hook/hook.man hook] [key subsequence] [manpage modules/struct/struct_list.man struct::list] +[key subst] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] [key sum] [manpage modules/crc/sum.man sum] [key swapping] [manpage modules/struct/struct_list.man struct::list] [key {symmetric difference}] @@ -1609,16 +2953,31 @@ [key synchronous] [manpage modules/cache/async.man cache::async] [key {syntax tree}] [manpage modules/grammar_me/me_util.man grammar::me::util] [key table] -[manpage modules/html/html.man html] -[manpage modules/report/report.man report] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/html/html.man html] +[manpage modules/report/report.man report] [key {table of contents}] [manpage modules/doctools/doctoc_intro.man doctoc_intro] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] +[manpage modules/doctools2toc/introduction.man doctools2toc_introduction] +[manpage modules/doctools2toc/container.man doctools::toc] [manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] [key tabstops] [manpage modules/textutil/tabify.man textutil::tabify] [key tallying] [manpage modules/counter/counter.man counter] [key {tape archive}] @@ -1626,15 +2985,67 @@ [key tar] [manpage modules/tar/tar.man tar] [key tcl] [manpage modules/math/bigfloat.man math::bigfloat] [manpage modules/math/bignum.man math::bignum] +[manpage modules/math/decimal.man math::decimal] +[key {Tcl module}] +[manpage modules/docstrip/docstrip_util.man docstrip_util] +[key {Tcl syntax}] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] +[key {tcler's wiki}] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] [key tcllib] [manpage modules/csv/csv.man csv] +[key TclOO] +[manpage modules/ooutil/ooutil.man oo::util] +[key TCLPARAM] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] [key TDPL] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key {temp file}] [manpage modules/fileutil/fileutil.man fileutil] [key {template processing}] [manpage modules/textutil/expander.man textutil::expander] [key terminal] @@ -1650,10 +3061,24 @@ [manpage modules/term/receive.man term::receive] [manpage modules/term/term_bind.man term::receive::bind] [manpage modules/term/term_send.man term::send] [key test] [manpage modules/fileutil/fileutil.man fileutil] +[key Testing] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] [key testing] [manpage modules/bench/bench.man bench] [manpage modules/bench/bench_read.man bench::in] [manpage modules/bench/bench_wcsv.man bench::out::csv] [manpage modules/bench/bench_wtext.man bench::out::text] @@ -1662,12 +3087,16 @@ [manpage modules/bench/bench_lang_spec.man bench_lang_spec] [key TeX] [manpage modules/textutil/textutil.man textutil] [manpage modules/textutil/adjust.man textutil::adjust] [key text] -[manpage modules/bench/bench_read.man bench::in] -[manpage modules/bench/bench_wtext.man bench::out::text] +[manpage modules/bench/bench_read.man bench::in] +[manpage modules/bench/bench_wtext.man bench::out::text] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] [key {text comparison}] [manpage modules/soundex/soundex.man soundex] [key {text conversion}] [manpage modules/rcs/rcs.man rcs] [key {text differences}] @@ -1689,10 +3118,15 @@ [manpage modules/page/page_util_norm_lemon.man page_util_norm_lemon] [manpage modules/page/page_util_norm_peg.man page_util_norm_peg] [manpage modules/page/page_util_peg.man page_util_peg] [manpage modules/page/page_util_quote.man page_util_quote] [manpage modules/yaml/yaml.man yaml] +[key {text widget}] +[manpage modules/virtchannel_base/textwindow.man tcl::chan::textwindow] +[key threads] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key thumbnail] [manpage modules/jpeg/jpeg.man jpeg] [key tie] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] @@ -1706,64 +3140,210 @@ [manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] [key time] [manpage modules/ntp/ntp_time.man ntp_time] [key timestamp] [manpage modules/png/png.man png] +[key {tip 219}] +[manpage modules/virtchannel_base/cat.man tcl::chan::cat] +[manpage modules/virtchannel_core/core.man tcl::chan::core] +[manpage modules/virtchannel_core/events.man tcl::chan::events] +[manpage modules/virtchannel_base/facade.man tcl::chan::facade] +[manpage modules/virtchannel_base/fifo.man tcl::chan::fifo] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] +[manpage modules/virtchannel_base/memchan.man tcl::chan::memchan] +[manpage modules/virtchannel_base/null.man tcl::chan::null] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[manpage modules/virtchannel_base/random.man tcl::chan::random] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] +[manpage modules/virtchannel_base/std.man tcl::chan::std] +[manpage modules/virtchannel_base/string.man tcl::chan::string] +[manpage modules/virtchannel_base/textwindow.man tcl::chan::textwindow] +[manpage modules/virtchannel_base/variable.man tcl::chan::variable] +[manpage modules/virtchannel_base/zero.man tcl::chan::zero] +[manpage modules/virtchannel_core/transformcore.man tcl::transform::core] +[key {tip 230}] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] +[key {tip 234}] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] +[key {tip 317}] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[key Tk] +[manpage modules/virtchannel_base/textwindow.man tcl::chan::textwindow] [key tls] -[manpage modules/mime/smtp.man smtp] +[manpage modules/comm/comm.man comm] +[manpage modules/imap4/imap4.man imap4] +[manpage modules/pop3/pop3.man pop3] +[manpage modules/pop3d/pop3d.man pop3d] +[manpage modules/mime/smtp.man smtp] +[manpage modules/transfer/connect.man transfer::connect] +[manpage modules/transfer/receiver.man transfer::receiver] +[manpage modules/transfer/transmitter.man transfer::transmitter] [key TMML] -[manpage modules/doctools/doctools.man doctools] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] -[manpage apps/dtplite.man dtplite] -[manpage modules/doctools/mpexpand.man mpexpand] +[manpage modules/doctools/doctools.man doctools] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage apps/dtplite.man dtplite] +[manpage modules/doctools/mpexpand.man mpexpand] [key toc] [manpage modules/doctools/doctoc_intro.man doctoc_intro] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] [manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc] +[manpage modules/doctools2toc/export_html.man doctools::toc::export::html] +[manpage modules/doctools2toc/export_json.man doctools::toc::export::json] +[manpage modules/doctools2toc/export_nroff.man doctools::toc::export::nroff] +[manpage modules/doctools2toc/export_text.man doctools::toc::export::text] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] +[manpage modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc] +[manpage modules/doctools2toc/import_json.man doctools::toc::import::json] [key {toc formatter}] [manpage modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref] [key {top-down parsing languages}] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key torrent] [manpage modules/bee/bee.man bee] [key touch] [manpage modules/fileutil/fileutil.man fileutil] [key TPDL] [manpage modules/grammar_me/me_intro.man grammar::me_intro] [key transducer] -[manpage modules/grammar_fa/fa.man grammar::fa] -[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] -[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] -[manpage modules/grammar_fa/faop.man grammar::fa::op] -[manpage modules/grammar_me/me_intro.man grammar::me_intro] -[manpage modules/grammar_peg/peg.man grammar::peg] -[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/grammar_aycock/aycock.man grammar::aycock] +[manpage modules/grammar_fa/fa.man grammar::fa] +[manpage modules/grammar_fa/dacceptor.man grammar::fa::dacceptor] +[manpage modules/grammar_fa/dexec.man grammar::fa::dexec] +[manpage modules/grammar_fa/faop.man grammar::fa::op] +[manpage modules/grammar_me/me_intro.man grammar::me_intro] +[manpage modules/grammar_peg/peg.man grammar::peg] +[manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt.man pt] +[manpage modules/pt/pt_astree.man pt::ast] +[manpage modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl] +[manpage modules/pt/pt_json_language.man pt::json_language] +[manpage modules/pt/pt_param.man pt::param] +[manpage modules/pt/pt_pexpression.man pt::pe] +[manpage modules/pt/pt_pexpr_op.man pt::pe::op] +[manpage modules/pt/pt_pegrammar.man pt::peg] +[manpage modules/pt/pt_peg_container.man pt::peg::container] +[manpage modules/pt/pt_peg_container_peg.man pt::peg::container::peg] +[manpage modules/pt/pt_peg_export.man pt::peg::export] +[manpage modules/pt/pt_peg_export_container.man pt::peg::export::container] +[manpage modules/pt/pt_peg_export_json.man pt::peg::export::json] +[manpage modules/pt/pt_peg_export_peg.man pt::peg::export::peg] +[manpage modules/pt/pt_peg_from_container.man pt::peg::from::container] +[manpage modules/pt/pt_peg_from_json.man pt::peg::from::json] +[manpage modules/pt/pt_peg_from_peg.man pt::peg::from::peg] +[manpage modules/pt/pt_peg_import.man pt::peg::import] +[manpage modules/pt/pt_peg_import_container.man pt::peg::import::container] +[manpage modules/pt/pt_peg_import_json.man pt::peg::import::json] +[manpage modules/pt/pt_peg_import_peg.man pt::peg::import::peg] +[manpage modules/pt/pt_peg_interp.man pt::peg::interp] +[manpage modules/pt/pt_peg_to_container.man pt::peg::to::container] +[manpage modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam] +[manpage modules/pt/pt_peg_to_json.man pt::peg::to::json] +[manpage modules/pt/pt_peg_to_param.man pt::peg::to::param] +[manpage modules/pt/pt_peg_to_peg.man pt::peg::to::peg] +[manpage modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam] +[manpage modules/pt/pt_peg_language.man pt::peg_language] +[manpage modules/pt/pt_peg_introduction.man pt::pegrammar] +[manpage modules/pt/pt_pgen.man pt::pgen] +[manpage modules/pt/pt_rdengine.man pt::rde] +[manpage modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit] +[manpage modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo] +[manpage modules/pt/pt_to_api.man pt_export_api] +[manpage modules/pt/pt_from_api.man pt_import_api] +[manpage modules/pt/pt_introduction.man pt_introduction] +[manpage modules/pt/pt_parser_api.man pt_parser_api] [key transfer] [manpage modules/transfer/connect.man transfer::connect] [manpage modules/transfer/copyops.man transfer::copy] [manpage modules/transfer/tqueue.man transfer::copy::queue] [manpage modules/transfer/ddest.man transfer::data::destination] [manpage modules/transfer/dsource.man transfer::data::source] [manpage modules/transfer/receiver.man transfer::receiver] [manpage modules/transfer/transmitter.man transfer::transmitter] [key transformation] -[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/page/page_util_peg.man page_util_peg] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key transmitter] [manpage modules/transfer/transmitter.man transfer::transmitter] +[key {travelling salesman}] +[manpage modules/struct/graphops.man struct::graph::op] [key traversal] [manpage modules/fileutil/traverse.man fileutil_traverse] [key tree] [manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] [manpage modules/grammar_me/me_util.man grammar::me::util] [manpage modules/htmlparse/htmlparse.man htmlparse] [manpage modules/struct/queue.man struct::queue] [manpage modules/struct/stack.man struct::stack] [manpage modules/struct/struct_tree.man struct::tree] -[manpage modules/struct/struct_tree1.man {struct::tree v1}] +[manpage modules/struct/struct_tree1.man struct::tree_v1] [manpage modules/treeql/treeql.man treeql] [key {tree query language}] [manpage modules/treeql/treeql.man treeql] [key {tree walking}] [manpage modules/page/page_util_flow.man page_util_flow] @@ -1780,10 +3360,26 @@ [manpage modules/fumagic/cgen.man fileutil::magic::cgen] [manpage modules/fumagic/filetypes.man fileutil::magic::filetype] [manpage modules/fumagic/mimetypes.man fileutil::magic::mimetype] [manpage modules/fumagic/rtcore.man fileutil::magic::rt] [manpage modules/snit/snit.man snit] +[key {Type checking}] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] +[key uevent] +[manpage modules/hook/hook.man hook] [key unbind] [manpage modules/uev/uevent.man uevent] [key uncapitalize] [manpage modules/textutil/textutil_string.man textutil::string] [key undenting] @@ -1796,54 +3392,144 @@ [key union] [manpage modules/struct/disjointset.man struct::disjointset] [manpage modules/struct/struct_set.man struct::set] [key unit] [manpage modules/units/units.man units] +[key {unknown hooking}] +[manpage modules/namespacex/namespacex.man namespacex] [key untie] [manpage modules/tie/tie.man tie] [manpage modules/tie/tie_std.man tie] +[key update] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] [key uri] [manpage modules/uri/uri.man uri] [manpage modules/uri/urn-scheme.man uri_urn] [key url] -[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] -[manpage modules/uri/uri.man uri] -[manpage modules/uri/urn-scheme.man uri_urn] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/import.man doctools::idx::import] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/import.man doctools::toc::import] +[manpage modules/map/map_geocode_nominatim.man map::geocode::nominatim] +[manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] +[manpage modules/uri/uri.man uri] +[manpage modules/uri/urn-scheme.man uri_urn] [key urn] [manpage modules/uri/urn-scheme.man uri_urn] +[key US-NPI] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[key utilities] +[manpage modules/namespacex/namespacex.man namespacex] [key uuencode] [manpage modules/base64/uuencode.man uuencode] [key UUID] [manpage modules/uuid/uuid.man uuid] +[key Validation] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] +[key {Value checking}] +[manpage modules/valtype/valtype_common.man valtype::common] +[manpage modules/valtype/cc_amex.man valtype::creditcard::amex] +[manpage modules/valtype/cc_discover.man valtype::creditcard::discover] +[manpage modules/valtype/cc_mastercard.man valtype::creditcard::mastercard] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] +[manpage modules/valtype/ean13.man valtype::gs1::ean13] +[manpage modules/valtype/iban.man valtype::iban] +[manpage modules/valtype/imei.man valtype::imei] +[manpage modules/valtype/isbn.man valtype::isbn] +[manpage modules/valtype/luhn.man valtype::luhn] +[manpage modules/valtype/luhn5.man valtype::luhn5] +[manpage modules/valtype/usnpi.man valtype::usnpi] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] [key vectors] [manpage modules/math/linalg.man math::linearalgebra] +[key verhoeff] +[manpage modules/valtype/verhoeff.man valtype::verhoeff] [key vertex] [manpage modules/struct/graph.man struct::graph] [manpage modules/struct/graphops.man struct::graph::op] +[key {vertex cover}] +[manpage modules/struct/graphops.man struct::graph::op] +[key {virtual channel}] +[manpage modules/virtchannel_base/cat.man tcl::chan::cat] +[manpage modules/virtchannel_core/core.man tcl::chan::core] +[manpage modules/virtchannel_core/events.man tcl::chan::events] +[manpage modules/virtchannel_base/facade.man tcl::chan::facade] +[manpage modules/virtchannel_base/fifo.man tcl::chan::fifo] +[manpage modules/virtchannel_base/fifo2.man tcl::chan::fifo2] +[manpage modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe] +[manpage modules/virtchannel_base/memchan.man tcl::chan::memchan] +[manpage modules/virtchannel_base/null.man tcl::chan::null] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[manpage modules/virtchannel_base/random.man tcl::chan::random] +[manpage modules/virtchannel_base/randseed.man tcl::chan::randseed] +[manpage modules/virtchannel_base/std.man tcl::chan::std] +[manpage modules/virtchannel_base/string.man tcl::chan::string] +[manpage modules/virtchannel_base/textwindow.man tcl::chan::textwindow] +[manpage modules/virtchannel_base/variable.man tcl::chan::variable] +[manpage modules/virtchannel_base/zero.man tcl::chan::zero] +[manpage modules/virtchannel_transform/adler32.man tcl::transform::adler32] +[manpage modules/virtchannel_transform/base64.man tcl::transform::base64] +[manpage modules/virtchannel_core/transformcore.man tcl::transform::core] +[manpage modules/virtchannel_transform/counter.man tcl::transform::counter] +[manpage modules/virtchannel_transform/crc32.man tcl::transform::crc32] +[manpage modules/virtchannel_transform/hex.man tcl::transform::hex] +[manpage modules/virtchannel_transform/identity.man tcl::transform::identity] +[manpage modules/virtchannel_transform/limitsize.man tcl::transform::limitsize] +[manpage modules/virtchannel_transform/observe.man tcl::transform::observe] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] +[manpage modules/virtchannel_transform/rot.man tcl::transform::rot] +[manpage modules/virtchannel_transform/spacer.man tcl::transform::spacer] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key {virtual machine}] [manpage modules/grammar_me/me_cpu.man grammar::me::cpu] [manpage modules/grammar_me/me_cpucore.man grammar::me::cpu::core] [manpage modules/grammar_me/gasm.man grammar::me::cpu::gasm] [manpage modules/grammar_me/me_tcl.man grammar::me::tcl] [manpage modules/grammar_me/me_intro.man grammar::me_intro] [manpage modules/grammar_me/me_vm.man grammar::me_vm] [manpage modules/grammar_peg/peg_interp.man grammar::peg::interp] +[manpage modules/pt/pt_param.man pt::param] +[key VISA] +[manpage modules/valtype/cc_visa.man valtype::creditcard::visa] [key vwait] -[manpage modules/smtpd/smtpd.man smtpd] +[manpage modules/coroutine/coroutine.man coroutine] +[manpage modules/coroutine/coro_auto.man coroutine::auto] +[manpage modules/smtpd/smtpd.man smtpd] [key wais] [manpage modules/uri/uri.man uri] [key widget] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [key {widget adaptors}] [manpage modules/snit/snit.man snit] [manpage modules/snit/snitfaq.man snitfaq] [key wiki] -[manpage modules/doctools/docidx.man doctools::idx] -[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2idx/container.man doctools::idx] +[manpage modules/doctools/docidx.man doctools::idx] +[manpage modules/doctools2idx/export.man doctools::idx::export] +[manpage modules/doctools2idx/export_wiki.man doctools::idx::export::wiki] +[manpage modules/doctools2toc/container.man doctools::toc] +[manpage modules/doctools/doctoc.man doctools::toc] +[manpage modules/doctools2toc/export.man doctools::toc::export] +[manpage modules/doctools2toc/export_wiki.man doctools::toc::export::wiki] [key word] -[manpage modules/wip/wip.man wip] +[manpage modules/doctools2base/tcl_parse.man doctools::tcl::parse] +[manpage modules/wip/wip.man wip] [key www] [manpage modules/uri/uri.man uri] [key x.208] [manpage modules/asn/asn.man asn] [key x.209] @@ -1850,10 +3536,12 @@ [manpage modules/asn/asn.man asn] [key x.500] [manpage modules/ldap/ldap.man ldap] [key xml] [manpage modules/amazon-s3/xsxp.man xsxp] +[key xor] +[manpage modules/virtchannel_transform/otp.man tcl::transform::otp] [key XPath] [manpage modules/treeql/treeql.man treeql] [key XSLT] [manpage modules/treeql/treeql.man treeql] [key yaml] @@ -1863,10 +3551,15 @@ [manpage modules/base64/yencode.man yencode] [key yEnc] [manpage modules/base64/yencode.man yencode] [key yencode] [manpage modules/base64/yencode.man yencode] +[key zero] +[manpage modules/virtchannel_base/nullzero.man tcl::chan::nullzero] +[manpage modules/virtchannel_base/zero.man tcl::chan::zero] +[key zlib] +[manpage modules/virtchannel_transform/zlib.man tcl::transform::zlib] [key zoom] [manpage modules/map/map_slippy.man map::slippy] [manpage modules/map/map_slippy_cache.man map::slippy::cache] [manpage modules/map/map_slippy_fetcher.man map::slippy::fetcher] [index_end] Index: support/devel/sak/doc/manpages.txt ================================================================== --- support/devel/sak/doc/manpages.txt +++ support/devel/sak/doc/manpages.txt @@ -9,10 +9,11 @@ modules/amazon-s3/xsxp.man modules/asn/asn.man modules/base32/base32.man modules/base32/base32core.man modules/base32/base32hex.man +modules/base64/ascii85.man modules/base64/base64.man modules/base64/uuencode.man modules/base64/yencode.man modules/bee/bee.man modules/bench/bench.man @@ -23,14 +24,18 @@ modules/bench/bench_wcsv.man modules/bench/bench_wtext.man modules/bibtex/bibtex.man modules/blowfish/blowfish.man modules/cache/async.man +modules/clock/iso8601.man +modules/clock/rfc2822.man modules/cmdline/cmdline.man modules/comm/comm.man modules/comm/comm_wire.man modules/control/control.man +modules/coroutine/coro_auto.man +modules/coroutine/coroutine.man modules/counter/counter.man modules/crc/cksum.man modules/crc/crc16.man modules/crc/crc32.man modules/crc/sum.man @@ -62,10 +67,50 @@ modules/doctools/doctools_lang_faq.man modules/doctools/doctools_lang_intro.man modules/doctools/doctools_lang_syntax.man modules/doctools/doctools_plugin_apiref.man modules/doctools/mpexpand.man +modules/doctools2base/html_cssdefaults.man +modules/doctools2base/nroff_manmacros.man +modules/doctools2base/tcl_parse.man +modules/doctools2base/tcllib_msgcat.man +modules/doctools2idx/container.man +modules/doctools2idx/export.man +modules/doctools2idx/export_docidx.man +modules/doctools2idx/export_html.man +modules/doctools2idx/export_json.man +modules/doctools2idx/export_nroff.man +modules/doctools2idx/export_text.man +modules/doctools2idx/export_wiki.man +modules/doctools2idx/import.man +modules/doctools2idx/import_docidx.man +modules/doctools2idx/import_json.man +modules/doctools2idx/introduction.man +modules/doctools2idx/msgcat_c.man +modules/doctools2idx/msgcat_de.man +modules/doctools2idx/msgcat_en.man +modules/doctools2idx/msgcat_fr.man +modules/doctools2idx/parse.man +modules/doctools2idx/structure.man +modules/doctools2toc/container.man +modules/doctools2toc/export.man +modules/doctools2toc/export_doctoc.man +modules/doctools2toc/export_html.man +modules/doctools2toc/export_json.man +modules/doctools2toc/export_nroff.man +modules/doctools2toc/export_text.man +modules/doctools2toc/export_wiki.man +modules/doctools2toc/import.man +modules/doctools2toc/import_doctoc.man +modules/doctools2toc/import_json.man +modules/doctools2toc/introduction.man +modules/doctools2toc/msgcat_c.man +modules/doctools2toc/msgcat_de.man +modules/doctools2toc/msgcat_en.man +modules/doctools2toc/msgcat_fr.man +modules/doctools2toc/parse.man +modules/doctools2toc/structure.man modules/exif/exif.man modules/fileutil/fileutil.man modules/fileutil/multi.man modules/fileutil/multiop.man modules/fileutil/traverse.man @@ -75,10 +120,13 @@ modules/fumagic/cfront.man modules/fumagic/cgen.man modules/fumagic/filetypes.man modules/fumagic/mimetypes.man modules/fumagic/rtcore.man +modules/generator/generator.man +modules/gpx/gpx.man +modules/grammar_aycock/aycock.man modules/grammar_fa/dacceptor.man modules/grammar_fa/dexec.man modules/grammar_fa/fa.man modules/grammar_fa/faop.man modules/grammar_me/gasm.man @@ -89,58 +137,68 @@ modules/grammar_me/me_tcl.man modules/grammar_me/me_util.man modules/grammar_me/me_vm.man modules/grammar_peg/peg.man modules/grammar_peg/peg_interp.man +modules/hook/hook.man modules/html/html.man modules/htmlparse/htmlparse.man modules/http/autoproxy.man modules/ident/ident.man +modules/imap4/imap4.man modules/inifile/ini.man modules/interp/deleg_method.man modules/interp/deleg_proc.man modules/interp/tcllib_interp.man modules/irc/irc.man modules/irc/picoirc.man modules/javascript/javascript.man modules/jpeg/jpeg.man modules/json/json.man +modules/json/json_write.man +modules/lambda/lambda.man modules/ldap/ldap.man modules/ldap/ldapx.man modules/log/log.man modules/log/logger.man modules/log/loggerAppender.man modules/log/loggerUtils.man +modules/map/map_geocode_nominatim.man modules/map/map_slippy.man modules/map/map_slippy_cache.man modules/map/map_slippy_fetcher.man modules/mapproj/mapproj.man modules/math/bigfloat.man modules/math/bignum.man modules/math/calculus.man modules/math/combinatorics.man modules/math/constants.man +modules/math/decimal.man modules/math/fourier.man modules/math/fuzzy.man -modules/math/geometry.man modules/math/interpolate.man modules/math/linalg.man +modules/math/machineparameters.man modules/math/math.man +modules/math/math_geometry.man +modules/math/numtheory.man modules/math/optimize.man modules/math/polynomials.man modules/math/qcomplex.man modules/math/rational_funcs.man modules/math/roman.man modules/math/romberg.man modules/math/special.man modules/math/statistics.man +modules/math/symdiff.man modules/md4/md4.man modules/md5/md5.man modules/md5crypt/md5crypt.man modules/mime/mime.man modules/mime/smtp.man modules/multiplexer/multiplexer.man +modules/namespacex/namespacex.man modules/ncgi/ncgi.man modules/nmea/nmea.man modules/nns/nns_auto.man modules/nns/nns_client.man modules/nns/nns_common.man @@ -147,36 +205,77 @@ modules/nns/nns_intro.man modules/nns/nns_protocol.man modules/nns/nns_server.man modules/nntp/nntp.man modules/ntp/ntp_time.man +modules/ooutil/ooutil.man modules/otp/otp.man modules/page/page_intro.man modules/page/page_pluginmgr.man modules/page/page_util_flow.man modules/page/page_util_norm_lemon.man modules/page/page_util_norm_peg.man modules/page/page_util_peg.man modules/page/page_util_quote.man +modules/pki/pki.man modules/pluginmgr/pluginmgr.man modules/png/png.man modules/pop3/pop3.man modules/pop3d/pop3d.man modules/pop3d/pop3d_dbox.man modules/pop3d/pop3d_udb.man modules/profiler/profiler.man +modules/pt/pt.man +modules/pt/pt_astree.man +modules/pt/pt_cparam_config_critcl.man +modules/pt/pt_from_api.man +modules/pt/pt_introduction.man +modules/pt/pt_json_language.man +modules/pt/pt_param.man +modules/pt/pt_parser_api.man +modules/pt/pt_peg_container.man +modules/pt/pt_peg_container_peg.man +modules/pt/pt_peg_export.man +modules/pt/pt_peg_export_container.man +modules/pt/pt_peg_export_json.man +modules/pt/pt_peg_export_peg.man +modules/pt/pt_peg_from_container.man +modules/pt/pt_peg_from_json.man +modules/pt/pt_peg_from_peg.man +modules/pt/pt_peg_import.man +modules/pt/pt_peg_import_container.man +modules/pt/pt_peg_import_json.man +modules/pt/pt_peg_import_peg.man +modules/pt/pt_peg_interp.man +modules/pt/pt_peg_introduction.man +modules/pt/pt_peg_language.man +modules/pt/pt_peg_to_container.man +modules/pt/pt_peg_to_cparam.man +modules/pt/pt_peg_to_json.man +modules/pt/pt_peg_to_param.man +modules/pt/pt_peg_to_peg.man +modules/pt/pt_peg_to_tclparam.man +modules/pt/pt_pegrammar.man +modules/pt/pt_pexpr_op.man +modules/pt/pt_pexpression.man +modules/pt/pt_pgen.man +modules/pt/pt_rdengine.man +modules/pt/pt_tclparam_config_snit.man +modules/pt/pt_tclparam_config_tcloo.man +modules/pt/pt_to_api.man modules/rc4/rc4.man modules/rcs/rcs.man modules/report/report.man +modules/rest/rest.man modules/ripemd/ripemd128.man modules/ripemd/ripemd160.man modules/sasl/sasl.man modules/sha1/sha1.man modules/sha1/sha256.man modules/simulation/annealing.man modules/simulation/montecarlo.man -modules/simulation/random.man +modules/simulation/simulation_random.man modules/smtpd/smtpd.man modules/snit/snit.man modules/snit/snitfaq.man modules/soundex/soundex.man modules/stooop/stooop.man @@ -199,10 +298,13 @@ modules/struct/struct_list.man modules/struct/struct_set.man modules/struct/struct_tree.man modules/struct/struct_tree1.man modules/tar/tar.man +modules/tepam/tepam_argument_dialogbox.man +modules/tepam/tepam_introduction.man +modules/tepam/tepam_procedure.man modules/term/ansi_cattr.man modules/term/ansi_cctrl.man modules/term/ansi_cmacros.man modules/term/ansi_code.man modules/term/ansi_ctrlu.man @@ -230,14 +332,58 @@ modules/transfer/dsource.man modules/transfer/receiver.man modules/transfer/tqueue.man modules/transfer/transmitter.man modules/treeql/treeql.man +modules/try/tcllib_try.man modules/uev/uevent.man modules/uev/uevent_onidle.man modules/units/units.man modules/uri/uri.man modules/uri/urn-scheme.man modules/uuid/uuid.man +modules/valtype/cc_amex.man +modules/valtype/cc_discover.man +modules/valtype/cc_mastercard.man +modules/valtype/cc_visa.man +modules/valtype/ean13.man +modules/valtype/iban.man +modules/valtype/imei.man +modules/valtype/isbn.man +modules/valtype/luhn.man +modules/valtype/luhn5.man +modules/valtype/usnpi.man +modules/valtype/valtype_common.man +modules/valtype/verhoeff.man +modules/virtchannel_base/cat.man +modules/virtchannel_base/facade.man +modules/virtchannel_base/fifo.man +modules/virtchannel_base/fifo2.man +modules/virtchannel_base/halfpipe.man +modules/virtchannel_base/memchan.man +modules/virtchannel_base/null.man +modules/virtchannel_base/nullzero.man +modules/virtchannel_base/random.man +modules/virtchannel_base/randseed.man +modules/virtchannel_base/std.man +modules/virtchannel_base/string.man +modules/virtchannel_base/textwindow.man +modules/virtchannel_base/variable.man +modules/virtchannel_base/zero.man +modules/virtchannel_core/core.man +modules/virtchannel_core/events.man +modules/virtchannel_core/transformcore.man +modules/virtchannel_transform/adler32.man +modules/virtchannel_transform/base64.man +modules/virtchannel_transform/counter.man +modules/virtchannel_transform/crc32.man +modules/virtchannel_transform/hex.man +modules/virtchannel_transform/identity.man +modules/virtchannel_transform/limitsize.man +modules/virtchannel_transform/observe.man +modules/virtchannel_transform/otp.man +modules/virtchannel_transform/rot.man +modules/virtchannel_transform/spacer.man +modules/virtchannel_transform/zlib.man modules/wip/wip.man modules/yaml/huddle.man modules/yaml/yaml.man Index: support/devel/sak/doc/toc.txt ================================================================== --- support/devel/sak/doc/toc.txt +++ support/devel/sak/doc/toc.txt @@ -1,7 +1,10 @@ [toc_begin {Table Of Contents} {}] [division_start {By Categories}] +[division_start {Argument entry form, mega widget}] +[item modules/tepam/tepam_argument_dialogbox.man tepam::argument_dialogbox {TEPAM argument_dialogbox, reference manual}] +[division_end] [division_start {Benchmark tools}] [item modules/bench/bench.man bench {bench - Processing benchmark suites}] [item modules/bench/bench_read.man bench::in {bench::in - Reading benchmark results}] [item modules/bench/bench_wcsv.man bench::out::csv {bench::out::csv - Formatting benchmark results as CSV}] [item modules/bench/bench_wtext.man bench::out::text {bench::out::text - Formatting benchmark results as human readable text}] @@ -8,75 +11,138 @@ [item modules/bench/bench_intro.man bench_intro {bench introduction}] [item modules/bench/bench_lang_intro.man bench_lang_intro {bench language introduction}] [item modules/bench/bench_lang_spec.man bench_lang_spec {bench language specification}] [division_end] [division_start {CGI programming}] -[item modules/html/html.man html {Procedures to generate HTML structures}] -[item modules/javascript/javascript.man javascript {Procedures to generate HTML and Java Script structures.}] -[item modules/json/json.man json {JSON parser}] -[item modules/ncgi/ncgi.man ncgi {Procedures to manipulate CGI values.}] +[item modules/html/html.man html {Procedures to generate HTML structures}] +[item modules/javascript/javascript.man javascript {Procedures to generate HTML and Java Script structures.}] +[item modules/json/json.man json {JSON parser}] +[item modules/json/json_write.man json::write {JSON generation}] +[item modules/ncgi/ncgi.man ncgi {Procedures to manipulate CGI values.}] +[division_end] +[division_start Channels] +[item modules/virtchannel_base/cat.man tcl::chan::cat {Concatenation channel}] +[item modules/virtchannel_core/core.man tcl::chan::core {Basic reflected/virtual channel support}] +[item modules/virtchannel_core/events.man tcl::chan::events {Event support for reflected/virtual channels}] +[item modules/virtchannel_base/facade.man tcl::chan::facade {Facade channel}] +[item modules/virtchannel_base/fifo.man tcl::chan::fifo {In-memory fifo channel}] +[item modules/virtchannel_base/fifo2.man tcl::chan::fifo2 {In-memory interconnected fifo channels}] +[item modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe {In-memory channel, half of a fifo2}] +[item modules/virtchannel_base/memchan.man tcl::chan::memchan {In-memory channel}] +[item modules/virtchannel_base/null.man tcl::chan::null {Null channel}] +[item modules/virtchannel_base/nullzero.man tcl::chan::nullzero {Null/Zero channel combination}] +[item modules/virtchannel_base/random.man tcl::chan::random {Random channel}] +[item modules/virtchannel_base/randseed.man tcl::chan::randseed {Utilities for random channels}] +[item modules/virtchannel_base/std.man tcl::chan::std {Standard I/O, unification of stdin and stdout}] +[item modules/virtchannel_base/string.man tcl::chan::string {Read-only in-memory channel}] +[item modules/virtchannel_base/textwindow.man tcl::chan::textwindow {Textwindow channel}] +[item modules/virtchannel_base/variable.man tcl::chan::variable {In-memory channel using variable for storage}] +[item modules/virtchannel_base/zero.man tcl::chan::zero {Zero channel}] +[item modules/virtchannel_transform/adler32.man tcl::transform::adler32 {Adler32 transformation}] +[item modules/virtchannel_transform/base64.man tcl::transform::base64 {Base64 encoding transformation}] +[item modules/virtchannel_core/transformcore.man tcl::transform::core {Basic reflected/virtual channel transform support}] +[item modules/virtchannel_transform/counter.man tcl::transform::counter {Counter transformation}] +[item modules/virtchannel_transform/crc32.man tcl::transform::crc32 {Crc32 transformation}] +[item modules/virtchannel_transform/hex.man tcl::transform::hex {Hexadecimal encoding transformation}] +[item modules/virtchannel_transform/identity.man tcl::transform::identity {Identity transformation}] +[item modules/virtchannel_transform/limitsize.man tcl::transform::limitsize {limiting input}] +[item modules/virtchannel_transform/observe.man tcl::transform::observe {Observer transformation, stream copy}] +[item modules/virtchannel_transform/otp.man tcl::transform::otp {Encryption via one-time pad}] +[item modules/virtchannel_transform/rot.man tcl::transform::rot rot-encryption] +[item modules/virtchannel_transform/spacer.man tcl::transform::spacer {Space insertation and removal}] +[item modules/virtchannel_transform/zlib.man tcl::transform::zlib {zlib (de)compression}] +[division_end] +[division_start Coroutine] +[item modules/coroutine/coroutine.man coroutine {Coroutine based event and IO handling}] +[item modules/coroutine/coro_auto.man coroutine::auto {Automatic event and IO coroutine awareness}] [division_end] [division_start {Data structures}] [item modules/counter/counter.man counter {Procedures for counters and histograms}] [item modules/report/report.man report {Create and manipulate report objects}] [item modules/struct/disjointset.man struct::disjointset {Disjoint set data structure}] [item modules/struct/graph.man struct::graph {Create and manipulate directed graph objects}] -[item modules/struct/graph1.man {struct::graph v1} {Create and manipulate directed graph objects}] [item modules/struct/graphops.man struct::graph::op {Operation for (un)directed graph objects}] +[item modules/struct/graph1.man struct::graph_v1 {Create and manipulate directed graph objects}] [item modules/struct/struct_list.man struct::list {Procedures for manipulating lists}] [item modules/struct/matrix.man struct::matrix {Create and manipulate matrix objects}] -[item modules/struct/matrix1.man {struct::matrix v1} {Create and manipulate matrix objects}] +[item modules/struct/matrix1.man struct::matrix_v1 {Create and manipulate matrix objects}] [item modules/struct/pool.man struct::pool {Create and manipulate pool objects (of discrete items)}] [item modules/struct/prioqueue.man struct::prioqueue {Create and manipulate prioqueue objects}] [item modules/struct/queue.man struct::queue {Create and manipulate queue objects}] [item modules/struct/record.man struct::record {Define and create records (similar to 'C' structures)}] [item modules/struct/struct_set.man struct::set {Procedures for manipulating sets}] [item modules/struct/skiplist.man struct::skiplist {Create and manipulate skiplists}] [item modules/struct/stack.man struct::stack {Create and manipulate stack objects}] [item modules/struct/struct_tree.man struct::tree {Create and manipulate tree objects}] -[item modules/struct/struct_tree1.man {struct::tree v1} {Create and manipulate tree objects}] +[item modules/struct/struct_tree1.man struct::tree_v1 {Create and manipulate tree objects}] [item modules/treeql/treeql.man treeql {Query tree objects}] [division_end] [division_start {Documentation tools}] -[item modules/doctools/docidx_intro.man docidx_intro {docidx introduction}] -[item modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref {docidx language command reference}] -[item modules/doctools/docidx_lang_faq.man docidx_lang_faq {docidx language faq}] -[item modules/doctools/docidx_lang_intro.man docidx_lang_intro {docidx language introduction}] -[item modules/doctools/docidx_lang_syntax.man docidx_lang_syntax {docidx language syntax}] -[item modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref {docidx plugin API reference}] -[item modules/docstrip/docstrip.man docstrip {Docstrip style source code extraction}] -[item modules/docstrip/docstrip_util.man docstrip_util {Docstrip-related utilities}] -[item modules/doctools/doctoc_intro.man doctoc_intro {doctoc introduction}] -[item modules/doctools/doctoc_lang_cmdref.man doctoc_lang_cmdref {doctoc language command reference}] -[item modules/doctools/doctoc_lang_faq.man doctoc_lang_faq {doctoc language faq}] -[item modules/doctools/doctoc_lang_intro.man doctoc_lang_intro {doctoc language introduction}] -[item modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax {doctoc language syntax}] -[item modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref {doctoc plugin API reference}] -[item modules/doctools/doctools.man doctools {doctools - Processing documents}] -[item modules/doctools/changelog.man doctools::changelog {Processing text in Emacs ChangeLog format}] -[item modules/doctools/cvs.man doctools::cvs {Processing text in 'cvs log' format}] -[item modules/doctools/docidx.man doctools::idx {docidx - Processing indices}] -[item modules/doctools/doctoc.man doctools::toc {doctoc - Processing tables of contents}] -[item modules/doctools/doctools_intro.man doctools_intro {doctools introduction}] -[item modules/doctools/doctools_lang_cmdref.man doctools_lang_cmdref {doctools language command reference}] -[item modules/doctools/doctools_lang_faq.man doctools_lang_faq {doctools language faq}] -[item modules/doctools/doctools_lang_intro.man doctools_lang_intro {doctools language introduction}] -[item modules/doctools/doctools_lang_syntax.man doctools_lang_syntax {doctools language syntax}] -[item modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref {doctools plugin API reference}] -[item apps/dtplite.man dtplite {Lightweight DocTools Markup Processor}] -[item modules/doctools/mpexpand.man mpexpand {Markup processor}] -[item apps/tcldocstrip.man tcldocstrip {Tcl-based Docstrip Processor}] -[item modules/textutil/expander.man textutil::expander {Procedures to process templates and expand text.}] +[item modules/doctools/docidx_intro.man docidx_intro {docidx introduction}] +[item modules/doctools/docidx_lang_cmdref.man docidx_lang_cmdref {docidx language command reference}] +[item modules/doctools/docidx_lang_faq.man docidx_lang_faq {docidx language faq}] +[item modules/doctools/docidx_lang_intro.man docidx_lang_intro {docidx language introduction}] +[item modules/doctools/docidx_lang_syntax.man docidx_lang_syntax {docidx language syntax}] +[item modules/doctools/docidx_plugin_apiref.man docidx_plugin_apiref {docidx plugin API reference}] +[item modules/docstrip/docstrip.man docstrip {Docstrip style source code extraction}] +[item modules/docstrip/docstrip_util.man docstrip_util {Docstrip-related utilities}] +[item modules/doctools/doctoc_intro.man doctoc_intro {doctoc introduction}] +[item modules/doctools/doctoc_lang_cmdref.man doctoc_lang_cmdref {doctoc language command reference}] +[item modules/doctools/doctoc_lang_faq.man doctoc_lang_faq {doctoc language faq}] +[item modules/doctools/doctoc_lang_intro.man doctoc_lang_intro {doctoc language introduction}] +[item modules/doctools/doctoc_lang_syntax.man doctoc_lang_syntax {doctoc language syntax}] +[item modules/doctools/doctoc_plugin_apiref.man doctoc_plugin_apiref {doctoc plugin API reference}] +[item modules/doctools/doctools.man doctools {doctools - Processing documents}] +[item modules/doctools2idx/introduction.man doctools2idx_introduction {DocTools - Keyword indices}] +[item modules/doctools2toc/introduction.man doctools2toc_introduction {DocTools - Tables of Contents}] +[item modules/doctools/changelog.man doctools::changelog {Processing text in Emacs ChangeLog format}] +[item modules/doctools/cvs.man doctools::cvs {Processing text in 'cvs log' format}] +[item modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults {Default CSS style for HTML export plugins}] +[item modules/doctools2idx/container.man doctools::idx {Holding keyword indices}] +[item modules/doctools/docidx.man doctools::idx {docidx - Processing indices}] +[item modules/doctools2idx/export.man doctools::idx::export {Exporting keyword indices}] +[item modules/doctools2idx/import.man doctools::idx::import {Importing keyword indices}] +[item modules/doctools2idx/parse.man doctools::idx::parse {Parsing text in docidx format}] +[item modules/doctools2idx/structure.man doctools::idx::structure {Docidx serialization utilities}] +[item modules/doctools2base/tcllib_msgcat.man doctools::msgcat {Message catalog management for the various document parsers}] +[item modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c {Message catalog for the docidx parser (C)}] +[item modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de {Message catalog for the docidx parser (DE)}] +[item modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en {Message catalog for the docidx parser (EN)}] +[item modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr {Message catalog for the docidx parser (FR)}] +[item modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c {Message catalog for the doctoc parser (C)}] +[item modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de {Message catalog for the doctoc parser (DE)}] +[item modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en {Message catalog for the doctoc parser (EN)}] +[item modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr {Message catalog for the doctoc parser (FR)}] +[item modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros {Default CSS style for NROFF export plugins}] +[item modules/doctools2base/tcl_parse.man doctools::tcl::parse {Processing text in 'subst -novariables' format}] +[item modules/doctools2toc/container.man doctools::toc {Holding tables of contents}] +[item modules/doctools/doctoc.man doctools::toc {doctoc - Processing tables of contents}] +[item modules/doctools2toc/export.man doctools::toc::export {Exporting tables of contents}] +[item modules/doctools2toc/import.man doctools::toc::import {Importing keyword indices}] +[item modules/doctools2toc/parse.man doctools::toc::parse {Parsing text in doctoc format}] +[item modules/doctools2toc/structure.man doctools::toc::structure {Doctoc serialization utilities}] +[item modules/doctools/doctools_intro.man doctools_intro {doctools introduction}] +[item modules/doctools/doctools_lang_cmdref.man doctools_lang_cmdref {doctools language command reference}] +[item modules/doctools/doctools_lang_faq.man doctools_lang_faq {doctools language faq}] +[item modules/doctools/doctools_lang_intro.man doctools_lang_intro {doctools language introduction}] +[item modules/doctools/doctools_lang_syntax.man doctools_lang_syntax {doctools language syntax}] +[item modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref {doctools plugin API reference}] +[item apps/dtplite.man dtplite {Lightweight DocTools Markup Processor}] +[item modules/doctools/mpexpand.man mpexpand {Markup processor}] +[item apps/tcldocstrip.man tcldocstrip {Tcl-based Docstrip Processor}] +[item modules/textutil/expander.man textutil::expander {Procedures to process templates and expand text.}] [division_end] [division_start {File formats}] [item modules/exif/exif.man exif {Tcl EXIF extracts and parses EXIF fields from digital images}] +[item modules/gpx/gpx.man gpx {Extracts waypoints, tracks and routes from GPX files}] [item modules/jpeg/jpeg.man jpeg {JPEG querying and manipulation of meta data}] [item modules/png/png.man png {PNG querying and manipulation of meta data}] [item modules/tar/tar.man tar {Tar file creation, extraction & manipulation}] [item modules/tiff/tiff.man tiff {TIFF reading, writing, and querying and manipulation of meta data}] [division_end] [division_start {Grammars and finite automata}] +[item modules/grammar_aycock/aycock.man grammar::aycock {Aycock-Horspool-Earley parser generator for Tcl}] [item modules/grammar_fa/fa.man grammar::fa {Create and manipulate finite automatons}] [item modules/grammar_fa/dacceptor.man grammar::fa::dacceptor {Create and use deterministic acceptors}] [item modules/grammar_fa/dexec.man grammar::fa::dexec {Execute deterministic finite automatons}] [item modules/grammar_fa/faop.man grammar::fa::op {Operations on finite automatons}] [item modules/grammar_me/me_cpu.man grammar::me::cpu {Virtual machine implementation II for parsing token streams}] @@ -99,42 +165,45 @@ [item modules/des/des.man des {Implementation of the DES and triple-DES ciphers}] [item modules/md4/md4.man md4 {MD4 Message-Digest Algorithm}] [item modules/md5/md5.man md5 {MD5 Message-Digest Algorithm}] [item modules/md5crypt/md5crypt.man md5crypt {MD5-based password encryption}] [item modules/otp/otp.man otp {One-Time Passwords}] -[item modules/rc4/rc4.man rc4 {Impementation of the RC4 stream cipher}] +[item modules/pki/pki.man pki {Implementation of the public key cipher}] +[item modules/rc4/rc4.man rc4 {Implementation of the RC4 stream cipher}] [item modules/ripemd/ripemd128.man ripemd128 {RIPEMD-128 Message-Digest Algorithm}] [item modules/ripemd/ripemd160.man ripemd160 {RIPEMD-160 Message-Digest Algorithm}] [item modules/sha1/sha1.man sha1 {SHA1 Message-Digest Algorithm}] [item modules/sha1/sha256.man sha256 {SHA256 Message-Digest Algorithm}] [item modules/soundex/soundex.man soundex Soundex] [item modules/crc/sum.man sum {Calculate a sum(1) compatible checksum}] [item modules/uuid/uuid.man uuid {UUID generation and comparison}] [division_end] [division_start Mathematics] -[item modules/math/math.man math {Tcl Math Library}] -[item modules/math/bigfloat.man math::bigfloat {Arbitrary precision floating-point numbers}] -[item modules/math/bignum.man math::bignum {Arbitrary precision integer numbers}] -[item modules/math/calculus.man math::calculus {Integration and ordinary differential equations}] -[item modules/math/romberg.man math::calculus::romberg {Romberg integration}] -[item modules/math/combinatorics.man math::combinatorics {Combinatorial functions in the Tcl Math Library}] -[item modules/math/qcomplex.man math::complexnumbers {Straightforward complex number package}] -[item modules/math/constants.man math::constants {Mathematical and numerical constants}] -[item modules/math/fourier.man math::fourier {Discrete and fast fourier transforms}] -[item modules/math/fuzzy.man math::fuzzy {Fuzzy comparison of floating-point numbers}] -[item modules/math/geometry.man math::geometry {Geometrical computations}] -[item modules/math/interpolate.man math::interpolate {Interpolation routines}] -[item modules/math/linalg.man math::linearalgebra {Linear Algebra}] -[item modules/math/optimize.man math::optimize {Optimisation routines}] -[item modules/math/polynomials.man math::polynomials {Polynomial functions}] -[item modules/math/rational_funcs.man math::rationalfunctions {Polynomial functions}] -[item modules/math/roman.man math::roman {Tools for creating and manipulating roman numerals}] -[item modules/math/special.man math::special {Special mathematical functions}] -[item modules/math/statistics.man math::statistics {Basic statistical functions and procedures}] -[item modules/simulation/annealing.man simulation::annealing {Simulated annealing}] -[item modules/simulation/montecarlo.man simulation::montecarlo {Monte Carlo simulations}] -[item modules/simulation/random.man simulation::random {Pseudo-random number generators}] +[item modules/math/math.man math {Tcl Math Library}] +[item modules/math/bigfloat.man math::bigfloat {Arbitrary precision floating-point numbers}] +[item modules/math/bignum.man math::bignum {Arbitrary precision integer numbers}] +[item modules/math/calculus.man math::calculus {Integration and ordinary differential equations}] +[item modules/math/romberg.man math::calculus::romberg {Romberg integration}] +[item modules/math/combinatorics.man math::combinatorics {Combinatorial functions in the Tcl Math Library}] +[item modules/math/qcomplex.man math::complexnumbers {Straightforward complex number package}] +[item modules/math/constants.man math::constants {Mathematical and numerical constants}] +[item modules/math/decimal.man math::decimal {General decimal arithmetic}] +[item modules/math/fourier.man math::fourier {Discrete and fast fourier transforms}] +[item modules/math/fuzzy.man math::fuzzy {Fuzzy comparison of floating-point numbers}] +[item modules/math/math_geometry.man math::geometry {Geometrical computations}] +[item modules/math/interpolate.man math::interpolate {Interpolation routines}] +[item modules/math/linalg.man math::linearalgebra {Linear Algebra}] +[item modules/math/numtheory.man math::numtheory {Number Theory}] +[item modules/math/optimize.man math::optimize {Optimisation routines}] +[item modules/math/polynomials.man math::polynomials {Polynomial functions}] +[item modules/math/rational_funcs.man math::rationalfunctions {Polynomial functions}] +[item modules/math/roman.man math::roman {Tools for creating and manipulating roman numerals}] +[item modules/math/special.man math::special {Special mathematical functions}] +[item modules/math/statistics.man math::statistics {Basic statistical functions and procedures}] +[item modules/simulation/annealing.man simulation::annealing {Simulated annealing}] +[item modules/simulation/montecarlo.man simulation::montecarlo {Monte Carlo simulations}] +[item modules/simulation/simulation_random.man simulation::random {Pseudo-random number generators}] [division_end] [division_start Networking] [item modules/asn/asn.man asn {ASN.1 BER encoder/decoder}] [item modules/http/autoproxy.man autoproxy {Automatic HTTP proxy usage and authentication}] [item modules/bee/bee.man bee {BitTorrent Serialization Format Encoder/Decoder}] @@ -179,10 +248,54 @@ [item modules/page/page_util_norm_lemon.man page_util_norm_lemon {page AST normalization, LEMON}] [item modules/page/page_util_norm_peg.man page_util_norm_peg {page AST normalization, PEG}] [item modules/page/page_util_peg.man page_util_peg {page PEG transformation utilities}] [item modules/page/page_util_quote.man page_util_quote {page character quoting utilities}] [division_end] +[division_start {Parsing and Grammars}] +[item modules/pt/pt.man pt {Parser Tools Application}] +[item modules/pt/pt_astree.man pt::ast {Abstract Syntax Tree Serialization}] +[item modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl {C/PARAM, Canned configuration, Critcl}] +[item modules/pt/pt_json_language.man pt::json_language {The JSON Grammar Exchange Format}] +[item modules/pt/pt_param.man pt::param {PackRat Machine Specification}] +[item modules/pt/pt_pexpression.man pt::pe {Parsing Expression Serialization}] +[item modules/pt/pt_pexpr_op.man pt::pe::op {Parsing Expression Utilities}] +[item modules/pt/pt_pegrammar.man pt::peg {Parsing Expression Grammar Serialization}] +[item modules/pt/pt_peg_container.man pt::peg::container {PEG Storage}] +[item modules/pt/pt_peg_container_peg.man pt::peg::container::peg {PEG Storage. Canned PEG grammar specification}] +[item modules/pt/pt_peg_export.man pt::peg::export {PEG Export}] +[item modules/pt/pt_peg_export_container.man pt::peg::export::container {PEG Export Plugin. Write CONTAINER format}] +[item modules/pt/pt_peg_export_json.man pt::peg::export::json {PEG Export Plugin. Write JSON format}] +[item modules/pt/pt_peg_export_peg.man pt::peg::export::peg {PEG Export Plugin. Write PEG format}] +[item modules/pt/pt_peg_from_container.man pt::peg::from::container {PEG Conversion. From CONTAINER format}] +[item modules/pt/pt_peg_from_json.man pt::peg::from::json {PEG Conversion. Read JSON format}] +[item modules/pt/pt_peg_from_peg.man pt::peg::from::peg {PEG Conversion. Read PEG format}] +[item modules/pt/pt_peg_import.man pt::peg::import {PEG Import}] +[item modules/pt/pt_peg_import_container.man pt::peg::import::container {PEG Import Plugin. From CONTAINER format}] +[item modules/pt/pt_peg_import_json.man pt::peg::import::json {PEG Import Plugin. Read JSON format}] +[item modules/pt/pt_peg_import_peg.man pt::peg::import::peg {PEG Import Plugin. Read PEG format}] +[item modules/pt/pt_peg_interp.man pt::peg::interp {Interpreter for parsing expression grammars}] +[item modules/pt/pt_peg_to_container.man pt::peg::to::container {PEG Conversion. Write CONTAINER format}] +[item modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam {PEG Conversion. Write CPARAM format}] +[item modules/pt/pt_peg_to_json.man pt::peg::to::json {PEG Conversion. Write JSON format}] +[item modules/pt/pt_peg_to_param.man pt::peg::to::param {PEG Conversion. Write PARAM format}] +[item modules/pt/pt_peg_to_peg.man pt::peg::to::peg {PEG Conversion. Write PEG format}] +[item modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam {PEG Conversion. Write TCLPARAM format}] +[item modules/pt/pt_peg_language.man pt::peg_language {PEG Language Tutorial}] +[item modules/pt/pt_peg_introduction.man pt::pegrammar {Introduction to Parsing Expression Grammars}] +[item modules/pt/pt_pgen.man pt::pgen {Parser Generator}] +[item modules/pt/pt_rdengine.man pt::rde {Parsing Runtime Support, PARAM based}] +[item modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit {Tcl/PARAM, Canned configuration, Snit}] +[item modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo {Tcl/PARAM, Canned configuration, Tcloo}] +[item modules/pt/pt_to_api.man pt_export_api {Parser Tools Export API}] +[item modules/pt/pt_from_api.man pt_import_api {Parser Tools Import API}] +[item modules/pt/pt_introduction.man pt_introduction {Introduction to Parser Tools}] +[item modules/pt/pt_parser_api.man pt_parser_api {Parser API}] +[division_end] +[division_start {Procedures, arguments, parameters, options}] +[item modules/tepam/tepam_introduction.man tepam {An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager}] +[item modules/tepam/tepam_procedure.man tepam::procedure {TEPAM procedure, reference manual}] +[division_end] [division_start {Programming tools}] [item modules/cmdline/cmdline.man cmdline {Procedures to process command lines and options.}] [item modules/comm/comm.man comm {A remote communication facility for Tcl (8.3 and later)}] [item modules/comm/comm_wire.man comm_wire {The comm wire protocol}] [item modules/control/control.man control {Procedures for control flow structures.}] @@ -195,10 +308,11 @@ [item modules/fumagic/mimetypes.man fileutil::magic::mimetype {Procedures implementing mime-type recognition}] [item modules/fumagic/rtcore.man fileutil::magic::rt {Runtime core for file type recognition engines written in pure Tcl}] [item modules/fileutil/multi.man fileutil::multi {Multi-file operation, scatter/gather, standard object}] [item modules/fileutil/multiop.man fileutil::multi::op {Multi-file operation, scatter/gather}] [item modules/fileutil/traverse.man fileutil_traverse {Iterative directory traversal}] +[item modules/hook/hook.man hook Hooks] [item modules/interp/tcllib_interp.man interp {Interp creation and aliasing}] [item modules/log/log.man log {Procedures to log messages of libraries and applications.}] [item modules/log/logger.man logger {System to control logging of events.}] [item modules/log/loggerAppender.man logger::appender {Collection of predefined appenders for logger}] [item modules/log/loggerUtils.man logger::utils {Utilities for logger}] @@ -225,16 +339,37 @@ [item modules/term/ipager.man term::interact::pager {Terminal widget, paging}] [item modules/term/receive.man term::receive {General input from terminals}] [item modules/term/term_bind.man term::receive::bind {Keyboard dispatch from terminals}] [item modules/term/term_send.man term::send {General output to terminals}] [division_end] +[division_start {Text formatter plugin}] +[item modules/doctools2idx/export_docidx.man doctools::idx::export::docidx {docidx export plugin}] +[item modules/doctools2idx/export_html.man doctools::idx::export::html {HTML export plugin}] +[item modules/doctools2idx/export_json.man doctools::idx::export::json {JSON export plugin}] +[item modules/doctools2idx/export_nroff.man doctools::idx::export::nroff {nroff export plugin}] +[item modules/doctools2idx/export_text.man doctools::idx::export::text {plain text export plugin}] +[item modules/doctools2idx/export_wiki.man doctools::idx::export::wiki {wiki export plugin}] +[item modules/doctools2idx/import_docidx.man doctools::idx::import::docidx {docidx import plugin}] +[item modules/doctools2idx/import_json.man doctools::idx::import::json {JSON import plugin}] +[item modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc {doctoc export plugin}] +[item modules/doctools2toc/export_html.man doctools::toc::export::html {HTML export plugin}] +[item modules/doctools2toc/export_json.man doctools::toc::export::json {JSON export plugin}] +[item modules/doctools2toc/export_nroff.man doctools::toc::export::nroff {nroff export plugin}] +[item modules/doctools2toc/export_text.man doctools::toc::export::text {plain text export plugin}] +[item modules/doctools2toc/export_wiki.man doctools::toc::export::wiki {wiki export plugin}] +[item modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc {doctoc import plugin}] +[item modules/doctools2toc/import_json.man doctools::toc::import::json {JSON import plugin}] +[division_end] [division_start {Text processing}] +[item modules/base64/ascii85.man ascii85 {ascii85-encode/decode binary data}] [item modules/base32/base32.man base32 {base32 standard encoding}] [item modules/base32/base32core.man base32::core {Expanding basic base32 maps}] [item modules/base32/base32hex.man base32::hex {base32 extended hex encoding}] [item modules/base64/base64.man base64 {base64-encode/decode binary data}] [item modules/bibtex/bibtex.man bibtex {Parse bibtex files}] +[item modules/clock/iso8601.man clock_iso8601 {Parsing ISO 8601 dates/times}] +[item modules/clock/rfc2822.man clock_rfc2822 {Parsing ISO 8601 dates/times}] [item modules/csv/csv.man csv {Procedures to handle CSV data.}] [item modules/htmlparse/htmlparse.man htmlparse {Procedures to parse HTML strings}] [item modules/inifile/ini.man inifile {Parsing of Windows INI files}] [item modules/mime/mime.man mime {Manipulation of MIME body parts}] [item modules/rcs/rcs.man rcs {RCS low level utilities}] @@ -257,23 +392,50 @@ [item modules/transfer/dsource.man transfer::data::source {Data source}] [item modules/transfer/receiver.man transfer::receiver {Data source}] [item modules/transfer/transmitter.man transfer::transmitter {Data source}] [division_end] [division_start Unfiled] -[item modules/cache/async.man cache::async {Asynchronous in-memory cache}] -[item modules/yaml/huddle.man huddle {Create and manipulate huddle object}] -[item modules/map/map_slippy.man map::slippy {Common code for slippy based map packages}] -[item modules/map/map_slippy_cache.man map::slippy::cache {Management of a tile cache in the local filesystem}] -[item modules/map/map_slippy_fetcher.man map::slippy::fetcher {Accessing a server providing tiles for slippy-based maps}] -[item modules/mapproj/mapproj.man mapproj {Map projection routines}] -[item modules/stringprep/stringprep.man stringprep {Implementation of stringprep}] -[item modules/stringprep/stringprep_data.man stringprep::data {stringprep data tables, generated, internal}] -[item modules/uev/uevent_onidle.man uevent::onidle {Request merging and deferal to idle time}] -[item modules/stringprep/unicode.man unicode {Implementation of Unicode normalization}] -[item modules/stringprep/unicode_data.man unicode::data {unicode data tables, generated, internal}] -[item modules/units/units.man units {unit conversion}] -[item modules/yaml/yaml.man yaml {YAML Format Encoder/Decoder}] +[item modules/cache/async.man cache::async {Asynchronous in-memory cache}] +[item modules/generator/generator.man generator {Procedures for creating and using generators.}] +[item modules/yaml/huddle.man huddle {Create and manipulate huddle object}] +[item modules/imap4/imap4.man imap4 {imap client-side tcl implementation of imap protocol}] +[item modules/map/map_geocode_nominatim.man map::geocode::nominatim {Resolving geographical names with a Nominatim service}] +[item modules/map/map_slippy.man map::slippy {Common code for slippy based map packages}] +[item modules/map/map_slippy_cache.man map::slippy::cache {Management of a tile cache in the local filesystem}] +[item modules/map/map_slippy_fetcher.man map::slippy::fetcher {Accessing a server providing tiles for slippy-based maps}] +[item modules/mapproj/mapproj.man mapproj {Map projection routines}] +[item modules/math/symdiff.man math::calculus::symdiff {Symbolic differentiation for Tcl}] +[item modules/namespacex/namespacex.man namespacex {Namespace utility commands}] +[item modules/rest/rest.man rest {define REST web APIs and call them inline or asychronously}] +[item modules/stringprep/stringprep.man stringprep {Implementation of stringprep}] +[item modules/stringprep/stringprep_data.man stringprep::data {stringprep data tables, generated, internal}] +[item modules/math/machineparameters.man tclrep/machineparameters {Compute double precision machine parameters.}] +[item modules/uev/uevent_onidle.man uevent::onidle {Request merging and deferal to idle time}] +[item modules/stringprep/unicode.man unicode {Implementation of Unicode normalization}] +[item modules/stringprep/unicode_data.man unicode::data {unicode data tables, generated, internal}] +[item modules/units/units.man units {unit conversion}] +[item modules/yaml/yaml.man yaml {YAML Format Encoder/Decoder}] +[division_end] +[division_start Utility] +[item modules/lambda/lambda.man lambda {Utility commands for anonymous procedures}] +[item modules/ooutil/ooutil.man oo::util {Utility commands for TclOO}] +[item modules/try/tcllib_try.man try {try - Trap and process errors and exceptions}] +[division_end] +[division_start {Validation, Type checking}] +[item modules/valtype/valtype_common.man valtype::common {Validation, common code}] +[item modules/valtype/cc_amex.man valtype::creditcard::amex {Validation for AMEX creditcard number}] +[item modules/valtype/cc_discover.man valtype::creditcard::discover {Validation for Discover creditcard number}] +[item modules/valtype/cc_mastercard.man valtype::creditcard::mastercard {Validation for Mastercard creditcard number}] +[item modules/valtype/cc_visa.man valtype::creditcard::visa {Validation for VISA creditcard number}] +[item modules/valtype/ean13.man valtype::gs1::ean13 {Validation for EAN13}] +[item modules/valtype/iban.man valtype::iban {Validation for IBAN}] +[item modules/valtype/imei.man valtype::imei {Validation for IMEI}] +[item modules/valtype/isbn.man valtype::isbn {Validation for ISBN}] +[item modules/valtype/luhn.man valtype::luhn {Validation for plain number with a LUHN checkdigit}] +[item modules/valtype/luhn5.man valtype::luhn5 {Validation for plain number with a LUHN5 checkdigit}] +[item modules/valtype/usnpi.man valtype::usnpi {Validation for USNPI}] +[item modules/valtype/verhoeff.man valtype::verhoeff {Validation for plain number with a VERHOEFF checkdigit}] [division_end] [division_end] [division_start {By Type}] [division_start Applications] [item apps/dtplite.man dtplite {Lightweight DocTools Markup Processor}] @@ -298,10 +460,11 @@ [item modules/base32/base32.man base32 {base32 standard encoding}] [item modules/base32/base32core.man base32::core {Expanding basic base32 maps}] [item modules/base32/base32hex.man base32::hex {base32 extended hex encoding}] [division_end] [division_start base64] +[item modules/base64/ascii85.man ascii85 {ascii85-encode/decode binary data}] [item modules/base64/base64.man base64 {base64-encode/decode binary data}] [item modules/base64/uuencode.man uuencode {UU-encode/decode binary data}] [item modules/base64/yencode.man yencode {Y-encode/decode binary data}] [division_end] [division_start bee] @@ -323,10 +486,14 @@ [item modules/blowfish/blowfish.man blowfish {Implementation of the Blowfish block cipher}] [division_end] [division_start cache] [item modules/cache/async.man cache::async {Asynchronous in-memory cache}] [division_end] +[division_start clock] +[item modules/clock/iso8601.man clock_iso8601 {Parsing ISO 8601 dates/times}] +[item modules/clock/rfc2822.man clock_rfc2822 {Parsing ISO 8601 dates/times}] +[division_end] [division_start cmdline] [item modules/cmdline/cmdline.man cmdline {Procedures to process command lines and options.}] [division_end] [division_start comm] [item modules/comm/comm.man comm {A remote communication facility for Tcl (8.3 and later)}] @@ -333,10 +500,14 @@ [item modules/comm/comm_wire.man comm_wire {The comm wire protocol}] [division_end] [division_start control] [item modules/control/control.man control {Procedures for control flow structures.}] [division_end] +[division_start coroutine] +[item modules/coroutine/coroutine.man coroutine {Coroutine based event and IO handling}] +[item modules/coroutine/coro_auto.man coroutine::auto {Automatic event and IO coroutine awareness}] +[division_end] [division_start counter] [item modules/counter/counter.man counter {Procedures for counters and histograms}] [division_end] [division_start crc] [item modules/crc/cksum.man cksum {Calculate a cksum(1) compatible checksum}] @@ -382,10 +553,56 @@ [item modules/doctools/doctools_lang_intro.man doctools_lang_intro {doctools language introduction}] [item modules/doctools/doctools_lang_syntax.man doctools_lang_syntax {doctools language syntax}] [item modules/doctools/doctools_plugin_apiref.man doctools_plugin_apiref {doctools plugin API reference}] [item modules/doctools/mpexpand.man mpexpand {Markup processor}] [division_end] +[division_start doctools2base] +[item modules/doctools2base/html_cssdefaults.man doctools::html::cssdefaults {Default CSS style for HTML export plugins}] +[item modules/doctools2base/tcllib_msgcat.man doctools::msgcat {Message catalog management for the various document parsers}] +[item modules/doctools2base/nroff_manmacros.man doctools::nroff::man_macros {Default CSS style for NROFF export plugins}] +[item modules/doctools2base/tcl_parse.man doctools::tcl::parse {Processing text in 'subst -novariables' format}] +[division_end] +[division_start doctools2idx] +[item modules/doctools2idx/introduction.man doctools2idx_introduction {DocTools - Keyword indices}] +[item modules/doctools2idx/container.man doctools::idx {Holding keyword indices}] +[item modules/doctools2idx/export.man doctools::idx::export {Exporting keyword indices}] +[item modules/doctools2idx/export_docidx.man doctools::idx::export::docidx {docidx export plugin}] +[item modules/doctools2idx/export_html.man doctools::idx::export::html {HTML export plugin}] +[item modules/doctools2idx/export_json.man doctools::idx::export::json {JSON export plugin}] +[item modules/doctools2idx/export_nroff.man doctools::idx::export::nroff {nroff export plugin}] +[item modules/doctools2idx/export_text.man doctools::idx::export::text {plain text export plugin}] +[item modules/doctools2idx/export_wiki.man doctools::idx::export::wiki {wiki export plugin}] +[item modules/doctools2idx/import.man doctools::idx::import {Importing keyword indices}] +[item modules/doctools2idx/import_docidx.man doctools::idx::import::docidx {docidx import plugin}] +[item modules/doctools2idx/import_json.man doctools::idx::import::json {JSON import plugin}] +[item modules/doctools2idx/parse.man doctools::idx::parse {Parsing text in docidx format}] +[item modules/doctools2idx/structure.man doctools::idx::structure {Docidx serialization utilities}] +[item modules/doctools2idx/msgcat_c.man doctools::msgcat::idx::c {Message catalog for the docidx parser (C)}] +[item modules/doctools2idx/msgcat_de.man doctools::msgcat::idx::de {Message catalog for the docidx parser (DE)}] +[item modules/doctools2idx/msgcat_en.man doctools::msgcat::idx::en {Message catalog for the docidx parser (EN)}] +[item modules/doctools2idx/msgcat_fr.man doctools::msgcat::idx::fr {Message catalog for the docidx parser (FR)}] +[division_end] +[division_start doctools2toc] +[item modules/doctools2toc/introduction.man doctools2toc_introduction {DocTools - Tables of Contents}] +[item modules/doctools2toc/msgcat_c.man doctools::msgcat::toc::c {Message catalog for the doctoc parser (C)}] +[item modules/doctools2toc/msgcat_de.man doctools::msgcat::toc::de {Message catalog for the doctoc parser (DE)}] +[item modules/doctools2toc/msgcat_en.man doctools::msgcat::toc::en {Message catalog for the doctoc parser (EN)}] +[item modules/doctools2toc/msgcat_fr.man doctools::msgcat::toc::fr {Message catalog for the doctoc parser (FR)}] +[item modules/doctools2toc/container.man doctools::toc {Holding tables of contents}] +[item modules/doctools2toc/export.man doctools::toc::export {Exporting tables of contents}] +[item modules/doctools2toc/export_doctoc.man doctools::toc::export::doctoc {doctoc export plugin}] +[item modules/doctools2toc/export_html.man doctools::toc::export::html {HTML export plugin}] +[item modules/doctools2toc/export_json.man doctools::toc::export::json {JSON export plugin}] +[item modules/doctools2toc/export_nroff.man doctools::toc::export::nroff {nroff export plugin}] +[item modules/doctools2toc/export_text.man doctools::toc::export::text {plain text export plugin}] +[item modules/doctools2toc/export_wiki.man doctools::toc::export::wiki {wiki export plugin}] +[item modules/doctools2toc/import.man doctools::toc::import {Importing keyword indices}] +[item modules/doctools2toc/import_doctoc.man doctools::toc::import::doctoc {doctoc import plugin}] +[item modules/doctools2toc/import_json.man doctools::toc::import::json {JSON import plugin}] +[item modules/doctools2toc/parse.man doctools::toc::parse {Parsing text in doctoc format}] +[item modules/doctools2toc/structure.man doctools::toc::structure {Doctoc serialization utilities}] +[division_end] [division_start exif] [item modules/exif/exif.man exif {Tcl EXIF extracts and parses EXIF fields from digital images}] [division_end] [division_start fileutil] [item modules/fileutil/fileutil.man fileutil {Procedures implementing some file utilities}] @@ -405,10 +622,19 @@ [item modules/fumagic/cgen.man fileutil::magic::cgen {Generator core for compiler of magic(5) files}] [item modules/fumagic/filetypes.man fileutil::magic::filetype {Procedures implementing file-type recognition}] [item modules/fumagic/mimetypes.man fileutil::magic::mimetype {Procedures implementing mime-type recognition}] [item modules/fumagic/rtcore.man fileutil::magic::rt {Runtime core for file type recognition engines written in pure Tcl}] [division_end] +[division_start generator] +[item modules/generator/generator.man generator {Procedures for creating and using generators.}] +[division_end] +[division_start gpx] +[item modules/gpx/gpx.man gpx {Extracts waypoints, tracks and routes from GPX files}] +[division_end] +[division_start grammar_aycock] +[item modules/grammar_aycock/aycock.man grammar::aycock {Aycock-Horspool-Earley parser generator for Tcl}] +[division_end] [division_start grammar_fa] [item modules/grammar_fa/fa.man grammar::fa {Create and manipulate finite automatons}] [item modules/grammar_fa/dacceptor.man grammar::fa::dacceptor {Create and use deterministic acceptors}] [item modules/grammar_fa/dexec.man grammar::fa::dexec {Execute deterministic finite automatons}] [item modules/grammar_fa/faop.man grammar::fa::op {Operations on finite automatons}] @@ -425,10 +651,13 @@ [division_end] [division_start grammar_peg] [item modules/grammar_peg/peg.man grammar::peg {Create and manipulate parsing expression grammars}] [item modules/grammar_peg/peg_interp.man grammar::peg::interp {Interpreter for parsing expression grammars}] [division_end] +[division_start hook] +[item modules/hook/hook.man hook Hooks] +[division_end] [division_start html] [item modules/html/html.man html {Procedures to generate HTML structures}] [division_end] [division_start htmlparse] [item modules/htmlparse/htmlparse.man htmlparse {Procedures to parse HTML strings}] @@ -437,10 +666,13 @@ [item modules/http/autoproxy.man autoproxy {Automatic HTTP proxy usage and authentication}] [division_end] [division_start ident] [item modules/ident/ident.man ident {Ident protocol client}] [division_end] +[division_start imap4] +[item modules/imap4/imap4.man imap4 {imap client-side tcl implementation of imap protocol}] +[division_end] [division_start inifile] [item modules/inifile/ini.man inifile {Parsing of Windows INI files}] [division_end] [division_start interp] [item modules/interp/deleg_method.man deleg_method {Creation of comm delegates (snit methods)}] @@ -456,11 +688,15 @@ [division_end] [division_start jpeg] [item modules/jpeg/jpeg.man jpeg {JPEG querying and manipulation of meta data}] [division_end] [division_start json] -[item modules/json/json.man json {JSON parser}] +[item modules/json/json.man json {JSON parser}] +[item modules/json/json_write.man json::write {JSON generation}] +[division_end] +[division_start lambda] +[item modules/lambda/lambda.man lambda {Utility commands for anonymous procedures}] [division_end] [division_start ldap] [item modules/ldap/ldap.man ldap {LDAP client}] [item modules/ldap/ldapx.man ldapx {LDAP extended object interface}] [division_end] @@ -469,37 +705,42 @@ [item modules/log/logger.man logger {System to control logging of events.}] [item modules/log/loggerAppender.man logger::appender {Collection of predefined appenders for logger}] [item modules/log/loggerUtils.man logger::utils {Utilities for logger}] [division_end] [division_start map] -[item modules/map/map_slippy.man map::slippy {Common code for slippy based map packages}] -[item modules/map/map_slippy_cache.man map::slippy::cache {Management of a tile cache in the local filesystem}] -[item modules/map/map_slippy_fetcher.man map::slippy::fetcher {Accessing a server providing tiles for slippy-based maps}] +[item modules/map/map_geocode_nominatim.man map::geocode::nominatim {Resolving geographical names with a Nominatim service}] +[item modules/map/map_slippy.man map::slippy {Common code for slippy based map packages}] +[item modules/map/map_slippy_cache.man map::slippy::cache {Management of a tile cache in the local filesystem}] +[item modules/map/map_slippy_fetcher.man map::slippy::fetcher {Accessing a server providing tiles for slippy-based maps}] [division_end] [division_start mapproj] [item modules/mapproj/mapproj.man mapproj {Map projection routines}] [division_end] [division_start math] -[item modules/math/math.man math {Tcl Math Library}] -[item modules/math/bigfloat.man math::bigfloat {Arbitrary precision floating-point numbers}] -[item modules/math/bignum.man math::bignum {Arbitrary precision integer numbers}] -[item modules/math/calculus.man math::calculus {Integration and ordinary differential equations}] -[item modules/math/romberg.man math::calculus::romberg {Romberg integration}] -[item modules/math/combinatorics.man math::combinatorics {Combinatorial functions in the Tcl Math Library}] -[item modules/math/qcomplex.man math::complexnumbers {Straightforward complex number package}] -[item modules/math/constants.man math::constants {Mathematical and numerical constants}] -[item modules/math/fourier.man math::fourier {Discrete and fast fourier transforms}] -[item modules/math/fuzzy.man math::fuzzy {Fuzzy comparison of floating-point numbers}] -[item modules/math/geometry.man math::geometry {Geometrical computations}] -[item modules/math/interpolate.man math::interpolate {Interpolation routines}] -[item modules/math/linalg.man math::linearalgebra {Linear Algebra}] -[item modules/math/optimize.man math::optimize {Optimisation routines}] -[item modules/math/polynomials.man math::polynomials {Polynomial functions}] -[item modules/math/rational_funcs.man math::rationalfunctions {Polynomial functions}] -[item modules/math/roman.man math::roman {Tools for creating and manipulating roman numerals}] -[item modules/math/special.man math::special {Special mathematical functions}] -[item modules/math/statistics.man math::statistics {Basic statistical functions and procedures}] +[item modules/math/math.man math {Tcl Math Library}] +[item modules/math/bigfloat.man math::bigfloat {Arbitrary precision floating-point numbers}] +[item modules/math/bignum.man math::bignum {Arbitrary precision integer numbers}] +[item modules/math/calculus.man math::calculus {Integration and ordinary differential equations}] +[item modules/math/romberg.man math::calculus::romberg {Romberg integration}] +[item modules/math/symdiff.man math::calculus::symdiff {Symbolic differentiation for Tcl}] +[item modules/math/combinatorics.man math::combinatorics {Combinatorial functions in the Tcl Math Library}] +[item modules/math/qcomplex.man math::complexnumbers {Straightforward complex number package}] +[item modules/math/constants.man math::constants {Mathematical and numerical constants}] +[item modules/math/decimal.man math::decimal {General decimal arithmetic}] +[item modules/math/fourier.man math::fourier {Discrete and fast fourier transforms}] +[item modules/math/fuzzy.man math::fuzzy {Fuzzy comparison of floating-point numbers}] +[item modules/math/math_geometry.man math::geometry {Geometrical computations}] +[item modules/math/interpolate.man math::interpolate {Interpolation routines}] +[item modules/math/linalg.man math::linearalgebra {Linear Algebra}] +[item modules/math/numtheory.man math::numtheory {Number Theory}] +[item modules/math/optimize.man math::optimize {Optimisation routines}] +[item modules/math/polynomials.man math::polynomials {Polynomial functions}] +[item modules/math/rational_funcs.man math::rationalfunctions {Polynomial functions}] +[item modules/math/roman.man math::roman {Tools for creating and manipulating roman numerals}] +[item modules/math/special.man math::special {Special mathematical functions}] +[item modules/math/statistics.man math::statistics {Basic statistical functions and procedures}] +[item modules/math/machineparameters.man tclrep/machineparameters {Compute double precision machine parameters.}] [division_end] [division_start md4] [item modules/md4/md4.man md4 {MD4 Message-Digest Algorithm}] [division_end] [division_start md5] @@ -513,10 +754,13 @@ [item modules/mime/smtp.man smtp {Client-side tcl implementation of the smtp protocol}] [division_end] [division_start multiplexer] [item modules/multiplexer/multiplexer.man multiplexer {One-to-many communication with sockets.}] [division_end] +[division_start namespacex] +[item modules/namespacex/namespacex.man namespacex {Namespace utility commands}] +[division_end] [division_start ncgi] [item modules/ncgi/ncgi.man ncgi {Procedures to manipulate CGI values.}] [division_end] [division_start nmea] [item modules/nmea/nmea.man nmea {Process NMEA data}] @@ -533,10 +777,13 @@ [item modules/nntp/nntp.man nntp {Tcl client for the NNTP protocol}] [division_end] [division_start ntp] [item modules/ntp/ntp_time.man ntp_time {Tcl Time Service Client}] [division_end] +[division_start ooutil] +[item modules/ooutil/ooutil.man oo::util {Utility commands for TclOO}] +[division_end] [division_start otp] [item modules/otp/otp.man otp {One-Time Passwords}] [division_end] [division_start page] [item modules/page/page_intro.man page_intro {page introduction}] @@ -545,10 +792,13 @@ [item modules/page/page_util_norm_lemon.man page_util_norm_lemon {page AST normalization, LEMON}] [item modules/page/page_util_norm_peg.man page_util_norm_peg {page AST normalization, PEG}] [item modules/page/page_util_peg.man page_util_peg {page PEG transformation utilities}] [item modules/page/page_util_quote.man page_util_quote {page character quoting utilities}] [division_end] +[division_start pki] +[item modules/pki/pki.man pki {Implementation of the public key cipher}] +[division_end] [division_start pluginmgr] [item modules/pluginmgr/pluginmgr.man pluginmgr {Manage a plugin}] [division_end] [division_start png] [item modules/png/png.man png {PNG querying and manipulation of meta data}] @@ -562,19 +812,62 @@ [item modules/pop3d/pop3d_udb.man pop3d::udb {Simple user database for pop3d}] [division_end] [division_start profiler] [item modules/profiler/profiler.man profiler {Tcl source code profiler}] [division_end] +[division_start pt] +[item modules/pt/pt.man pt {Parser Tools Application}] +[item modules/pt/pt_astree.man pt::ast {Abstract Syntax Tree Serialization}] +[item modules/pt/pt_cparam_config_critcl.man pt::cparam::configuration::critcl {C/PARAM, Canned configuration, Critcl}] +[item modules/pt/pt_json_language.man pt::json_language {The JSON Grammar Exchange Format}] +[item modules/pt/pt_param.man pt::param {PackRat Machine Specification}] +[item modules/pt/pt_pexpression.man pt::pe {Parsing Expression Serialization}] +[item modules/pt/pt_pexpr_op.man pt::pe::op {Parsing Expression Utilities}] +[item modules/pt/pt_pegrammar.man pt::peg {Parsing Expression Grammar Serialization}] +[item modules/pt/pt_peg_container.man pt::peg::container {PEG Storage}] +[item modules/pt/pt_peg_container_peg.man pt::peg::container::peg {PEG Storage. Canned PEG grammar specification}] +[item modules/pt/pt_peg_export.man pt::peg::export {PEG Export}] +[item modules/pt/pt_peg_export_container.man pt::peg::export::container {PEG Export Plugin. Write CONTAINER format}] +[item modules/pt/pt_peg_export_json.man pt::peg::export::json {PEG Export Plugin. Write JSON format}] +[item modules/pt/pt_peg_export_peg.man pt::peg::export::peg {PEG Export Plugin. Write PEG format}] +[item modules/pt/pt_peg_from_container.man pt::peg::from::container {PEG Conversion. From CONTAINER format}] +[item modules/pt/pt_peg_from_json.man pt::peg::from::json {PEG Conversion. Read JSON format}] +[item modules/pt/pt_peg_from_peg.man pt::peg::from::peg {PEG Conversion. Read PEG format}] +[item modules/pt/pt_peg_import.man pt::peg::import {PEG Import}] +[item modules/pt/pt_peg_import_container.man pt::peg::import::container {PEG Import Plugin. From CONTAINER format}] +[item modules/pt/pt_peg_import_json.man pt::peg::import::json {PEG Import Plugin. Read JSON format}] +[item modules/pt/pt_peg_import_peg.man pt::peg::import::peg {PEG Import Plugin. Read PEG format}] +[item modules/pt/pt_peg_interp.man pt::peg::interp {Interpreter for parsing expression grammars}] +[item modules/pt/pt_peg_to_container.man pt::peg::to::container {PEG Conversion. Write CONTAINER format}] +[item modules/pt/pt_peg_to_cparam.man pt::peg::to::cparam {PEG Conversion. Write CPARAM format}] +[item modules/pt/pt_peg_to_json.man pt::peg::to::json {PEG Conversion. Write JSON format}] +[item modules/pt/pt_peg_to_param.man pt::peg::to::param {PEG Conversion. Write PARAM format}] +[item modules/pt/pt_peg_to_peg.man pt::peg::to::peg {PEG Conversion. Write PEG format}] +[item modules/pt/pt_peg_to_tclparam.man pt::peg::to::tclparam {PEG Conversion. Write TCLPARAM format}] +[item modules/pt/pt_peg_language.man pt::peg_language {PEG Language Tutorial}] +[item modules/pt/pt_peg_introduction.man pt::pegrammar {Introduction to Parsing Expression Grammars}] +[item modules/pt/pt_pgen.man pt::pgen {Parser Generator}] +[item modules/pt/pt_rdengine.man pt::rde {Parsing Runtime Support, PARAM based}] +[item modules/pt/pt_tclparam_config_snit.man pt::tclparam::configuration::snit {Tcl/PARAM, Canned configuration, Snit}] +[item modules/pt/pt_tclparam_config_tcloo.man pt::tclparam::configuration::tcloo {Tcl/PARAM, Canned configuration, Tcloo}] +[item modules/pt/pt_to_api.man pt_export_api {Parser Tools Export API}] +[item modules/pt/pt_from_api.man pt_import_api {Parser Tools Import API}] +[item modules/pt/pt_introduction.man pt_introduction {Introduction to Parser Tools}] +[item modules/pt/pt_parser_api.man pt_parser_api {Parser API}] +[division_end] [division_start rc4] -[item modules/rc4/rc4.man rc4 {Impementation of the RC4 stream cipher}] +[item modules/rc4/rc4.man rc4 {Implementation of the RC4 stream cipher}] [division_end] [division_start rcs] [item modules/rcs/rcs.man rcs {RCS low level utilities}] [division_end] [division_start report] [item modules/report/report.man report {Create and manipulate report objects}] [division_end] +[division_start rest] +[item modules/rest/rest.man rest {define REST web APIs and call them inline or asychronously}] +[division_end] [division_start ripemd] [item modules/ripemd/ripemd128.man ripemd128 {RIPEMD-128 Message-Digest Algorithm}] [item modules/ripemd/ripemd160.man ripemd160 {RIPEMD-160 Message-Digest Algorithm}] [division_end] [division_start sasl] @@ -583,13 +876,13 @@ [division_start sha1] [item modules/sha1/sha1.man sha1 {SHA1 Message-Digest Algorithm}] [item modules/sha1/sha256.man sha256 {SHA256 Message-Digest Algorithm}] [division_end] [division_start simulation] -[item modules/simulation/annealing.man simulation::annealing {Simulated annealing}] -[item modules/simulation/montecarlo.man simulation::montecarlo {Monte Carlo simulations}] -[item modules/simulation/random.man simulation::random {Pseudo-random number generators}] +[item modules/simulation/annealing.man simulation::annealing {Simulated annealing}] +[item modules/simulation/montecarlo.man simulation::montecarlo {Monte Carlo simulations}] +[item modules/simulation/simulation_random.man simulation::random {Pseudo-random number generators}] [division_end] [division_start smtpd] [item modules/smtpd/smtpd.man smtpd {Tcl SMTP server implementation}] [division_end] [division_start snit] @@ -609,28 +902,33 @@ [item modules/stringprep/unicode_data.man unicode::data {unicode data tables, generated, internal}] [division_end] [division_start struct] [item modules/struct/disjointset.man struct::disjointset {Disjoint set data structure}] [item modules/struct/graph.man struct::graph {Create and manipulate directed graph objects}] -[item modules/struct/graph1.man {struct::graph v1} {Create and manipulate directed graph objects}] [item modules/struct/graphops.man struct::graph::op {Operation for (un)directed graph objects}] +[item modules/struct/graph1.man struct::graph_v1 {Create and manipulate directed graph objects}] [item modules/struct/struct_list.man struct::list {Procedures for manipulating lists}] [item modules/struct/matrix.man struct::matrix {Create and manipulate matrix objects}] -[item modules/struct/matrix1.man {struct::matrix v1} {Create and manipulate matrix objects}] +[item modules/struct/matrix1.man struct::matrix_v1 {Create and manipulate matrix objects}] [item modules/struct/pool.man struct::pool {Create and manipulate pool objects (of discrete items)}] [item modules/struct/prioqueue.man struct::prioqueue {Create and manipulate prioqueue objects}] [item modules/struct/queue.man struct::queue {Create and manipulate queue objects}] [item modules/struct/record.man struct::record {Define and create records (similar to 'C' structures)}] [item modules/struct/struct_set.man struct::set {Procedures for manipulating sets}] [item modules/struct/skiplist.man struct::skiplist {Create and manipulate skiplists}] [item modules/struct/stack.man struct::stack {Create and manipulate stack objects}] [item modules/struct/struct_tree.man struct::tree {Create and manipulate tree objects}] -[item modules/struct/struct_tree1.man {struct::tree v1} {Create and manipulate tree objects}] +[item modules/struct/struct_tree1.man struct::tree_v1 {Create and manipulate tree objects}] [division_end] [division_start tar] [item modules/tar/tar.man tar {Tar file creation, extraction & manipulation}] [division_end] +[division_start tepam] +[item modules/tepam/tepam_introduction.man tepam {An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager}] +[item modules/tepam/tepam_argument_dialogbox.man tepam::argument_dialogbox {TEPAM argument_dialogbox, reference manual}] +[item modules/tepam/tepam_procedure.man tepam::procedure {TEPAM procedure, reference manual}] +[division_end] [division_start term] [item modules/term/term.man term {General terminal control}] [item modules/term/ansi_code.man term::ansi::code {Helper for control sequences}] [item modules/term/ansi_cattr.man term::ansi::code::attr {ANSI attribute sequences}] [item modules/term/ansi_cctrl.man term::ansi::code::ctrl {ANSI control sequences}] @@ -670,10 +968,13 @@ [item modules/transfer/transmitter.man transfer::transmitter {Data source}] [division_end] [division_start treeql] [item modules/treeql/treeql.man treeql {Query tree objects}] [division_end] +[division_start try] +[item modules/try/tcllib_try.man try {try - Trap and process errors and exceptions}] +[division_end] [division_start uev] [item modules/uev/uevent.man uevent {User events}] [item modules/uev/uevent_onidle.man uevent::onidle {Request merging and deferal to idle time}] [division_end] [division_start units] @@ -684,10 +985,61 @@ [item modules/uri/urn-scheme.man uri_urn {URI utilities, URN scheme}] [division_end] [division_start uuid] [item modules/uuid/uuid.man uuid {UUID generation and comparison}] [division_end] +[division_start valtype] +[item modules/valtype/valtype_common.man valtype::common {Validation, common code}] +[item modules/valtype/cc_amex.man valtype::creditcard::amex {Validation for AMEX creditcard number}] +[item modules/valtype/cc_discover.man valtype::creditcard::discover {Validation for Discover creditcard number}] +[item modules/valtype/cc_mastercard.man valtype::creditcard::mastercard {Validation for Mastercard creditcard number}] +[item modules/valtype/cc_visa.man valtype::creditcard::visa {Validation for VISA creditcard number}] +[item modules/valtype/ean13.man valtype::gs1::ean13 {Validation for EAN13}] +[item modules/valtype/iban.man valtype::iban {Validation for IBAN}] +[item modules/valtype/imei.man valtype::imei {Validation for IMEI}] +[item modules/valtype/isbn.man valtype::isbn {Validation for ISBN}] +[item modules/valtype/luhn.man valtype::luhn {Validation for plain number with a LUHN checkdigit}] +[item modules/valtype/luhn5.man valtype::luhn5 {Validation for plain number with a LUHN5 checkdigit}] +[item modules/valtype/usnpi.man valtype::usnpi {Validation for USNPI}] +[item modules/valtype/verhoeff.man valtype::verhoeff {Validation for plain number with a VERHOEFF checkdigit}] +[division_end] +[division_start virtchannel_base] +[item modules/virtchannel_base/cat.man tcl::chan::cat {Concatenation channel}] +[item modules/virtchannel_base/facade.man tcl::chan::facade {Facade channel}] +[item modules/virtchannel_base/fifo.man tcl::chan::fifo {In-memory fifo channel}] +[item modules/virtchannel_base/fifo2.man tcl::chan::fifo2 {In-memory interconnected fifo channels}] +[item modules/virtchannel_base/halfpipe.man tcl::chan::halfpipe {In-memory channel, half of a fifo2}] +[item modules/virtchannel_base/memchan.man tcl::chan::memchan {In-memory channel}] +[item modules/virtchannel_base/null.man tcl::chan::null {Null channel}] +[item modules/virtchannel_base/nullzero.man tcl::chan::nullzero {Null/Zero channel combination}] +[item modules/virtchannel_base/random.man tcl::chan::random {Random channel}] +[item modules/virtchannel_base/randseed.man tcl::chan::randseed {Utilities for random channels}] +[item modules/virtchannel_base/std.man tcl::chan::std {Standard I/O, unification of stdin and stdout}] +[item modules/virtchannel_base/string.man tcl::chan::string {Read-only in-memory channel}] +[item modules/virtchannel_base/textwindow.man tcl::chan::textwindow {Textwindow channel}] +[item modules/virtchannel_base/variable.man tcl::chan::variable {In-memory channel using variable for storage}] +[item modules/virtchannel_base/zero.man tcl::chan::zero {Zero channel}] +[division_end] +[division_start virtchannel_core] +[item modules/virtchannel_core/core.man tcl::chan::core {Basic reflected/virtual channel support}] +[item modules/virtchannel_core/events.man tcl::chan::events {Event support for reflected/virtual channels}] +[item modules/virtchannel_core/transformcore.man tcl::transform::core {Basic reflected/virtual channel transform support}] +[division_end] +[division_start virtchannel_transform] +[item modules/virtchannel_transform/adler32.man tcl::transform::adler32 {Adler32 transformation}] +[item modules/virtchannel_transform/base64.man tcl::transform::base64 {Base64 encoding transformation}] +[item modules/virtchannel_transform/counter.man tcl::transform::counter {Counter transformation}] +[item modules/virtchannel_transform/crc32.man tcl::transform::crc32 {Crc32 transformation}] +[item modules/virtchannel_transform/hex.man tcl::transform::hex {Hexadecimal encoding transformation}] +[item modules/virtchannel_transform/identity.man tcl::transform::identity {Identity transformation}] +[item modules/virtchannel_transform/limitsize.man tcl::transform::limitsize {limiting input}] +[item modules/virtchannel_transform/observe.man tcl::transform::observe {Observer transformation, stream copy}] +[item modules/virtchannel_transform/otp.man tcl::transform::otp {Encryption via one-time pad}] +[item modules/virtchannel_transform/rot.man tcl::transform::rot rot-encryption] +[item modules/virtchannel_transform/spacer.man tcl::transform::spacer {Space insertation and removal}] +[item modules/virtchannel_transform/zlib.man tcl::transform::zlib {zlib (de)compression}] +[division_end] [division_start wip] [item modules/wip/wip.man wip {Word Interpreter}] [division_end] [division_start yaml] [item modules/yaml/huddle.man huddle {Create and manipulate huddle object}] ADDED support/devel/sak/localdoc/cmd.tcl Index: support/devel/sak/localdoc/cmd.tcl ================================================================== --- /dev/null +++ support/devel/sak/localdoc/cmd.tcl @@ -0,0 +1,21 @@ +# -*- tcl -*- +# Implementation of 'localdoc'. + +# Available variables +# * argv - Cmdline arguments +# * base - Location of sak.tcl = Top directory of Tcllib distribution +# * cbase - Location of all files relevant to this command. +# * sbase - Location of all files supporting the SAK. + +# ### + +package require sak::localdoc + +if {[llength $argv]} { + sak::localdoc::usage +} + +sak::localdoc::run + +## +# ### ADDED support/devel/sak/localdoc/help.txt Index: support/devel/sak/localdoc/help.txt ================================================================== --- /dev/null +++ support/devel/sak/localdoc/help.txt @@ -0,0 +1,8 @@ + + localdoc -- Generate documentation for website and installer. + + sak localdoc + + Convert all documentation into html and nroff, for use by the + installer, and the website. For the latter the results of the + conversion are stored in the repository itself. ADDED support/devel/sak/localdoc/localdoc.tcl Index: support/devel/sak/localdoc/localdoc.tcl ================================================================== --- /dev/null +++ support/devel/sak/localdoc/localdoc.tcl @@ -0,0 +1,89 @@ +# -*- tcl -*- +# sak::doc - Documentation facilities + +package require sak::util +package require sak::doc + +namespace eval ::sak::localdoc {} + +# ### +# API commands + +## ### ### ### ######### ######### ######### + +proc ::sak::localdoc::usage {} { + package require sak::help + puts stdout \n[sak::help::on localdoc] + exit 1 +} + +proc ::sak::localdoc::run {} { + set noe [info nameofexecutable] + + # Relative path is necessary to handle possibility of fossil + # repository and website as child of a larger website. Absolute + # adressing may not point to our root, but the outer site. + #set nav /home + + # NOTE: This may not work for the deeper nested manpages. + # doc/tip/embedded/www/tcoc.html + #set nav ../../../../../home + + # Indeed, not working for the nested pages. + # Use absolute, for main location. + set nav /tcllib + + puts "Removing old documentation..." + file delete -force embedded + file mkdir embedded/man + file mkdir embedded/www + + puts "Reindex the documentation..." + sak::doc::imake __dummy__ + sak::doc::index __dummy__ + + puts "Generating manpages..." + exec 2>@ stderr >@ stdout $noe apps/dtplite \ + -exclude {*/doctools/tests/*} \ + -exclude {*/support/*} \ + -ext n \ + -o embedded/man \ + nroff . + + # Note: Might be better to run them separately. + # Note @: Or we shuffle the results a bit more in the post processing stage. + + set toc [string map { + .man .html + modules/ tcllib/files/modules/ + } [fileutil::cat support/devel/sak/doc/toc.txt]] + + puts "Generating HTML... Pass 1, draft..." + exec 2>@ stderr >@ stdout $noe apps/dtplite \ + -toc $toc \ + -nav Home $nav \ + -exclude {*/doctools/tests/*} \ + -exclude {*/support/*} \ + -merge \ + -o embedded/www \ + html . + + puts "Generating HTML... Pass 2, resolving cross-references..." + exec 2>@ stderr >@ stdout $noe apps/dtplite \ + -toc $toc \ + -nav Home $nav \ + -exclude {*/doctools/tests/*} \ + -exclude {*/support/*} \ + -merge \ + -o embedded/www \ + html . + + return +} + +# ### ### ### ######### ######### ######### + +package provide sak::localdoc 1.0 + +## +# ### ADDED support/devel/sak/localdoc/pkgIndex.tcl Index: support/devel/sak/localdoc/pkgIndex.tcl ================================================================== --- /dev/null +++ support/devel/sak/localdoc/pkgIndex.tcl @@ -0,0 +1,2 @@ +if {![package vsatisfies [package provide Tcl] 8.2]} return +package ifneeded sak::localdoc 1.0 [list source [file join $dir localdoc.tcl]] ADDED support/devel/sak/localdoc/topic.txt Index: support/devel/sak/localdoc/topic.txt ================================================================== --- /dev/null +++ support/devel/sak/localdoc/topic.txt @@ -0,0 +1,2 @@ +localdoc Generate html & nroff documentation for display + from the website, and the installer.